IBM WebSphereTM eXtreme Scale, Release 8.6
API Specification

com.ibm.websphere.objectgrid
Interface BackingMap

All Superinterfaces:
ClientReplicableMap

public interface BackingMap
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 plug-ins or by setting properties. The defaults are:

Since:
WAS XD 6.0, XC10

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
          Deprecated. Deprecated in 8.6. Buckets are no longer required. Use the isNearCacheEnabled() flag to disable the near cache in the ObjectGrid configuration XML file.
static int DEFAULT_NUMBER_OF_LOCK_BUCKETS
          Default number of lock buckets used if setNumberOfLockBuckets(int) is not invoked.
static String EVICTIONTRIGGER_MEMORY_USAGE_THRESHOLD
          The eviction trigger string constant to enable memory based eviction using memory usage threshold provided by the java.lang.management.MemoryPoolMXBean.
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(EventListener eventListener)
          Adds an EventListener to this BackingMap.
 void addMapEventListener(MapEventListener eventListener)
          Deprecated. This method is deprecated in version 7.1.1, use the addMapEventListener(EventListener) method.
 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(String name, boolean isRangeIndex, 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.
 String getEvictionTriggers()
          Returns the types of additional eviction triggers.
 Evictor getEvictor()
          Gets the Evictor being used by this BackingMap.
 OutputFormat getKeyOutputFormat()
          Retrieves the data format for all data access APIs that return cache keys.
 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.
 List getMapEventListeners()
          Gets the current list of EventListeners.
 List getMapIndexPlugins()
          Returns the current list of MapIndexPlugin objects for this BackingMap.
 String getMapSetName()
          Retrieves the name of the MapSet that this BackingMap is currently associated with.
 int getMapType()
          Returns the type of BackingMap.
 String getName()
          Gets the name of the BackingMap.
 boolean getNullValuesSupported()
          Gets whether this BackingMap supports null values or not.
 int getNumberOfBuckets()
          Deprecated. Deprecated in 8.6. Buckets are no longer required. Use the isNearCacheEnabled() flag to disable the near cache in the ObjectGrid configuration XML file.
 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.
 SerializerAccessor getSerializerAccessor()
          Retrieve the SerializerAccessor for this map.
 BackingMapLifecycleListener.State getState()
          Retrieve the current life cycle state of this map.
 TimeBasedDBUpdateConfig getTimeBasedDBUpdateConfig()
          Get the time-based database update configuration object.
 int getTimeToLive()
          Gets the number of seconds for an entry to live.
 TTLType getTtlEvictorType()
          Gets how expiration time of a BackingMap entry is computed.
 OutputFormat getValueOutputFormat()
          Retrieves the data format for all data access APIs that return cache values.
 String getWriteBehind()
          Get the write-behind parameter.
 boolean isNearCacheEnabled()
          If true, the client near cache is enabled for supported configurations.
 boolean isNearCacheInvalidationEnabled()
          If true, clients with local caches are automatically invalidated when the data grid map is updated.
 boolean isNearCacheLastAccessTTLSyncEnabled()
          If true, clients automatically send time-to-live access information to the remote data grid when accessed and the TTLType.LAST_ACCESS_TIME TTL evictor type is configured.
 void removeDynamicIndex(String name)
          Removes a dynamic index on the BackingMap.
 void removeMapEventListener(EventListener eventListener)
          Removes an EventListener from this BackingMap.
 void removeMapEventListener(MapEventListener eventListener)
          Provided for compatibility with old releases, use the removeMapEventListener(EventListener) method.
 void setCopyKey(boolean copy)
          Sets whether or not the key needs to be copied when a map entry is created.
 void setCopyMode(CopyMode mode, Class valueInterface)
          Sets the CopyMode.
 void setEvictionTriggers(String evictionTriggers)
          Sets the types of additional eviction triggers, all evictors for the backing map will use the provided set of triggers.
 void setEvictor(Evictor e)
          Associates an Evictor with this BackingMap.
 void setKeyOutputFormat(OutputFormat dataFormat)
          Sets the data format for all data access APIs that return cache keys.
 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(List eventListenerList)
          Deprecated. This method is deprecated in version 7.1.1. Use the addMapEventListener(EventListener) or removeMapEventListener(EventListener) methods. Plugins that implement the ObjectGridLifecycleListener interface are automatically registered with the grid. Using this method will remove those automatically added listeners.
 void setMapIndexPlugins(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)
          Deprecated. Deprecated in 8.6. Buckets are no longer required. Use the isNearCacheEnabled() flag to disable the near cache in the ObjectGrid configuration XML file.
 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 setTimeBasedDBUpdateConfig(TimeBasedDBUpdateConfig dbUpdateConfig)
          Set the time-based database update configuration object.
 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.
 void setValueOutputFormat(OutputFormat dataFormat)
          Sets the data format for all data access APIs that return cache values.
 void setWriteBehind(String writeBehindParam)
          Enable write-behind updates for this map.
 
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
Deprecated. Deprecated in 8.6. Buckets are no longer required. Use the isNearCacheEnabled() flag to disable the near cache in the ObjectGrid configuration XML file.
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

EVICTIONTRIGGER_MEMORY_USAGE_THRESHOLD

static final String EVICTIONTRIGGER_MEMORY_USAGE_THRESHOLD
The eviction trigger string constant to enable memory based eviction using memory usage threshold provided by the java.lang.management.MemoryPoolMXBean.

Since:
WAS XD 6.1.0.3
See Also:
setEvictionTriggers(String), 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

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.

An Evictor that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous evictor which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

An Evictor may also implement the BackingMapPlugin interface in order to receive enhanced BackingMap plug-in lifecycle method calls. The plug-in is then also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Parameters:
e - Evictor instance
Throws:
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.

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.

An ObjectTransformer that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous transformer which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

Parameters:
t - ObjectTransformer instance
Throws:
IllegalArgumentException - if the passed in ObjectTransformer is null
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.

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.

An OptimisticCallback that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous optimistic callback which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

Parameters:
checker - OptimisticCallback instance
Throws:
IllegalArgumentException - if the passed in OptimisticCallback is null
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.

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.

A loader that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous loader which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

A Loader may also implement the BackingMapPlugin interface in order to receive enhanced BackingMap plug-in lifecycle method calls. The plug-in is then also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Parameters:
loader - Loader instance
Throws:
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.

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:
async - If this is true then the cache is loaded asynchronously otherwise it blocks and the cache is unavailable until preload completes.
Throws:
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.

A MapIndexPlugin that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous index which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

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

getMapIndexPlugins

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(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.

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:
indexList - A non-null reference to a List of MapIndexPlugin objects.
Throws:
IllegalArgumentException - is thrown if indexList is null or the indexList contains either a null reference or an object that is not an instance of MapIndexPlugin.
See Also:
MapIndexPlugin, ObjectGrid.initialize(), ObjectGrid.getSession()

setCopyMode

void setCopyMode(CopyMode mode,
                 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.

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:
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 - the value interface Class object. Specify null in version 7.1 and later.
Throws:
IllegalArgumentException - if mode is CopyMode.COPY_ON_WRITE and valueInterface parameter is null and CGLIB isn't in the classpath.
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.

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:
lockStrategy - must be one of the final static variables defined in LockStrategy. See LockStrategy class for an explanation of each locking strategy.
Throws:
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

@Deprecated
void setMapEventListeners(List eventListenerList)
Deprecated. This method is deprecated in version 7.1.1. Use the addMapEventListener(EventListener) or removeMapEventListener(EventListener) methods. Plugins that implement the ObjectGridLifecycleListener interface are automatically registered with the grid. Using this method will remove those automatically added listeners.

Sets the list of EventListener objects.

If this BackingMap already has a List of EventListeners, 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 EventListener objects that are instances of BackingMapLifecycleListener or MapEventListener
Throws:
IllegalArgumentException - is thrown if eventListenerList is null, the eventListenerList contains either a null reference or an object that is not an instance of BackingMapLifecycleListener or MapEventListener
See Also:
EventListener, MapEventListener, BackingMapLifecycleListener, addMapEventListener(EventListener), removeMapEventListener(EventListener)

getMapEventListeners

List getMapEventListeners()
Gets the current list of EventListeners.

Returns:
the current list of EventListener objects for this BackingMap.
See Also:
EventListener, MapEventListener, BackingMapLifecycleListener

addMapEventListener

void addMapEventListener(EventListener eventListener)
Adds an EventListener to this BackingMap.

Note, this method is allowed to be invoked before and after the ObjectGrid.initialize() method. Backing map plug-ins (Loader, Evictor, MapIndexPlugin, ObjectTransformer, OptimisticCallback) that implement the ObjectGridLifecycleListener are automatically added as listeners when added to the BackingMap.

Parameters:
eventListener - A non-null reference to a EventListener to add to the list. The listener must be an instance of BackingMapLifecycleListener or MapEventListener
Throws:
IllegalArgumentException - if eventListener is null or not an instance of BackingMapLifecycleListener or MapEventListener
See Also:
EventListener, MapEventListener, BackingMapLifecycleListener

addMapEventListener

void addMapEventListener(MapEventListener eventListener)
Deprecated. This method is deprecated in version 7.1.1, use the addMapEventListener(EventListener) method.

Provided for compatibility with old releases, use the addMapEventListener(EventListener) method.

Parameters:
eventListener - A non-null reference to a EventListener to add to the list. The listener must be an instance of BackingMapLifecycleListener or MapEventListener

removeMapEventListener

void removeMapEventListener(EventListener eventListener)
Removes an EventListener from this BackingMap.

Note, this method is allowed to be invoked before and after the ObjectGrid.initialize() method. Backing map plug-ins (Loader, Evictor, MapIndexPlugin, ObjectTransformer, OptimisticCallback) that implement the ObjectGridLifecycleListener are automatically removed as listeners when removed from the ObjectGrid.

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

removeMapEventListener

void removeMapEventListener(MapEventListener eventListener)
Provided for compatibility with old releases, use the removeMapEventListener(EventListener) method.

Parameters:
eventListener - A non-null reference to an event listener that was previously added by invoking either the addMapEventListener(EventListener) or setMapEventListeners(List) method of this interface.

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.

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:
readOnlyEnabled - If set to true, this BackingMap will be a read only map. If false, the map will be a read/write map.
Throws:
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)
Deprecated. Deprecated in 8.6. Buckets are no longer required. Use the isNearCacheEnabled() flag to disable the near cache in the ObjectGrid configuration XML file.

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 plug-ins 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:
IllegalArgumentException - if numBuckets is less than 0.
IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
See Also:
ObjectGrid.initialize(), ObjectGrid.getSession()

getNumberOfBuckets

int getNumberOfBuckets()
Deprecated. Deprecated in 8.6. Buckets are no longer required. Use the isNearCacheEnabled() flag to disable the near cache in the ObjectGrid configuration XML file.

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:
IllegalArgumentException - if numBuckets is less than 1.
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 occurring, the lock manager has a default timeout value for waiting for a lock to be granted. If this timeout limit is exceeded, 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 occurring. 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:
IllegalArgumentException - if seconds is less than 0.
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.

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:
nullValuesSupported - If set to true, null values are supported; otherwise null values are not supported.
Throws:
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).

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:
copy - If true is specified, then this BackingMap uses the ObjectTransformer.copyKey(Object) method to copy the key object when necessary.
Throws:
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:
IllegalArgumentException - if seconds is less than 0.
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).

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:
type - must be one of the public constants declared in the TTLType class.
Throws:
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(String name,
                        boolean isRangeIndex,
                        String attributeName,
                        DynamicIndexCallback dynamicIndexCallback)
                        throws IndexAlreadyDefinedException,
                               IllegalArgumentException
