01: package org.apache.ojb.broker.cache;
02:
03: /* Copyright 2002-2005 The Apache Software Foundation
04: *
05: * Licensed under the Apache License, Version 2.0 (the "License");
06: * you may not use this file except in compliance with the License.
07: * You may obtain a copy of the License at
08: *
09: * http://www.apache.org/licenses/LICENSE-2.0
10: *
11: * Unless required by applicable law or agreed to in writing, software
12: * distributed under the License is distributed on an "AS IS" BASIS,
13: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14: * See the License for the specific language governing permissions and
15: * limitations under the License.
16: */
17:
18: import org.apache.ojb.broker.Identity;
19:
20: /**
21: * The <code>ObjectCache</code> stores all Objects loaded by the
22: * {@link org.apache.ojb.broker.PersistenceBroker} from a DB.
23: * When the PersistenceBroker tries to get an Object by its Primary key values
24: * it first lookups the cache if the object has been already loaded and cached.
25: * <br/><br/>
26: * Using an ObjectCache has several advantages:
27: * - it increases performance as it reduces DB lookups.
28: * - it allows to perform circular lookups (as by crossreferenced objects)
29: * that would result in non-terminating loops without such a cache. This will be internally handled by OJB, no
30: * need to take care of this.
31: * - it maintains the uniqueness of objects as any Db row will be mapped to
32: * exactly one object.
33: * <br/><br/>
34: * This interface allows to have userdefined Cache implementations.
35: * The ObjectCacheFactory is responsible for generating cache instances.
36: * by default it uses the OJB {@link ObjectCacheDefaultImpl}.
37: * <br/><br/>
38: * <b>Note:</b> Each {@link org.apache.ojb.broker.PersistenceBroker} was
39: * associated with its own <code>ObjectCache</code> instance at creation
40: * time.
41: * <br/>
42: * {@link ObjectCacheFactory} is responsible for creating <code>ObjectCache</code>
43: * instances. To make the <code>ObjectCache</code> implementation work, a
44: * constructor with {@link org.apache.ojb.broker.PersistenceBroker} and
45: * {@link java.util.Properties} as arguments or only <code>PersistenceBroker</code>
46: * argument is needed.
47: *
48: * @author <a href="mailto:thma@apache.org">Thomas Mahler<a>
49: * @author <a href="mailto:armin@codeaulait.de">Armin Waibel<a>
50: *
51: * @version $Id: ObjectCache.java,v 1.9.2.3 2005/12/21 22:24:15 tomdz Exp $
52: */
53: public interface ObjectCache {
54: /**
55: * Used to cache objects by it's {@link org.apache.ojb.broker.Identity}.
56: *
57: * @param oid Identity of the object to cache.
58: * @param obj The object to cache.
59: */
60: public void cache(Identity oid, Object obj);
61:
62: /**
63: * Lookup object with Identity 'oid' in cache.
64: *
65: * @param oid Identity of the object to search for.
66: * @return The cached object or <em>null</em> if no matching object for
67: * specified {@link org.apache.ojb.broker.Identity} is found.
68: */
69: public Object lookup(Identity oid);
70:
71: /**
72: * Removes an Object from the cache.
73: *
74: * @param oid Identity of the object to be removed.
75: */
76: public void remove(Identity oid);
77:
78: /**
79: * Clear the cache.
80: */
81: public void clear();
82: }
|