org.glassfish.ha.store.api
Class BackingStore<K extends java.io.Serializable,V extends java.io.Serializable>

java.lang.Object
  org.glassfish.ha.store.api.BackingStore<K,V>

Direct Known Subclasses:

NoOpBackingStore

public abstract class BackingStore<K extends java.io.Serializable,V extends java.io.Serializable>
extends java.lang.Object

An object that stores a given value against an id. This class defines the set of operations that a container could perform on a store.

An instance of BackingStore is created by calling BackingStoreFactory.createBackingStore() method.

The BackingStore instance is created and used for storing data that belongs to a single application or container.

The store implementation must be thread safe.

Author:

Mahesh.Kannan@Sun.Com, Larry.White@Sun.Com

Constructor Summary

BackingStore()

Method Summary

void	close()
protected java.io.ObjectInputStream	createObjectInputStream(java.io.InputStream is)
protected java.io.ObjectOutputStream	createObjectOutputStream(java.io.OutputStream os)
abstract void	destroy() Called when the store is no longer needed.
java.util.Collection	findByCriteria(Criteria<V> criteria, StoreEntryEvaluator<K,V> eval) Find entries that satisfy the given Criteria.
protected BackingStoreConfiguration<K,V>	getBackingStoreConfiguration()
BackingStoreFactory	getBackingStoreFactory()
protected void	initialize(BackingStoreConfiguration<K,V> conf)
abstract V	load(java.lang.Object key, java.lang.String version) Load and return the data for the given id.
abstract void	remove(K key) Remove the association for the id.
void	removeByCriteria(Criteria<V> criteria, StoreEntryEvaluator<K,V> eval) Remove instances that meet the criteria.
int	removeExpired()
abstract int	removeExpired(long idleForMillis) Remove expired entries
abstract java.lang.String	save(K key, V value, boolean isNew) Save the value whose key is id.
abstract int	size() Get the current size of the store
java.util.Collection	synchronizeKeys(Criteria<V> criteria, StoreEntryEvaluator<K,V> eval, boolean eagerFetch) Cache the keys for the entries that satisfy the given Criteria.
abstract void	updateTimestamp(K key, long time)
java.lang.String	updateTimestamp(K key, java.lang.Long version, java.lang.Long accessTime, java.lang.Long maxIdleTime) Recomended way is to just do a save(k, v)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BackingStore

public BackingStore()

Method Detail

initialize

protected void initialize(BackingStoreConfiguration<K,V> conf)
                   throws BackingStoreException

Throws:

BackingStoreException

getBackingStoreConfiguration

protected BackingStoreConfiguration<K,V> getBackingStoreConfiguration()

load

public abstract V load(java.lang.Object key,
                       java.lang.String version)
                                             throws BackingStoreException

Load and return the data for the given id. The store is expected to return the largest ever version that was saved in the stored using the save() method.

Parameters:

key - the key whose value must be returned

Returns:

the value if this store contains it or null. The implementation must return the exact same type as that was passed to it in the save method.

Throws:

java.lang.NullPointerException - if the id is null

BackingStoreException - if the underlying store implementation encounters any exception

save

public abstract java.lang.String save(K key,
                                      V value,
                                      boolean isNew)
                               throws BackingStoreException

Save the value whose key is id. The store is NOT expected to throw an exception if isNew is false but the entry doesn't exist in the store. (This is possible in some implementations (like in-memory) where packets could be lost.)

Parameters:

key - the id

value - The Metadata to be stored

Returns:

A (possibly null) String indicating the instance name where the data was saved.

Throws:

BackingStoreException - if the underlying store implementation encounters any exception

remove

public abstract void remove(K key)
                     throws BackingStoreException

Remove the association for the id.

After this call, any call to load(id) must return null. In addition, any association between id and container extra params must also be removed.

Parameters:

key - the id of the Metadata

Throws:

BackingStoreException - if the underlying store implementation encounters any exception

updateTimestamp

public abstract void updateTimestamp(K key,
                                     long time)
                              throws BackingStoreException

Throws:

BackingStoreException

updateTimestamp

public java.lang.String updateTimestamp(K key,
                                        java.lang.Long version,
                                        java.lang.Long accessTime,
                                        java.lang.Long maxIdleTime)
                                 throws BackingStoreException

Recomended way is to just do a save(k, v)

Parameters:

key -

version -

accessTime -

maxIdleTime -

Throws:

BackingStoreException

removeExpired

public abstract int removeExpired(long idleForMillis)
                           throws BackingStoreException

Remove expired entries

Throws:

BackingStoreException

removeExpired

public int removeExpired()
                  throws BackingStoreException

Throws:

BackingStoreException

removeByCriteria

public void removeByCriteria(Criteria<V> criteria,
                             StoreEntryEvaluator<K,V> eval)
                      throws BackingStoreException

Remove instances that meet the criteria.

Throws:

BackingStoreException - if the underlying store implementation encounters any exception

size

public abstract int size()
                  throws BackingStoreException

Get the current size of the store

Returns:

the (approximate) number of entries in the store

Throws:

BackingStoreException - if the underlying store implementation encounters any exception

destroy

public abstract void destroy()
                      throws BackingStoreException

Called when the store is no longer needed. Must clean up and close any opened resources. The store must not be used after this call.

Throws:

BackingStoreException

findByCriteria

public java.util.Collection findByCriteria(Criteria<V> criteria,
                                           StoreEntryEvaluator<K,V> eval)

Find entries that satisfy the given Criteria. If criteria is null, then all entries in this store match the criteria. The store must do the following: 1. Execute the criteria and for each value that satisfy the criteria, must call 2. evaluator._getExtraParamCollectionFromManager(key, value) and if evaluator._getExtraParamCollectionFromManager() return true, then ; 3. if eagerFetch is true then all attributes of value are populated. Else only those whose loadLazily is set to false will be returned.

Parameters:

criteria - The criteria that must be satisfied. Can be null (in which case every value in this store is assumed to match the criteria)

eval - The StoreEntryEvaluator The evaluator whose _getExtraParamCollectionFromManager method must be invoked to further narrow the result.

close

public void close()
           throws BackingStoreException

Throws:

BackingStoreException

getBackingStoreFactory

public BackingStoreFactory getBackingStoreFactory()

synchronizeKeys

public java.util.Collection synchronizeKeys(Criteria<V> criteria,
                                            StoreEntryEvaluator<K,V> eval,
                                            boolean eagerFetch)

Cache the keys for the entries that satisfy the given Criteria. If criteria is null, then all entries in this store match the criteria. The store must do the following: 1. Execute the criteria and for each value that satisfy the criteria, must call 2. evaluator._getExtraParamCollectionFromManager(key, value) and if evaluator._getExtraParamCollectionFromManager() return true, then ; 3. if eagerFetch is true then all attributes of value are populated. Else only those whose loadLazily is set to false will be returned.

Parameters:

criteria - The criteria that must be satisfied. Can be null (in which case every value in this store is assumed to match the criteria)

eval - The StoreEntryEvaluator The evaluator whose _getExtraParamCollectionFromManager method must be invoked to further narrow the result.

createObjectOutputStream

protected java.io.ObjectOutputStream createObjectOutputStream(java.io.OutputStream os)
                                                       throws java.io.IOException

Throws:

java.io.IOException

createObjectInputStream

protected java.io.ObjectInputStream createObjectInputStream(java.io.InputStream is)
                                                     throws java.io.IOException

Throws:

java.io.IOException