Creates a dynamic index on the BackingMap.

Required Client Permission: ServerMapPermission.REPLICATE

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:
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,
                               IllegalArgumentException
Creates a dynamic index on the BackingMap.

Required Client Permission: ServerMapPermission.DYNAMIC_INDEX

A MapIndexPlugin that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous index which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

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:
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(String name)
                        throws IndexUndefinedException,
                               IllegalArgumentException
Removes a dynamic index on the BackingMap.

Required Client Permission: ServerMapPermission.DYNAMIC_INDEX

Parameters:
name - the name of the index. The name can not be null.
Throws:
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

setWriteBehind

void setWriteBehind(String writeBehindParam)
Enable write-behind updates for this map.

If a map is configured with write-behind loader update, the updates (could be insert type, remove type, or update type) to the backend are not instantly updated to the back end by calling the Loader.batchUpdate(TxID, LogSequence) method. Instead, they are queued in a write-behind queue map and updated to the back end periodically.

A write-behind update is pushed to the backend periodically within a different transaction from the one the update is made to ObjectGrid. When the write-behind update to the backend fails, for example, due to data integrity problem, it is too late to roll back the original ObjectGrid transaction. ObjectGrid will invalidate the entry and create an entry in a failed database update map. The name of this failed database update map is WriteBehindLoaderConstants.WRITE_BEHIND_FAILED_UPDATES_MAP_PREFIX+baseMapName. The key of the entry in this map is an auto-increment Integer, and the value is a LogElement. The logElement can be used to compensate the failure.

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:
writeBehindParam - a write-behind parameter consisting of a maximum update time and/or a maximum key update count. The format of the write-behind parameter is "T[time];C[count]", for example, "T100;C2000". "T100;C2000" means the loader will write to the back end when there are 2000 pending keys to be updated or when 100 seconds have passed since the last update. The default update time is 300 seconds and the default update key count is 1000. You can configure the update time only, the update key count only, or an empty string. The default value(s) will then be used in either of the above three cases. The default value is null to disable write-behind updates.
Throws:
IllegalArgumentException - if the write behind parameters are unknown or improperly formatted.
IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
Since:
WAS XD 6.1.0.3
See Also:
WriteBehindLoaderConstants

