BackingMap (IBM WebSphere XD ObjectGrid API Specification)

Overview

Package

Class

Tree

Deprecated

Index

Help

IBM WebSphere Extended Deployment (XD)^TM, Release 6.1
ObjectGrid API Specification

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ibm.websphere.objectgrid
Interface BackingMap

All Superinterfaces:: ClientReplicableMap

public interface BackingMap
extends ClientReplicableMap
extends ClientReplicableMap

This is the public interface to the BackingMap. It is returned when a new Map is defined on the ObjectGrid. It allows the Map to be customized with various plugins or by setting properties. The defaults are:

No external Evictor, but an internal time-based evictor is provided by default
No Loader
No MapEventListeners
No MapIndexPlugins
An internal ObjectTransformer
An internal OptimisticCallback
Key is not copied
A value CopyMode of CopyMode.COPY_ON_READ_AND_COMMIT
A LockStrategy of LockStrategy.OPTIMISTIC
A default lock timeout
null values are supported
A default number of buckets
A default number of lock buckets
Synchronous preload
Read/write map by default
A TimeToLive of 0 (indicating unlimited time)
A TtlEvictor type of TTLType.NONE

Since:: WAS XD 6.0

Nested Class Summary

Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.ClientReplicableMap
`ClientReplicableMap.Mode`

Field Summary
`static int`	`CLIENT` Constant used to indicate this map is a client to a server map
`static int`	`DEFAULT_LOCK_TIMEOUT` Default lock timeout used if `setLockTimeout(int)` is not invoked.
`static int`	`DEFAULT_NUMBER_OF_BUCKETS` Default number of lock buckets used if `setNumberOfBuckets(int)` is not invoked.
`static int`	`DEFAULT_NUMBER_OF_LOCK_BUCKETS` Default number of lock buckets used if `setNumberOfLockBuckets(int)` is not invoked.
`static int`	`LOCAL` Constant used to indicate this map is not a distributed map.
`static int`	`SERVER` Constant used to indicate this map is a server map.

Fields inherited from interface com.ibm.websphere.objectgrid.ClientReplicableMap
`CONTINUOUS_REPLICATION, NONE, SNAPSHOT_REPLICATION`

