Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.openjpa.datacache
Interface DataCache

All Superinterfaces:
  Closeable

All Known Implementing Classes:
  AbstractDataCache, ConcurrentDataCache, DelegatingDataCache

    public interface DataCache

extends Closeable

Interface that must be implemented by any level 2 cache used by OpenJPA. Most data caches will choose to implement the `Configurable` interface as well so that they will be given the system configuration just after construction. Implementations should take care not to return timed out data.

Author:
  Patrick Linskey, Abe White
See Also:
  `AbstractDataCache`, `DataCachePCData.isTimedOut()`

Field Summary
`static String` | `NAME_DEFAULT` The name of the default data cache: `default`

Method Summary
`void` | `addExpirationListener(ExpirationListener listen)` Add a new expiration event listener to this cache.
`void` | `clear()` Remove all data from this cache.
`void` | `close()` Free the resources used by this cache.
`void` | `commit(Collection additions, Collection newUpdates, Collection existingUpdates, Collection deletes)` Perform a batch update of the cache.
`boolean` | `contains(Object oid)` Returns `true` if this cache contains data corresponding to `oid`; otherwise returns `false`.
`BitSet` | `containsAll(Collection oids)` Returns the indexes of the oids in this cache.
`DataCachePCData` | `get(Object oid)` Return the cached object for the given oid.
`String` | `getName()` Returns a string name that can be used by end-user-visible code to identify this cache.
`void` | `initialize(DataCacheManager manager)` Initialize any resources associated with the given `DataCacheManager`.
`boolean` | `pin(Object oid)` Pin the value stored under `oid` into the cache.
`void` | `pinAll(Class cls, boolean subs)` Pin all oids for the given type.
`BitSet` | `pinAll(Collection oids)` Pin all oids to the cache.
`DataCachePCData` | `put(DataCachePCData value)` Set the cached value for the given instance.
`DataCachePCData` | `remove(Object oid)` Remove the value stored under the given oid.
`void` | `removeAll(Class cls, boolean subclasses)` Evict all values of a specified type.
`BitSet` | `removeAll(Collection oids)` Remove the values stored under the given oids.
`boolean` | `removeExpirationListener(ExpirationListener listen)` Remove an expiration event listener from this cache.
`void` | `setName(String name)` Sets a string name to be used to identify this cache to end-user needs.
`boolean` | `unpin(Object oid)` Unpin the value stored under `oid` from the cache.
`void` | `unpinAll(Class cls, boolean subs)` Unpin all oids associaed with the given type from the cache.
`BitSet` | `unpinAll(Collection oids)` Unpin all oids from the cache.
`void` | `update(DataCachePCData value)` Update the cached value for the given instance.
`void` | `writeLock()` Obtain a write lock on the cache.
`void` | `writeUnlock()` Release the write lock on the cache.

Field Detail

### NAME_DEFAULT

    static final String NAME_DEFAULT

  The name of the default data cache: `default`

  See Also:
    Constant Field Values

Method Detail

### getName

    String getName()

  Returns a string name that can be used by end-user-visible code to identify this cache.

  Since:
    0.2.5.0

### setName

    void setName(String name)

  Sets a string name to be used to identify this cache to end-user needs.

  Since:
    0.2.5.0

### initialize

    void initialize(DataCacheManager manager)

  Initialize any resources associated with the given `DataCacheManager`.

### commit

    void commit(Collection additions,
                Collection newUpdates,
                Collection existingUpdates,
                Collection deletes)

  Perform a batch update of the cache. Add all `DataCachePCData` objects in `additions` and in `newUpdates`, make the appropriate modifications to all DataCachePCDatas in `existingUpdates`, and delete all OIDs in `deletes`. All changes made to cached data must be made via this method. It is this method that is responsible for performing any side-effects that should happen on meaningful cache changes. Implementations should bear in mind that the `deletes` collection may contain oids that are also in the `additions` map. This is possible because it is valid for a user to delete an object with a particular oid and then add that object in the same batch.

  Parameters:
    `additions` - A collection of `DataCachePCData` objects. These represent data that have been newly created, and thus must be added to the cache.
    `newUpdates` - A collection of `DataCachePCData` objects. These represent data that have been modified but were not originally in the cache, and thus must be added to the cache.
    `existingUpdates` - A collection of `DataCachePCData` objects. These represent data that have been modified and were originally loaded from the cache. It is up to the cache implementation to decide if these values must be re-enlisted in the cache. Some caches may return live data from `get(java.lang.Object)` invocations, in which case these values need not be re-enlisted.
    `deletes` - A collection of object IDs that have been deleted and must therefore be dropped from the cache.