getWriteBehind

String getWriteBehind()
Get the write-behind parameter. A write-behind parameter consists of a maximum update time and/or a maximum key update count. The format of the write-behind parameter is "T[time];C[count]".

Returns:
the write-behind parameter. If the write-behind parameter is not set, null will be returned.
Since:
WAS XD 6.1.0.3
See Also:
setWriteBehind(String)

setTimeBasedDBUpdateConfig

void setTimeBasedDBUpdateConfig(TimeBasedDBUpdateConfig dbUpdateConfig)
Set the time-based database update configuration object.

When a time-based database update configuration object is set, a thread will be started automatically to update or invalidate the ObjectGrid maps with the latest updates (inserts and updates) from the database.

For a local ObjectGrid map, the thread will be launched in the same JVM. For a distributed ObjectGrid map in an ObjectGrid container, the thread will be automatically launched in partition 0. No database update thread will be started in a client side near cache.

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:
dbUpdateConfig - the time-based database update configuration object or null.
Throws:
IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
Since:
WAS XD 6.1.0.3

getTimeBasedDBUpdateConfig

TimeBasedDBUpdateConfig getTimeBasedDBUpdateConfig()
Get the time-based database update configuration object.

Returns:
the time-based database update configuration object or null if not set.
Since:
WAS XD 6.1.0.3
See Also:
setTimeBasedDBUpdateConfig(TimeBasedDBUpdateConfig)

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