Method Summary
`void`	`addMapEventListener(MapEventListener eventListener)` Adds a `MapEventListener` to this `BackingMap`.
`void`	`addMapIndexPlugin(MapIndexPlugin index)` Adds an `MapIndexPlugin` to this Map.
`void`	`createDynamicIndex(MapIndexPlugin index, DynamicIndexCallback dynamicIndexCallback)` Creates a dynamic index on the `BackingMap`.
`void`	`createDynamicIndex(java.lang.String name, boolean isRangeIndex, java.lang.String attributeName, DynamicIndexCallback dynamicIndexCallback)` Creates a dynamic index on the `BackingMap`.
`boolean`	`getCopyKey()` Gets whether keys are copied for this `BackingMap`.
`CopyMode`	`getCopyMode()` Gets the `CopyMode` being used by this `BackingMap`.
`EntityMetadata`	`getEntityMetadata()` Retreive the metadata for the entity associated with this backing map.
`Evictor`	`getEvictor()` Gets the `Evictor` being used by this BackingMap.
`Loader`	`getLoader()` Gets the Loader being used by this `BackingMap`.
`LockStrategy`	`getLockStrategy()` Gets the `LockStrategy` object being used by this `BackingMap`.
`int`	`getLockTimeout()` Gets the lock timeout value used by the lock manager for this `BackingMap`.
`java.util.List`	`getMapEventListeners()` Gets the current list of `MapEventListener`s.
`java.util.List`	`getMapIndexPlugins()` Returns the current list of `MapIndexPlugin` objects for this BackingMap.
`int`	`getMapType()` Returns the type of BackingMap.
`java.lang.String`	`getName()` Gets the name of the `BackingMap`.
`boolean`	`getNullValuesSupported()` Gets whether this `BackingMap` supports `null` values or not.
`int`	`getNumberOfBuckets()` Gets the number of buckets defined for this `BackingMap`.
`int`	`getNumberOfLockBuckets()` Gets the number of lock buckets defined for the hash map used by lock manager for this backing map.
`ObjectGrid`	`getObjectGrid()` Gets the `ObjectGrid` that owns this `BackingMap`.
`ObjectTransformer`	`getObjectTransformer()` Gets the `ObjectTransformer` object being used by this `BackingMap` and/or `Loader`.
`OptimisticCallback`	`getOptimisticCallback()` Gets the `OptimisticCallback` being used by this `BackingMap` and/or `Loader` or `null` if the LockStrategy is not optimistic.
`int`	`getPartitionId()` Gets the partition identifier being used by this `BackingMap`.
`PartitionManager`	`getPartitionManager()` Allows access to the `PartitionManager` that is defined for this `BackingMap`.
`boolean`	`getPreLoadMode()` Returns whether this `BackingMap` will be asynchronously preloaded or not if a `Loader` is set.
`boolean`	`getReadOnly()` Retrieves the map type.
`int`	`getTimeToLive()` Gets the number of seconds for an entry to live.
`TTLType`	`getTtlEvictorType()` Gets how expiration time of a `BackingMap` entry is computed.
`void`	`removeDynamicIndex(java.lang.String name)` Removes a dynamic index on the `BackingMap`.
`void`	`removeMapEventListener(MapEventListener eventListener)` Removes a `MapEventListener` from this `BackingMap`.
`void`	`setCopyKey(boolean copy)` Sets whether or not the key needs to be copied when a map entry is created.
`void`	`setCopyMode(CopyMode mode, java.lang.Class valueInterface)` Sets the `CopyMode`.
`void`	`setEvictor(Evictor e)` Associates an `Evictor` with this `BackingMap`.
`void`	`setLoader(Loader loader)` Associates a `Loader` with this `BackingMap`.
`void`	`setLockStrategy(LockStrategy lockStrategy)` Sets the `LockStrategy`.
`void`	`setLockTimeout(int seconds)` Sets the lock timeout used by the lock manager for this `BackingMap`.
`void`	`setMapEventListeners(java.util.List eventListenerList)` Sets the list of `MapEventListener` objects.
`void`	`setMapIndexPlugins(java.util.List indexList)` Sets the list of `MapIndexPlugin` objects for this BackingMap.
`void`	`setNullValuesSupported(boolean nullValuesSupported)` Sets whether this `BackingMap` supports `null` values.
`void`	`setNumberOfBuckets(int numBuckets)` Sets the number of buckets used by this `BackingMap`.
`void`	`setNumberOfLockBuckets(int numBuckets)` Sets the number of lock buckets used by the lock manager for this `BackingMap`.
`void`	`setObjectTransformer(ObjectTransformer t)` Sets the ObjectTransformer object for use by this `BackingMap` and/or `Loader`.
`void`	`setOptimisticCallback(OptimisticCallback checker)` Sets the `OptimisticCallback`.
`void`	`setPreloadMode(boolean async)` Sets the preload mode if a `Loader` is set for this `BackingMap`.
`void`	`setReadOnly(boolean readOnlyEnabled)` Sets the map type of this `BackingMap`.
`void`	`setTimeToLive(int seconds)` Sets "time to live" of each map entry in seconds.
`void`	`setTtlEvictorType(TTLType type)` Sets how expiration time of a `BackingMap` entry is computed.

Methods inherited from interface com.ibm.websphere.objectgrid.ClientReplicableMap
`disableClientReplication, enableClientReplication, getReplicationMode`

Field Detail

DEFAULT_LOCK_TIMEOUT

static final int DEFAULT_LOCK_TIMEOUT

Default lock timeout used if setLockTimeout(int) is not invoked.

See Also:: Constant Field Values

DEFAULT_NUMBER_OF_BUCKETS

static final int DEFAULT_NUMBER_OF_BUCKETS

Default number of lock buckets used if setNumberOfBuckets(int) is not invoked.

See Also:: Constant Field Values

DEFAULT_NUMBER_OF_LOCK_BUCKETS

static final int DEFAULT_NUMBER_OF_LOCK_BUCKETS

Default number of lock buckets used if setNumberOfLockBuckets(int) is not invoked.

See Also:: Constant Field Values

LOCAL

static final int LOCAL

Constant used to indicate this map is not a distributed map.

Since:: WAS XD 6.1
See Also:: getMapType(), Constant Field Values

SERVER

static final int SERVER

Constant used to indicate this map is a server map.

Since:: WAS XD 6.1
See Also:: getMapType(), Constant Field Values

