001    package org.apache.ojb.broker.cache;
002    
003    /* Copyright 2002-2005 The Apache Software Foundation
004     *
005     * Licensed under the Apache License, Version 2.0 (the "License");
006     * you may not use this file except in compliance with the License.
007     * 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    import org.apache.ojb.broker.Identity;
019    
020    /**
021     * The <code>ObjectCache</code> stores all Objects loaded by the
022     * {@link org.apache.ojb.broker.PersistenceBroker} from a DB.
023     * When the PersistenceBroker tries to get an Object by its Primary key values
024     * it first lookups the cache if the object has been already loaded and cached.
025     * <br/><br/>
026     * Using an ObjectCache has several advantages:
027     * - it increases performance as it reduces DB lookups.
028     * - it allows to perform circular lookups (as by crossreferenced objects)
029     * that would result in non-terminating loops without such a cache. This will be internally handled by OJB, no
030     * need to take care of this.
031     * - it maintains the uniqueness of objects as any Db row will be mapped to
032     * exactly one object.
033     * <br/><br/>
034     * This interface allows to have userdefined Cache implementations.
035     * The ObjectCacheFactory is responsible for generating cache instances.
036     * by default it uses the OJB {@link ObjectCacheDefaultImpl}.
037     * <br/><br/>
038     * <b>Note:</b> Each {@link org.apache.ojb.broker.PersistenceBroker} was
039     * associated with its own <code>ObjectCache</code> instance at creation
040     * time.
041     * <br/>
042     * {@link ObjectCacheFactory} is responsible for creating <code>ObjectCache</code>
043     * instances. To make the <code>ObjectCache</code> implementation work, a
044     * constructor with {@link org.apache.ojb.broker.PersistenceBroker} and
045     * {@link java.util.Properties} as arguments or only <code>PersistenceBroker</code>
046     * argument is needed.
047     *
048     * @author <a href="mailto:thma@apache.org">Thomas Mahler<a>
049     * @author <a href="mailto:armin@codeaulait.de">Armin Waibel<a>
050     *
051     * @version $Id: ObjectCache.java,v 1.1 2007-08-24 22:17:29 ewestfal Exp $
052     */
053    public interface ObjectCache
054    {
055        /**
056         * Used to cache objects by it's {@link org.apache.ojb.broker.Identity}.
057         *
058         * @param oid Identity of the object to cache.
059         * @param obj The object to cache.
060         */
061        public void cache(Identity oid, Object obj);
062    
063        /**
064         * Lookup object with Identity 'oid' in cache.
065         *
066         * @param oid Identity of the object to search for.
067         * @return The cached object or <em>null</em> if no matching object for
068         * specified {@link org.apache.ojb.broker.Identity} is found.
069         */
070        public Object lookup(Identity oid);
071    
072        /**
073         * Removes an Object from the cache.
074         *
075         * @param oid Identity of the object to be removed.
076         */
077        public void remove(Identity oid);
078    
079        /**
080         * Clear the cache.
081         */
082        public void clear();
083    }