001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.datacache;
020:
021: import java.util.BitSet;
022: import java.util.Collection;
023: import java.util.List;
024: import java.util.Map;
025:
026: import org.apache.openjpa.lib.util.Closeable;
027:
028: /**
029: * Interface that must be implemented by any level 2 cache used by
030: * OpenJPA. Most data caches will choose to implement the
031: * {@link org.apache.openjpa.lib.conf.Configurable} interface as well so that
032: * they will be given the system configuration just after construction.
033: * Implementations should take care not to return timed out data.
034: *
035: * @see AbstractDataCache
036: * @see DataCachePCData#isTimedOut
037: * @author Patrick Linskey
038: * @author Abe White
039: */
040: public interface DataCache extends Closeable {
041:
042: /**
043: * The name of the default data cache: <code>default</code>
044: */
045: public static final String NAME_DEFAULT = "default";
046:
047: /**
048: * Returns a string name that can be used by end-user-visible
049: * code to identify this cache.
050: *
051: * @since 0.2.5.0
052: */
053: public String getName();
054:
055: /**
056: * Sets a string name to be used to identify this cache to end-user needs.
057: *
058: * @since 0.2.5.0
059: */
060: public void setName(String name);
061:
062: /**
063: * Initialize any resources associated with the given
064: * {@link DataCacheManager}.
065: */
066: public void initialize(DataCacheManager manager);
067:
068: /**
069: * Perform a batch update of the cache. Add all {@link DataCachePCData}
070: * objects in <code>additions</code> and in
071: * <code>newUpdates</code>, make the appropriate modifications to
072: * all DataCachePCDatas in <code>existingUpdates</code>, and delete all
073: * OIDs in <code>deletes</code>.
074: * All changes made to cached data must be made via this
075: * method. It is this method that is responsible for performing
076: * any side-effects that should happen on meaningful cache changes.
077: * Implementations should bear in mind that the
078: * <code>deletes</code> collection may contain oids that are also
079: * in the <code>additions</code> map. This is possible because it
080: * is valid for a user to delete an object with a particular oid
081: * and then add that object in the same batch.
082: *
083: * @param additions A collection of {@link DataCachePCData} objects.
084: * These represent data that have been newly created,
085: * and thus must be added to the cache.
086: * @param newUpdates A collection of {@link DataCachePCData} objects.
087: * These represent data that have been modified but
088: * were not originally in the cache, and thus must be added to the cache.
089: * @param existingUpdates A collection of {@link DataCachePCData} objects.
090: * These represent data that have been modified and
091: * were originally loaded from the cache. It is
092: * up to the cache implementation to decide if
093: * these values must be re-enlisted in the cache.
094: * Some caches may return live data from {@link #get}
095: * invocations, in which case these values need not be re-enlisted.
096: * @param deletes A collection of object IDs that have been deleted
097: * and must therefore be dropped from the cache.
098: */
099: public void commit(Collection additions, Collection newUpdates,
100: Collection existingUpdates, Collection deletes);
101:
102: /**
103: * Returns <code>true</code> if this cache contains data
104: * corresponding to <code>oid</code>; otherwise returns
105: * <code>false</code>.
106: */
107: public boolean contains(Object oid);
108:
109: /**
110: * Returns the indexes of the oids in this cache.
111: */
112: public BitSet containsAll(Collection oids);
113:
114: /**
115: * Return the cached object for the given oid. Modifying the returned
116: * object may or may not change the cached value; the {@link #update}
117: * method should be used to re-cache any changed objects.
118: *
119: * @return the object matching the given oid, or null if none
120: */
121: public DataCachePCData get(Object oid);
122:
123: /**
124: * Set the cached value for the given instance. This does <em>not</em>
125: * result in an update of other caches. Rather, it should only be
126: * used for loading clean data into the cache. Meaningful changes
127: * to the state of the cache should be made via the {@link #commit} method.
128: *
129: * @return The previously cached value, or <code>null</code> if
130: * the value was not previously cached. See {@link Map#put}
131: * for more information.
132: */
133: public DataCachePCData put(DataCachePCData value);
134:
135: /**
136: * Update the cached value for the given instance. This does
137: * <em>not</em> result in an update of other caches. Rather, it should
138: * only be used for loading clean data into the cache. Meaningful changes
139: * to the state of the cache should be made via the {@link #commit} method.
140: * A cache implementation may or may not return a live object
141: * from {@link #get} invocations. If an object retrieved from a
142: * {@link #get} operation needs to be updated, this method can be
143: * invoked instead of invoking {@link #put}. The DataCache implementation
144: * can then make optimizations based on how its {@link #get} method works.
145: */
146: public void update(DataCachePCData value);
147:
148: /**
149: * Remove the value stored under the given oid. This does
150: * <em>not</em> result in an update of other caches. Rather, it
151: * should only be used for removing data in the cache.
152: * Meaningful changes to the state of the cache should be made
153: * via the {@link #commit} method.
154: *
155: * @return The previously cached value, or <code>null</code> if
156: * the oid was not previously cached. See {@link Map#remove}
157: * for more information.
158: */
159: public DataCachePCData remove(Object oid);
160:
161: /**
162: * Remove the values stored under the given oids.
163: *
164: * @return the indexes of the removed oids
165: * @see #remove
166: */
167: public BitSet removeAll(Collection oids);
168:
169: /**
170: * Evict all values of a specified type.
171: */
172: public void removeAll(Class cls, boolean subclasses);
173:
174: /**
175: * Remove all data from this cache. This does <em>not</em> result
176: * in an update of other caches. Rather, it should only be used
177: * for clearing the cache. Meaningful changes to the state of the
178: * cache should be made via the {@link #commit} method.
179: */
180: public void clear();
181:
182: /**
183: * Pin the value stored under <code>oid</code> into the cache.
184: * This method guarantees that <code>oid</code>'s value will not
185: * be dropped by the caching algorithm. This method does not
186: * affect the behavior of {@link #remove}.
187: *
188: * @return <code>true</code> if <code>oid</code>'s value was
189: * pinned into the cache; <code>false</code> if the oid is not in the cache.
190: */
191: public boolean pin(Object oid);
192:
193: /**
194: * Pin all oids to the cache.
195: *
196: * @return the indexes of the pinned oids
197: * @see #pin
198: */
199: public BitSet pinAll(Collection oids);
200:
201: /**
202: * Pin all oids for the given type.
203: * @param subs Whether to include subclasses.
204: */
205: public void pinAll(Class cls, boolean subs);
206:
207: /**
208: * Unpin the value stored under <code>oid</code> from the cache.
209: * This method reverses a previous invocation of {@link #pin}.
210: * This method does not remove anything from the cache; it merely
211: * makes <code>oid</code>'s value a candidate for flushing from the cache.
212: *
213: * @return <code>true</code> if <code>oid</code>'s value was
214: * unpinned from the cache; <code>false</code> if the
215: * oid is not in the cache.
216: */
217: public boolean unpin(Object oid);
218:
219: /**
220: * Unpin all oids from the cache.
221: *
222: * @return the indexes of the unpinned oids
223: * @see #unpin
224: */
225: public BitSet unpinAll(Collection oids);
226:
227: /**
228: * Unpin all oids associaed with the given type from the cache.
229: * @param subs Whether to include subclasses.
230: */
231: public void unpinAll(Class cls, boolean subs);
232:
233: /**
234: * Obtain a write lock on the cache.
235: */
236: public void writeLock();
237:
238: /**
239: * Release the write lock on the cache.
240: */
241: public void writeUnlock();
242:
243: /**
244: * Add a new expiration event listener to this cache.
245: *
246: * @since 0.2.5.0
247: */
248: public void addExpirationListener(ExpirationListener listen);
249:
250: /**
251: * Remove an expiration event listener from this cache.
252: *
253: * @since 0.2.5.0
254: */
255: public boolean removeExpirationListener(ExpirationListener listen);
256:
257: /**
258: * Free the resources used by this cache.
259: */
260: public void close();
261:
262: /**
263: * returns objects from the caches for a given list of keys
264: */
265: public Map getAll(List keys);
266: }
|