CLIENT

static final int CLIENT

Constant used to indicate this map is a client to a server map

Since:: WAS XD 6.1
See Also:: getMapType(), Constant Field Values

Method Detail

getName

java.lang.String getName()

Gets the name of the BackingMap.

Returns:: value specified when BackingMap was created.

setEvictor

void setEvictor(Evictor e)

Associates an Evictor with this BackingMap.

An Evictor aids with cleaning up the cache based on whatever algorithm is desired (LRU, LFU, etc). Passing null to this method removes a previously set Evictor object from an earlier invocation of this method.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:: e - Evictor instance
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: Evictor, ObjectGrid.initialize(), ObjectGrid.getSession()

getEvictor

Evictor getEvictor()

Gets the Evictor being used by this BackingMap.

Returns:: the argument that was passed to the setEvictor(Evictor) method of this interface or null if setEvictor was not previously called for this BackingMap object.
See Also:: Evictor, setEvictor(Evictor)

setObjectTransformer

void setObjectTransformer(ObjectTransformer t)

Sets the ObjectTransformer object for use by this BackingMap and/or Loader.

An ObjectTransformer aids with the "serialization" of non-Serializable objects. It allows a custom copy function to be installed for more efficient object copy operations.

Parameters:: t - ObjectTransformer instance
Throws:: java.lang.IllegalArgumentException - if the passed in ObjectTransformer is null; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: ObjectTransformer, ObjectGrid.initialize(), ObjectGrid.getSession()

getObjectTransformer

ObjectTransformer getObjectTransformer()

Gets the ObjectTransformer object being used by this BackingMap and/or Loader.

Returns:: the argument that was passed to the setObjectTransformer(ObjectTransformer) method of this interface or the default ObjectTransformer object if the setObjectTransformer method was not previously called for this object.
See Also:: ObjectTransformer, setObjectTransformer(ObjectTransformer)

setOptimisticCallback

void setOptimisticCallback(OptimisticCallback checker)

Sets the OptimisticCallback.

The OptimisticCallback will be used to check the versions of cache entries during the commit phase. If no OptimisticCallback was previously set, a default OptimisticCallback will be used. For Entities, the default OptimisticCallback will use a version field that was specified in the entity metadata. For POJO objects or Entities that do not have a version field specified, the default OptimisticCallback uses the entire object as the version value. In order for it to work for POJO objects, the application's value object needs to have a useful equals(Object) method. If your application does not require versioning, but is using Optimistic locking, the NoVersioningOptimistCallback should be used.

Parameters:: checker - OptimisticCallback instance
Throws:: java.lang.IllegalArgumentException - if the passed in OptimisticCallback is null; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: OptimisticCallback, NoVersioningOptimisticCallback, LockStrategy.OPTIMISTIC, ObjectGrid.initialize(), ObjectGrid.getSession()

getOptimisticCallback

OptimisticCallback getOptimisticCallback()

Gets the OptimisticCallback being used by this BackingMap and/or Loader or null if the LockStrategy is not optimistic.

If no OptimisticCallback was previously set, a default OptimisticCallback will be used. For Entities, the default OptimisticCallback will use a version field that was specified in the entity metadata. For POJO objects or Entities that do not have a version field specified, the default OptimisticCallback uses the entire object as the version value. In order for it to work for POJO objects, the application's value object needs to have a useful equals(Object) method. If your application does not require versioning, but is using Optimistic locking, the NoVersioningOptimistCallback should be used.

Returns:: the argument that was passed to the setOptimisticCallback(OptimisticCallback) method of this interface or the default OptimisticCallback object if the setOptimisticCallback method was not previously called for this object. If Optimistic locking is not being used, this method will return null after ObjectGrid.initialize() has been invoked.
See Also:: NoVersioningOptimisticCallback, OptimisticCallback, LockStrategy.OPTIMISTIC, setOptimisticCallback(OptimisticCallback)

setLoader

void setLoader(Loader loader)

Associates a Loader with this BackingMap.

Only one Loader can be associated with a given BackingMap. Passing null to this method removes a previously set Loader object from an earlier invocation of this method and indicates that this BackingMap is not associated with a Loader.

Parameters:: loader - Loader instance
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: Loader, ObjectGrid.initialize(), ObjectGrid.getSession()

getLoader