getEvictionTriggers

String getEvictionTriggers()
Returns the types of additional eviction triggers.

The available eviction trigger strings are a described in the String constants in this interface that begin with the name: EVICTIONTRIGGER.

Returns:
a semicolon separated list of eviction triggers
Since:
WAS XD 6.1.0.3

setEvictionTriggers

void setEvictionTriggers(String evictionTriggers)
Sets the types of additional eviction triggers, all evictors for the backing map will use the provided set of triggers.

The available eviction trigger strings are a described in the String constants in this interface that begin with the name: EVICTIONTRIGGER.

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:
evictionTriggers - a semicolon separated list of eviction triggers
Throws:
IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.
IllegalArgumentException - if the eviction triggers are unknown or improperly formatted.
Since:
WAS XD 6.1.0.3

getMapSetName

String getMapSetName()
Retrieves the name of the MapSet that this BackingMap is currently associated with. A "null" return value indicates it is currently not associated with a MapSet. This method will only return a non null value for a client or server map.

Returns:
name of associated MapSet
Since:
7.1
See Also:
getMapType()

getSerializerAccessor

SerializerAccessor getSerializerAccessor()
Retrieve the SerializerAccessor for this map.

Returns:
the SerializerAccessor
Since:
7.1.1

getState

BackingMapLifecycleListener.State getState()
Retrieve the current life cycle state of this map.

Returns:
the current state.
Since:
7.1.1

isNearCacheInvalidationEnabled

boolean isNearCacheInvalidationEnabled()
If true, clients with local caches are automatically invalidated when the data grid map is updated.

Returns:
true if client near cache invalidation is enabled.
Since:
8.6

isNearCacheLastAccessTTLSyncEnabled

boolean isNearCacheLastAccessTTLSyncEnabled()
If true, clients automatically send time-to-live access information to the remote data grid when accessed and the TTLType.LAST_ACCESS_TIME TTL evictor type is configured.

Returns:
true if last-access time-to-live information is sent to the remote data grid.
Since:
8.6

isNearCacheEnabled

boolean isNearCacheEnabled()
If true, the client near cache is enabled for supported configurations. The client near cache can only be enabled when using optimistic locking or when locking is disabled.

Returns:
true if the client near cache is enabled.

getKeyOutputFormat

OutputFormat getKeyOutputFormat()
Retrieves the data format for all data access APIs that return cache keys.

Returns:
the data format or null if the default should be used.
Since:
8.6

setKeyOutputFormat

void setKeyOutputFormat(OutputFormat dataFormat)
Sets the data format for all data access APIs that return cache keys.

Parameters:
dataFormat - the data format to use or null to use the default.
Since:
8.6

getValueOutputFormat

OutputFormat getValueOutputFormat()
Retrieves the data format for all data access APIs that return cache values.

Returns:
the data format.
Since:
8.6

setValueOutputFormat

void setValueOutputFormat(OutputFormat dataFormat)
Sets the data format for all data access APIs that return cache values.

Parameters:
dataFormat - the data format to use or null to use the default.
Since:
8.6

IBM WebSphereTM eXtreme Scale, Release 8.6
API Specification

© Copyright International Business Machines Corp 2005,2012. All rights reserved.