### contains

    boolean contains(Object oid)

  Returns `true` if this cache contains data corresponding to `oid`; otherwise returns `false`.

### containsAll

    BitSet containsAll(Collection oids)

  Returns the indexes of the oids in this cache.

### get

    DataCachePCData get(Object oid)

  Return the cached object for the given oid. Modifying the returned object may or may not change the cached value; the `update(org.apache.openjpa.datacache.DataCachePCData)` method should be used to re-cache any changed objects.

  Returns:
    the object matching the given oid, or null if none

### put

    DataCachePCData put(DataCachePCData value)

  Set the cached value for the given instance. This does not result in an update of other caches. Rather, it should only be used for loading clean data into the cache. Meaningful changes to the state of the cache should be made via the `commit(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection)` method.

  Returns:
    The previously cached value, or `null` if the value was not previously cached. See `Map.put(K, V)` for more information.

### update

    void update(DataCachePCData value)

  Update the cached value for the given instance. This does not result in an update of other caches. Rather, it should only be used for loading clean data into the cache. Meaningful changes to the state of the cache should be made via the `commit(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection)` method. A cache implementation may or may not return a live object from `get(java.lang.Object)` invocations. If an object retrieved from a `get(java.lang.Object)` operation needs to be updated, this method can be invoked instead of invoking `put(org.apache.openjpa.datacache.DataCachePCData)`. The DataCache implementation can then make optimizations based on how its `get(java.lang.Object)` method works.

### remove

    DataCachePCData remove(Object oid)

  Remove the value stored under the given oid. This does not result in an update of other caches. Rather, it should only be used for removing data in the cache. Meaningful changes to the state of the cache should be made via the `commit(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection)` method.

  Returns:
    The previously cached value, or `null` if the oid was not previously cached. See `Map.remove(java.lang.Object)` for more information.

### removeAll

    BitSet removeAll(Collection oids)

  Remove the values stored under the given oids.

  Returns:
    the indexes of the removed oids
  See Also:
    `remove(java.lang.Object)`

### removeAll

    void removeAll(Class cls,
                   boolean subclasses)

  Evict all values of a specified type.

### clear

    void clear()

  Remove all data from this cache. This does not result in an update of other caches. Rather, it should only be used for clearing the cache. Meaningful changes to the state of the cache should be made via the `commit(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection)` method.

### pin

    boolean pin(Object oid)

  Pin the value stored under `oid` into the cache. This method guarantees that `oid`'s value will not be dropped by the caching algorithm. This method does not affect the behavior of `remove(java.lang.Object)`.

  Returns:
    `true` if `oid`'s value was pinned into the cache; `false` if the oid is not in the cache.

### pinAll

    BitSet pinAll(Collection oids)

  Pin all oids to the cache.

  Returns:
    the indexes of the pinned oids
  See Also:
    `pin(java.lang.Object)`

### pinAll

    void pinAll(Class cls,
                boolean subs)

  Pin all oids for the given type.

  Parameters:
    `subs` - Whether to include subclasses.

### unpin

    boolean unpin(Object oid)

  Unpin the value stored under `oid` from the cache. This method reverses a previous invocation of `pin(java.lang.Object)`. This method does not remove anything from the cache; it merely makes `oid`'s value a candidate for flushing from the cache.

  Returns:
    `true` if `oid`'s value was unpinned from the cache; `false` if the oid is not in the cache.

### unpinAll

    BitSet unpinAll(Collection oids)

  Unpin all oids from the cache.

  Returns:
    the indexes of the unpinned oids
  See Also:
    `unpin(java.lang.Object)`

### unpinAll

    void unpinAll(Class cls,
                  boolean subs)

  Unpin all oids associaed with the given type from the cache.

  Parameters:
    `subs` - Whether to include subclasses.

### writeLock

    void writeLock()

  Obtain a write lock on the cache.

### writeUnlock

    void writeUnlock()

  Release the write lock on the cache.

### addExpirationListener

    void addExpirationListener(ExpirationListener listen)

  Add a new expiration event listener to this cache.

  Since:
    0.2.5.0

### removeExpirationListener

    boolean removeExpirationListener(ExpirationListener listen)

  Remove an expiration event listener from this cache.

  Since:
    0.2.5.0

### close

    void close()

  Free the resources used by this cache.

  Specified by:
    `close` in interface `Closeable`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006 Apache Software Foundation. All Rights Reserved.