Loader getLoader()

Gets the Loader being used by this BackingMap.

Returns:: the argument that was passed to the setLoader(Loader) method of this interface or null if setLoader was not previously called for this object.
See Also:: Loader, setLoader(Loader)

setPreloadMode

void setPreloadMode(boolean async)

Sets the preload mode if a Loader is set for this BackingMap.

If the parameter is true then the Loader.preloadMap(Session, BackingMap) is invoked asynchronously; otherwise it blocks the execution when loading data so the cache is unavailable until preload completes. Preloading occurs during ObjectGrid initialization.

Parameters:: async - If this is true then the cache is loaded asynchronously otherwise it blocks and the cache is unavailable until preload completes.
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: Loader.preloadMap(Session, BackingMap)

getPreLoadMode

boolean getPreLoadMode()

Returns whether this BackingMap will be asynchronously preloaded or not if a Loader is set.

If true is returned then the Loader.preloadMap(Session, BackingMap) method is invoked asynchronously; otherwise it blocks the execution when loading data so the cache is unavailable until preload completes. Preloading occurs during ObjectGrid initialization.

Returns:: the argument that was passed to the setPreloadMode(boolean) method of this interface or false if setPreloadeMode was not previously called for this object.
See Also:: Loader.preloadMap(Session, BackingMap), setPreloadMode(boolean)

addMapIndexPlugin

void addMapIndexPlugin(MapIndexPlugin index)
                       throws IndexAlreadyDefinedException

Adds an MapIndexPlugin to this Map. This method assumes the index implementation was constructed with the name of the attribute to index. The name of the index is specified when the index is constructed.

Note, to avoid an IllegalStateException, this method must be called prior to ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:: index - The index implementation.
Throws:: IndexAlreadyDefinedException - if this index already exists.; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: MapIndexPlugin, ObjectGrid.initialize(), ObjectGrid.getSession()

getMapIndexPlugins

java.util.List getMapIndexPlugins()

Returns the current list of MapIndexPlugin objects for this BackingMap.

Returns:: The current list of MapIndexPlugins for this BackingMap. The list is empty if the addMapIndexPlugin(MapIndexPlugin) or setMapIndexPlugins(List) method was not previously called for this BackingMap.
See Also:: addMapIndexPlugin(MapIndexPlugin), setMapIndexPlugins(List)

setMapIndexPlugins

void setMapIndexPlugins(java.util.List indexList)

Sets the list of MapIndexPlugin objects for this BackingMap. If the BackingMap already has a List of MapIndexPlugin objects, that list is replaced by the List passed as an argument to the current invocation of this method.

Parameters:: indexList - A non-null reference to a List of MapIndexPlugin objects.
Throws:: java.lang.IllegalArgumentException - is thrown if indexList is null or the indexList contains either a null reference or an object that is not an instanceof MapIndexPlugin.
See Also:: MapIndexPlugin, ObjectGrid.initialize(), ObjectGrid.getSession()

setCopyMode

void setCopyMode(CopyMode mode,
                 java.lang.Class valueInterface)

Sets the CopyMode.

The CopyMode determines whether a get operation of an entry in the BackingMap returns the actual value, a copy of the value, or a proxy for the value. In the case of a proxy, the copy of the value does not occur unless a set method of the application provided value interface is invoked. It also determines that when a transaction is committed, whether a copy of the value object of an entry that was marked as dirty by the transaction is put into the BackingMap at commit time. The CopyMode does not specify if the object is copied when being read or written to a Loader. It is the responsibility of the implementor of a Loader to make copies as appropriate. The default CopyMode is CopyMode.COPY_ON_READ_AND_COMMIT.

Parameters:: mode - must be one of the final static variables defined in CopyMode. See CopyMode class for an explanation of each mode and how the valueInterface is used for CopyMode.COPY_ON_WRITE .; valueInterface - is a value interface Class object. A non-null valueInterface is required when mode is set to CopyMode.COPY_ON_WRITE. It is ignored for all other modes.
Throws:: java.lang.IllegalArgumentException - if mode is CopyMode.COPY_ON_WRITE and valueInterface parameter is null and CGLIB isn't in the classpath.; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: CopyMode, ObjectGrid.initialize(), ObjectGrid.getSession()

getCopyMode

CopyMode getCopyMode()

