|
IBM WebSphereTM eXtreme Scale, Release 8.6 API Specification |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface BackingMap
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:
Evictor
, but an internal time-based evictor is provided by defaultLoader
EventListener
sMapIndexPlugin
sObjectTransformer
OptimisticCallback
CopyMode
of CopyMode.COPY_ON_READ_AND_COMMIT
LockStrategy
of LockStrategy.OPTIMISTIC
null
values are supportedTTLType.NONE
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 EventListener s. |
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 |
---|
static final int DEFAULT_LOCK_TIMEOUT
setLockTimeout(int)
is not invoked.
static final int DEFAULT_NUMBER_OF_BUCKETS
isNearCacheEnabled()
flag to disable
the near cache in the ObjectGrid configuration XML file.setNumberOfBuckets(int)
is not invoked.
static final int DEFAULT_NUMBER_OF_LOCK_BUCKETS
setNumberOfLockBuckets(int)
is not invoked.
static final String EVICTIONTRIGGER_MEMORY_USAGE_THRESHOLD
setEvictionTriggers(String)
,
Constant Field Valuesstatic final int LOCAL
getMapType()
,
Constant Field Valuesstatic final int SERVER
getMapType()
,
Constant Field Valuesstatic final int CLIENT
getMapType()
,
Constant Field ValuesMethod Detail |
---|
String getName()
BackingMap
.
BackingMap
was created.void setEvictor(Evictor e)
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).
e
- Evictor instance
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.Evictor
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
Evictor getEvictor()
Evictor
being used by this BackingMap.
setEvictor(Evictor)
method of
this interface or null
if setEvictor was not previously called
for this BackingMap object.Evictor
,
setEvictor(Evictor)
void setObjectTransformer(ObjectTransformer t)
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.
t
- ObjectTransformer instance
IllegalArgumentException
- if the passed in ObjectTransformer
is null
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.ObjectTransformer
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
ObjectTransformer getObjectTransformer()
ObjectTransformer
object being used by this
BackingMap
and/or Loader
.
setObjectTransformer(ObjectTransformer)
method of this interface or the default ObjectTransformer
object if the
setObjectTransformer
method was not previously called for this object.ObjectTransformer
,
setObjectTransformer(ObjectTransformer)
void setOptimisticCallback(OptimisticCallback checker)
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.
checker
- OptimisticCallback instance
IllegalArgumentException
- if the passed in OptimisticCallback
is null
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.OptimisticCallback
,
NoVersioningOptimisticCallback
,
LockStrategy.OPTIMISTIC
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
OptimisticCallback getOptimisticCallback()
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.
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.NoVersioningOptimisticCallback
,
OptimisticCallback
,
LockStrategy.OPTIMISTIC
,
setOptimisticCallback(OptimisticCallback)
void setLoader(Loader loader)
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).
loader
- Loader instance
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.Loader
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
Loader getLoader()
BackingMap
.
setLoader(Loader)
method of
this interface or null
if setLoader
was not previously called for this
object.Loader
,
setLoader(Loader)
void setPreloadMode(boolean async)
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.
async
- If this is true then the cache is loaded asynchronously otherwise it blocks
and the cache is unavailable until preload completes.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.Loader.preloadMap(Session, BackingMap)
boolean getPreLoadMode()
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.
setPreloadMode(boolean)
method of
this interface or false
if setPreloadeMode was not previously
called for this object.Loader.preloadMap(Session, BackingMap)
,
setPreloadMode(boolean)
void addMapIndexPlugin(MapIndexPlugin index) throws IndexAlreadyDefinedException
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.
index
- The index implementation.
IndexAlreadyDefinedException
- if this index already exists.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.MapIndexPlugin
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
List getMapIndexPlugins()
MapIndexPlugin
objects for this BackingMap.
MapIndexPlugin
s for this BackingMap.
The list is empty if the addMapIndexPlugin(MapIndexPlugin)
or setMapIndexPlugins(List)
method was
not previously called for this BackingMap.addMapIndexPlugin(MapIndexPlugin)
,
setMapIndexPlugins(List)
void setMapIndexPlugins(List indexList)
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.
indexList
- A non-null reference to a List
of MapIndexPlugin
objects.
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
.MapIndexPlugin
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
void setCopyMode(CopyMode mode, Class valueInterface)
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.
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.
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.CopyMode
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
CopyMode getCopyMode()
CopyMode
being used by this BackingMap
.
setCopyMode(CopyMode, Class)
method of
this interface or the default CopyMode
object if setCopyMode
was not previously
called for this object.CopyMode
,
setCopyMode(CopyMode, Class)
void setLockStrategy(LockStrategy lockStrategy)
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.
lockStrategy
- must be one of the final static variables defined in
LockStrategy
. See LockStrategy
class for an explanation of each
locking strategy.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.LockStrategy
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
LockStrategy getLockStrategy()
LockStrategy
object being used by this BackingMap
.
setLockStrategy(LockStrategy)
method of
this interface or the default LockStrategy
object if setLockStrategy
was not previously
called for this object.LockStrategy
,
setLockStrategy(LockStrategy)
@Deprecated void setMapEventListeners(List eventListenerList)
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.
EventListener
objects.
If this BackingMap
already has a List
of
EventListener
s, 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.
eventListenerList
- A non-null reference to a List of
EventListener
objects that are instances of
BackingMapLifecycleListener
or MapEventListener
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
EventListener
,
MapEventListener
,
BackingMapLifecycleListener
,
addMapEventListener(EventListener)
,
removeMapEventListener(EventListener)
List getMapEventListeners()
EventListener
s.
EventListener
objects for this BackingMap
.EventListener
,
MapEventListener
,
BackingMapLifecycleListener
void addMapEventListener(EventListener eventListener)
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
.
eventListener
- A non-null reference to a EventListener
to add to the list.
The listener must be an instance of BackingMapLifecycleListener
or MapEventListener
IllegalArgumentException
- if eventListener is null or not an instance of
BackingMapLifecycleListener
or MapEventListener
EventListener
,
MapEventListener
,
BackingMapLifecycleListener
void addMapEventListener(MapEventListener eventListener)
addMapEventListener(EventListener)
method.
addMapEventListener(EventListener)
method.
eventListener
- A non-null reference to a EventListener
to add to the list.
The listener must be an instance of BackingMapLifecycleListener
or MapEventListener
void removeMapEventListener(EventListener eventListener)
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
.
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.
IllegalArgumentException
- if eventListener is null or not an instance of
BackingMapLifecycleListener
or MapEventListener
EventListener
,
MapEventListener
,
BackingMapLifecycleListener
,
addMapEventListener(EventListener)
void removeMapEventListener(MapEventListener eventListener)
removeMapEventListener(EventListener)
method.
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.int getPartitionId()
BackingMap
.
BackingMap
instance. If there is only a single partition defined
for this BackingMap
object, a 0 will be returned (default).void setReadOnly(boolean readOnlyEnabled)
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.
readOnlyEnabled
- If set to true, this BackingMap
will be a read only map. If false, the
map will be a read/write map.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.boolean getReadOnly()
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.setReadOnly(boolean)
ObjectGrid getObjectGrid()
ObjectGrid
that owns this BackingMap
.
ObjectGrid
void setNumberOfBuckets(int numBuckets)
isNearCacheEnabled()
flag to disable
the near cache in the ObjectGrid configuration XML file.
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.
numBuckets
- The number of buckets to use.
IllegalArgumentException
- if numBuckets is less than 0.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.ObjectGrid.initialize()
,
ObjectGrid.getSession()
int getNumberOfBuckets()
isNearCacheEnabled()
flag to disable
the near cache in the ObjectGrid configuration XML file.
BackingMap
.
setNumberOfBuckets(int)
method or
DEFAULT_NUMBER_OF_BUCKETS
if setNumberOfBuckets
was never called.setNumberOfBuckets(int)
,
DEFAULT_NUMBER_OF_BUCKETS
void setNumberOfLockBuckets(int numBuckets)
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.
numBuckets
- The number of lock buckets to use.
IllegalArgumentException
- if numBuckets is less than 1.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.LockStrategy
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
int getNumberOfLockBuckets()
setNumberOfLockBuckets(int)
method or
DEFAULT_NUMBER_OF_LOCK_BUCKETS
if setNumberOfLockBuckets
was never called.setNumberOfLockBuckets(int)
,
DEFAULT_NUMBER_OF_LOCK_BUCKETS
void setLockTimeout(int seconds)
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)
seconds
- is the lock timeout value to use in seconds.
IllegalArgumentException
- if seconds is less than 0.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.DEFAULT_LOCK_TIMEOUT
,
LockStrategy
,
LockTimeoutException
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
,
ObjectMap.setLockTimeout(int)
int getLockTimeout()
BackingMap
.
setLockTimeout(int)
method or
DEFAULT_LOCK_TIMEOUT
if setLockTimeout
was never called.DEFAULT_LOCK_TIMEOUT
,
setLockTimeout(int)
void setNullValuesSupported(boolean nullValuesSupported)
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.
nullValuesSupported
- If set to true, null
values are
supported; otherwise null
values
are not supported.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.ObjectGrid.initialize()
,
ObjectGrid.getSession()
,
ObjectMap.containsKey(Object)
boolean getNullValuesSupported()
BackingMap
supports null
values
or not.
setNullValuesSupported(boolean)
method or the default value of true if setNullValuesSupported
was never called.setNullValuesSupported(boolean)
void setCopyKey(boolean copy)
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.
copy
- If true
is specified, then this BackingMap
uses the ObjectTransformer.copyKey(Object)
method
to copy the key object when necessary.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.ObjectGrid.initialize()
,
ObjectGrid.getSession()
,
ObjectTransformer.copyKey(Object)
boolean getCopyKey()
BackingMap
.
setCopyKey(boolean)
method or the default value of false if setCopyKey
was never called.setCopyKey(boolean)
void setTimeToLive(int 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.
seconds
- the number of seconds a map entry is allowed to live in map
before being evicted.
IllegalArgumentException
- if seconds is less than 0.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.setTtlEvictorType(TTLType)
,
ObjectMap.setTimeToLive(int)
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
int getTimeToLive()
This value returned is in seconds and 0 indicates forever.
setTimeToLive(int)
method or
0 if setLockTimeout
was never called.setTimeToLive(int)
void setTtlEvictorType(TTLType type)
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.
type
- must be one of the public constants declared in the
TTLType
class.
IllegalStateException
- if this method is called after the
ObjectGrid.initialize()
method is called.TTLType
,
ObjectGrid.initialize()
,
ObjectGrid.getSession()
TTLType getTtlEvictorType()
BackingMap
entry is computed.
TTLType
that was passed to the setTtlEvictorType(TTLType)
or
TTLType.NONE
if setTtlEvictorType
was never called.setTtlEvictorType(TTLType)
,
TTLType
void createDynamicIndex(String name, boolean isRangeIndex, String attributeName, DynamicIndexCallback dynamicIndexCallback) throws IndexAlreadyDefinedException, IllegalArgumentException
BackingMap
.
Required Client Permission: ServerMapPermission.REPLICATE
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.
IllegalArgumentException
- if name or attributeName is null or a zero length string.
IndexAlreadyDefinedException
- if a MapIndexPlugin
with the specified name already exists.MapIndex
,
MapIndexPlugin
,
MapRangeIndex
,
ObjectMap.getIndex(String)
void createDynamicIndex(MapIndexPlugin index, DynamicIndexCallback dynamicIndexCallback) throws IndexAlreadyDefinedException, IllegalArgumentException
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.
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.
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.MapIndexPlugin
,
ObjectMap.getIndex(String)
void removeDynamicIndex(String name) throws IndexUndefinedException, IllegalArgumentException
BackingMap
.
Required Client Permission: ServerMapPermission.DYNAMIC_INDEX
name
- the name of the index. The name can not be null
.
IllegalArgumentException
- if name is null
.
IndexUndefinedException
- if a MapIndexPlugin
with the specified name does not exists.createDynamicIndex(MapIndexPlugin, DynamicIndexCallback)
,
createDynamicIndex(String, boolean, String, DynamicIndexCallback)
PartitionManager getPartitionManager()
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
Overview
Package
Class
Tree
Serialized
Deprecated
Index
Help
IBM WebSphereTM eXtreme Scale, Release 8.6
API Specification
PREV CLASS
NEXT CLASS
FRAMES
NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD
© Copyright International Business Machines Corp 2005,2012. All rights reserved.