001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     * 
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    package org.apache.commons.betwixt.strategy;
019    
020    import org.apache.commons.betwixt.expression.Context;
021    
022    /**
023     * Pluggable strategy for id storage management.
024     * It is possible to use this strategy for innovative
025     * active storage storage strategies as well as passive ones.
026     * For example, it is possible to have some beans map to 
027     * references without ever being fully mapped.
028     * 
029     * @author <a href="mailto:christian@wilde-welt.de">Christian Aust </a>
030     * @since 0.7
031     */
032    public abstract class IdStoringStrategy {
033    
034        /**
035         * Default storage strategy
036         * 
037         * @deprecated do not use this singleton since it 
038         * creates a static Map of all objects ever written. 
039         * Use {@link #createDefault} instead
040         */
041        public static IdStoringStrategy DEFAULT = new DefaultIdStoringStrategy();
042    
043        /**
044         * Factory method creates the default <code>Betwixt</code> implementation.
045         * The implementation created may vary if the default implementation changes.
046         * @return <code>IdStoringStrategy</code> used as default
047         * @since 0.8
048         */
049        public static IdStoringStrategy createDefault() {
050            return new DefaultIdStoringStrategy();
051        }
052            
053        
054        /**
055         * Retrieves a reference for the given instance.
056         * If a not null value is returned from this method,
057         * then the bean content will not be written.
058         * Use {@link org.apache.commons.betwixt.io.IDGenerator} strategy to vary the values
059         * written for a bean.
060         * 
061         * @param context
062         *            current context, not null
063         * @param bean
064         *            the instance, not null
065         * @return id as String when this bean has already been reference, 
066         * or null to indicate that this bean is not yet reference
067         */
068        public abstract String getReferenceFor(Context context, Object bean);
069    
070        /**
071         * Stores an instance reference for later retrieval.
072         * This method is shared by writing and reading.
073         *  
074         * @param context
075         *            current context, not null
076         * @param bean
077         *            the instance, not null
078         * @param id
079         *            the id to use
080         */
081        public abstract void setReference(Context context, Object bean, String id);
082    
083        /**
084         * Gets an object matching the given reference.
085         * @param context <code>Context</code>, not null
086         * @param id the reference id
087         * @return an bean matching the given reference, 
088         * or null if there is no bean matching the given reference
089         */
090        public abstract Object getReferenced(Context context, String id);
091        
092        /**
093         * Reset to the initial state.
094         *
095         */
096        public abstract void reset();
097        
098    }