Gets the CopyMode being used by this BackingMap.

Returns:: the argument that was passed to the setCopyMode(CopyMode, Class) method of this interface or the default CopyMode object if setCopyMode was not previously called for this object.
See Also:: CopyMode, setCopyMode(CopyMode, Class)

setLockStrategy

void setLockStrategy(LockStrategy lockStrategy)

Sets the LockStrategy.

The locking strategy represented by the LockStrategy object determines if the internal ObjectGrid lock manager is used whenever a map entry is accessed by a transaction. The default strategy is LockStrategy.OPTIMISTIC.

Parameters:: lockStrategy - must be one of the final static variables defined in LockStrategy. See LockStrategy class for an explanation of each locking strategy.
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: LockStrategy, ObjectGrid.initialize(), ObjectGrid.getSession()

getLockStrategy

LockStrategy getLockStrategy()

Gets the LockStrategy object being used by this BackingMap.

Returns:: the argument that was passed to the setLockStrategy(LockStrategy) method of this interface or the default LockStrategy object if setLockStrategy was not previously called for this object.
See Also:: LockStrategy, setLockStrategy(LockStrategy)

setMapEventListeners

void setMapEventListeners(java.util.List eventListenerList)

Sets the list of MapEventListener objects.

If this BackingMap already has a List of MapEventListeners, that list is replaced by the List passed as an argument to the current invocation of this method. This method can be called before and after the ObjectGrid.initialize() method.

Parameters:: eventListenerList - A non-null reference to a List of MapEventListener objects.
Throws:: java.lang.IllegalArgumentException - is thrown if eventListenerList is null or the eventListenerList contains either a null reference or an object that is not an instance of MapEventListener.
See Also:: MapEventListener

getMapEventListeners

java.util.List getMapEventListeners()

Gets the current list of MapEventListeners.

Returns:: the current list of MapEventListener for this BackingMap.
See Also:: MapEventListener

addMapEventListener

void addMapEventListener(MapEventListener eventListener)

Adds a MapEventListener to this BackingMap.

Note, this method is allowed to be invoked before and after the ObjectGrid.initialize() method.

Parameters:: eventListener - A non-null reference to a MapEventListener to add to the list.
Throws:: java.lang.IllegalArgumentException - if eventListener is null.
See Also:: MapEventListener

removeMapEventListener

void removeMapEventListener(MapEventListener eventListener)

Removes a MapEventListener from this BackingMap.

Note, this method is allowed to be invoked before and after the ObjectGrid.initialize() method.

Parameters:: eventListener - A non-null reference to an event listener that was previously added by invoking either the addMapEventListener(MapEventListener) or setMapEventListeners(List) method of this interface.
Throws:: java.lang.IllegalArgumentException - if eventListener is null.
See Also:: MapEventListener, addMapEventListener(MapEventListener), setMapEventListeners(List)

getPartitionId

int getPartitionId()

Gets the partition identifier being used by this BackingMap.

Returns:: The 0-based index for the partition represented by this BackingMap instance. If there is only a single partition defined for this BackingMap object, a 0 will be returned (default).
Since:: WAS XD 6.0.1

setReadOnly

void setReadOnly(boolean readOnlyEnabled)

Sets the map type of this BackingMap.

A map can be a read only map or a read/write map. Passing true as the parameter value will make this map a read only map; passing false as the parameter value will make this map a read/write map.

Parameters:: readOnlyEnabled - If set to true, this BackingMap will be a read only map. If false, the map will be a read/write map.
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.

getReadOnly

boolean getReadOnly()

Retrieves the map type.

Returns:: the argument that was passed to setReadOnly(boolean) method of this interface. True is returned if this a read only map. A return value of false implies that this is a read/write map. If setReadOnly was never called, the default return value is false.
See Also:: setReadOnly(boolean)

getObjectGrid

ObjectGrid getObjectGrid()

Gets the ObjectGrid that owns this BackingMap.

Returns:: the ObjectGrid instance that owns this BackingMap.
See Also:: ObjectGrid

setNumberOfBuckets

void setNumberOfBuckets(int numBuckets)

Sets the number of buckets used by this BackingMap.

The BackingMap implementation uses a hash map for its implementation. If there are a lot of entries in the BackingMap then more buckets means better performance because the risk of collisions is lower as the number of buckets grows. More buckets also means more concurrency. If number of buckets is 0, no entries will be stored in the map, but the appropriate ObjectGrid and BackingMap plugins will still be called.

Once the ObjectGrid is initialized this parameter cannot be changed. Therefore, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:: numBuckets - The number of buckets to use.
Throws:: java.lang.IllegalArgumentException - if numBuckets is less than 0.; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: ObjectGrid.initialize(), ObjectGrid.getSession()

getNumberOfBuckets

int getNumberOfBuckets()

Gets the number of buckets defined for this BackingMap.

Returns:: the same value passed to the setNumberOfBuckets(int) method or DEFAULT_NUMBER_OF_BUCKETS if setNumberOfBuckets was never called.
See Also:: setNumberOfBuckets(int), DEFAULT_NUMBER_OF_BUCKETS

setNumberOfLockBuckets

void setNumberOfLockBuckets(int numBuckets)

Sets the number of lock buckets used by the lock manager for this BackingMap.

When LockStrategy.OPTIMISTIC or LockStrategy.PESSIMISTIC is used for this BackingMap, a lock manager is created for the BackingMap. The lock manager uses a hash map to keep track of entries that are locked by 1 or more transactions. If there are a lot of entries in the hash map, then more lock buckets means better performance as the risk of collisions is lower as the number of buckets grows. More lock buckets also means more concurrency. When the lock strategy is LockStrategy.NONE, no lock manager is used by this BackingMap. In this case, a call to this method does nothing.

Once the ObjectGrid is initialized, the number of lock buckets cannot be changed. Therefore, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:: numBuckets - The number of lock buckets to use.
Throws:: java.lang.IllegalArgumentException - if numBuckets is less than 1.; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: LockStrategy, ObjectGrid.initialize(), ObjectGrid.getSession()

getNumberOfLockBuckets

int getNumberOfLockBuckets()

Gets the number of lock buckets defined for the hash map used by lock manager for this backing map.

Returns:: the same value passed to the setNumberOfLockBuckets(int) method or DEFAULT_NUMBER_OF_LOCK_BUCKETS if setNumberOfLockBuckets was never called.
See Also:: setNumberOfLockBuckets(int), DEFAULT_NUMBER_OF_LOCK_BUCKETS

setLockTimeout

void setLockTimeout(int seconds)

Sets the lock timeout used by the lock manager for this BackingMap.

When LockStrategy.OPTIMISTIC or LockStrategy.PESSIMISTIC is used for this BackingMap, a lock manager is created for the BackingMap. To prevent deadlocks from occuring, the lock manager has a default timeout value for waiting for a lock to be granted. If this timeout limit is exceeeded, a LockTimeoutException is thrown. The default value of DEFAULT_LOCK_TIMEOUT should be sufficient for most applications, but on a heavily loaded system, a timeout may occur when no deadlock exists. In that case, this method can be used to increase the lock timeout value from the default to whatever is desired to prevent false timeout exceptions from occuring. When the lock strategy is LockStrategy.NONE, no lock manager is used by this BackingMap. In this case, a call to this method does nothing. A lock timeout value of zero indicates to not wait for the lock if it is not immediately available.

Once the lock manager is initialized, the lock timeout value cannot be changed. Therefore, to avoid an IllegalStateException, this method must be called prior to ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application. When an entry is fetched the lock timeout can be changed for a given transaction using ObjectMap.setLockTimeout(int)

Parameters:: seconds - is the lock timeout value to use in seconds.
Throws:: java.lang.IllegalArgumentException - if seconds is less than 0.; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: DEFAULT_LOCK_TIMEOUT, LockStrategy, LockTimeoutException, ObjectGrid.initialize(), ObjectGrid.getSession(), ObjectMap.setLockTimeout(int)

getLockTimeout

int getLockTimeout()

Gets the lock timeout value used by the lock manager for this BackingMap.

Returns:: the same value passed to the setLockTimeout(int) method or DEFAULT_LOCK_TIMEOUT if setLockTimeout was never called.
See Also:: DEFAULT_LOCK_TIMEOUT, setLockTimeout(int)

setNullValuesSupported

void setNullValuesSupported(boolean nullValuesSupported)

Sets whether this BackingMap supports null values.

If null values are supported, users need to be careful when a get operation returns a null reference. It could be due to the fact that the key is not found in the BackingMap, or that the value in the BackingMap is null. To determine if a key was not found, or the value is null, the containsKey method can be used.

Parameters:: nullValuesSupported - If set to true, null values are supported; otherwise null values are not supported.
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: ObjectGrid.initialize(), ObjectGrid.getSession(), ObjectMap.containsKey(Object)

getNullValuesSupported

boolean getNullValuesSupported()

Gets whether this BackingMap supports null values or not.

Returns:: the same value passed to the setNullValuesSupported(boolean) method or the default value of true if setNullValuesSupported was never called.
See Also:: setNullValuesSupported(boolean)

setCopyKey

void setCopyKey(boolean copy)

Sets whether or not the key needs to be copied when a map entry is created.

Copying the key object allows the application to use the same key object for each ObjectMap operation. The application changes the key object state prior to each ObjectMap operation so that it can work with different entries using the same key object. If a separate key object is used for each entry, then there is no reason to copy the key object. This attribute allows an application to make the tradeoff of copying key object versus using more memory as a result of separate key object used by the application for each entry. If this method is not called, then the default of false is used (e.g. the key is NOT copied).

Parameters:: copy - If true is specified, then this BackingMap uses the ObjectTransformer.copyKey(Object) method to copy the key object when necessary.
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: ObjectGrid.initialize(), ObjectGrid.getSession(), ObjectTransformer.copyKey(Object)

getCopyKey

boolean getCopyKey()

Gets whether keys are copied for this BackingMap.

Returns:: the same value passed to the setCopyKey(boolean) method or the default value of false if setCopyKey was never called.
See Also:: setCopyKey(boolean)

setTimeToLive

void setTimeToLive(int seconds)

Sets "time to live" of each map entry in seconds.

If this method is not called, the lifetime of an entry is forever (or until the application explicitly removes or invalidates the entry, or a user defined Evictor evicts the entry). Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:: seconds - the number of seconds a map entry is allowed to live in map before being evicted.
Throws:: java.lang.IllegalArgumentException - if seconds is less than 0.; java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: setTtlEvictorType(TTLType), ObjectMap.setTimeToLive(int), ObjectGrid.initialize(), ObjectGrid.getSession()

getTimeToLive

int getTimeToLive()

Gets the number of seconds for an entry to live.

This value returned is in seconds and 0 indicates forever.

Returns:: the same value passed to the setTimeToLive(int) method or 0 if setLockTimeout was never called.
See Also:: setTimeToLive(int)

setTtlEvictorType

void setTtlEvictorType(TTLType type)

Sets how expiration time of a BackingMap entry is computed.

If this method is not called, TTLType.NONE is used to indicate the map entry has no expiration time (e.g. is allowed to live until explicitly removed or invalidated by the application, or evicted by a user defined Evictor).

Parameters:: type - must be one of the public constants declared in the TTLType class.
Throws:: java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:: TTLType, ObjectGrid.initialize(), ObjectGrid.getSession()

getTtlEvictorType

TTLType getTtlEvictorType()

Gets how expiration time of a BackingMap entry is computed.

Returns:: the TTLType that was passed to the setTtlEvictorType(TTLType) or TTLType.NONE if setTtlEvictorType was never called.
See Also:: setTtlEvictorType(TTLType), TTLType

createDynamicIndex

void createDynamicIndex(java.lang.String name,
                        boolean isRangeIndex,
                        java.lang.String attributeName,
                        DynamicIndexCallback dynamicIndexCallback)
                        throws IndexAlreadyDefinedException,
                               java.lang.IllegalArgumentException

Creates a dynamic index on the BackingMap.

When security is enabled, this method requires a ServerMapPermission with action "dynamicIndex" when creating a dynamic index on a server from a client process. Refer to ServerMapPermission for more permission details.

Parameters:: name - the name of the index. The name can not be null or a zero length string.; isRangeIndex - Indicate whether to create a MapRangeIndex or a MapIndex. If set to true, the index will be a type of MapRangeIndex.; attributeName - The name of the attribute to be indexed. The attributeName can not be null or a zero length string.; dynamicIndexCallback - The callback that will invoke upon dynamic index events. The dynamicIndexCallback is optional and can be null.
Throws:: java.lang.IllegalArgumentException - if name or attributeName is null or a zero length string.; IndexAlreadyDefinedException - if a MapIndexPlugin with the specified name already exists.
Since:: WAS XD 6.0.1
See Also:: MapIndex, MapIndexPlugin, MapRangeIndex, ObjectMap.getIndex(String)

createDynamicIndex

void createDynamicIndex(MapIndexPlugin index,
                        DynamicIndexCallback dynamicIndexCallback)
                        throws IndexAlreadyDefinedException,
                               java.lang.IllegalArgumentException

Creates a dynamic index on the BackingMap.

Parameters:: index - The index implementation. The index can not be null.; dynamicIndexCallback - The callback that will invoke upon dynamic index events. The dynamicIndexCallback is optional and can be null.
Throws:: java.lang.IllegalArgumentException - if index is null or index.getName() returns null or a zero length string.; IndexAlreadyDefinedException - if a MapIndexPlugin with the specified name already exists.
Since:: WAS XD 6.0.1
See Also:: MapIndexPlugin, ObjectMap.getIndex(String)

removeDynamicIndex

void removeDynamicIndex(java.lang.String name)
                        throws IndexUndefinedException,
                               java.lang.IllegalArgumentException

Removes a dynamic index on the BackingMap.

When security is enabled, this method requires a ServerMapPermission with action "dynamicIndex" when removing a dynamic index on a server from a client process. Refer to ServerMapPermission for more permission details.

Parameters:: name - the name of the index. The name can not be null.
Throws:: java.lang.IllegalArgumentException - if name is null.; IndexUndefinedException - if a MapIndexPlugin with the specified name does not exists.
Since:: WAS XD 6.0.1
See Also:: createDynamicIndex(MapIndexPlugin, DynamicIndexCallback), createDynamicIndex(String, boolean, String, DynamicIndexCallback)

getPartitionManager

PartitionManager getPartitionManager()

Allows access to the PartitionManager that is defined for this BackingMap. This access may be useful for

Loaders during
 Loader.preloadMap(Session, BackingMap) processing (to properly partition
 the data to be loaded).




Returns:
PartitionManager associated with this BackingMap.
Since:
  WAS XD 6.0.1
See Also:
PartitionManager, 
Loader.preloadMap(Session, BackingMap)





getEntityMetadata
EntityMetadata getEntityMetadata()

Retreive the metadata for the entity associated with this backing map.






Returns:
the EntityMetadata if an entity is associated with this backing map or null if there is no
 entity associated with this backing map.
Since:
  WAS XD 6.1






getMapType
int getMapType()

Returns the type of BackingMap.
 
 The return value is equivalent to one of the constants declared on this interface,
 LOCAL, SERVER, or CLIENT.






Returns:
the map type
Since:
  WAS XD 6.1















  
      Overview 
      Package 
    Class 
      Tree 
      Deprecated 
      Index 
      Help 
  



IBM WebSphere Extended Deployment (XD)^TM, Release 6.1
ObjectGrid API Specification





 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD






© Copyright International Business Machines Corp 2005-2007. All rights reserved.

com.ibm.websphere.objectgrid Interface BackingMap

DEFAULT_LOCK_TIMEOUT

DEFAULT_NUMBER_OF_BUCKETS

DEFAULT_NUMBER_OF_LOCK_BUCKETS

LOCAL

SERVER

CLIENT

getName

setEvictor

getEvictor

setObjectTransformer

getObjectTransformer

setOptimisticCallback

getOptimisticCallback

setLoader

getLoader

setPreloadMode

getPreLoadMode

addMapIndexPlugin

getMapIndexPlugins

setMapIndexPlugins

setCopyMode

getCopyMode

setLockStrategy

getLockStrategy

setMapEventListeners

getMapEventListeners

addMapEventListener

removeMapEventListener

getPartitionId

setReadOnly

getReadOnly

getObjectGrid

setNumberOfBuckets

getNumberOfBuckets

setNumberOfLockBuckets

getNumberOfLockBuckets

setLockTimeout

getLockTimeout

setNullValuesSupported

getNullValuesSupported

setCopyKey

getCopyKey

setTimeToLive

getTimeToLive

setTtlEvictorType

getTtlEvictorType

createDynamicIndex

createDynamicIndex

removeDynamicIndex

getPartitionManager

getEntityMetadata

getMapType

com.ibm.websphere.objectgrid
Interface BackingMap