| IBM WebSphere Extended Deployment (XD)TM
Release 6.0 |
com.ibm.websphere.objectgrid
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
plugins or by setting properties. The defaults are:
- No external
Evictor
, but an internal time-based evictor is provided by default
- No
Loader
- No
MapEventListener
s
- An internal
ObjectTransformer
- An internal
OptimisticCallback
- Key is not copied
- A value
CopyMode
of CopyMode.COPY_ON_READ_AND_COMMIT
- A
LockStrategy
of LockStrategy.OPTIMISTIC
- A default lock timeout
null
values are supported
- A default number of buckets
- A default number of lock buckets
- Synchronous preload
- Read/write map by default
- A TimeToLive of 0 (indicating unlimited time)
- A TtlEvictor type of
TTLType.NONE
DEFAULT_LOCK_TIMEOUT
public
static DEFAULT_LOCK_TIMEOUT
Default lock timeout used if setLockTimeout(int)
is not invoked.
DEFAULT_NUMBER_OF_BUCKETS
public
static DEFAULT_NUMBER_OF_BUCKETS
Default number of lock buckets used if setNumberOfBuckets(int)
is not invoked.
DEFAULT_NUMBER_OF_LOCK_BUCKETS
public
static DEFAULT_NUMBER_OF_LOCK_BUCKETS
Default number of lock buckets used if setNumberOfLockBuckets(int)
is not invoked.
getName
Gets the name of the BackingMap
.
Returns:
value specified when BackingMap
was created.
setEvictor
public 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.
See Also:
-
Evictor
Parameters:
e
-
Evictor instance
Throws:
java.lang.IllegalStateException
getEvictor
public Evictor getEvictor( | ) |
Gets the Evictor
being used by this BackingMap.
See Also:
-
Evictor
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.
setObjectTransformer
public 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.
See Also:
-
ObjectTransformer
Parameters:
t
-
ObjectTransformer instance
Throws:
java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException
getObjectTransformer
public ObjectTransformer getObjectTransformer( | ) |
Gets the ObjectTransformer
object being used by this
BackingMap
and/or Loader
.
See Also:
-
ObjectTransformer
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.
setOptimisticCallback
public void setOptimisticCallback( | | OptimisticCallback checker )
|
Sets the OptimisticCallback
.
The OptimisticCallback will be used to check the versions of cache entries
during the commit phase.
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.
See Also:
-
OptimisticCallback
Parameters:
checker
-
OptimisticCallback instance
Throws:
java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException
getOptimisticCallback
public OptimisticCallback getOptimisticCallback( | ) |
Gets the OptimisticCallback
being used by this BackingMap
and/or Loader
.
See Also:
-
OptimisticCallback
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.
setLoader
public 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.
See Also:
-
Loader
Parameters:
loader
-
Loader instance
Throws:
java.lang.IllegalStateException
getLoader
public Loader getLoader( | ) |
Gets the Loader being used by this BackingMap
.
See Also:
-
Loader
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.
setPreloadMode
public 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.
See Also:
-
preloadMap(Session, BackingMap)
Parameters:
async
-
If this is true then the cache is loaded asynchronously otherwise it blocks
and the cache is unavailable until preload completes.
Throws:
java.lang.IllegalStateException
getPreLoadMode
public 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) is
invoked asynchronously; otherwise it blocks the execution when loading data
so the cache is unavailable until preload completes. Preloading occurs during
ObjectGrid
initialization.
See Also:
-
preloadMap(Session, BackingMap)
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.
addMapIndexPlugin
public void addMapIndexPlugin( | | MapIndexPlugin index )
|
This method adds an index plugin to this Map. We assume the index implementation was constructed
with the name of the attribute to index. The name of the index is specified when
the index is constructed.
Note, to avoid an IllegalStateException, this method must be called
prior to ObjectGrid#initialize() method. Also, keep in mind that the
ObjectGrid#getSession() method implicitly calls the
ObjectGrid#initialize() method if it has yet to be called by the application.
Parameters:
index
-
The index implementation.
Throws:
com.ibm.websphere.objectgrid.IndexAlreadyDefinedExceptionjava.lang.IllegalStateException
getMapIndexPlugins
public List getMapIndexPlugins( | ) |
This method returns the current list of MapIndexPlugin objects for this BackingMap.
Returns:
The current list of MapIndexPlugin for this BackingMap.
The list is empty if the #addMapIndexPlugin(MapIndexPlugin)
or #setMapIndexPlugins(List) methods were
not previously called for this BackingMap.
setMapIndexPlugins
public void setMapIndexPlugins( | | List indexList )
|
This method 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:
java.lang.IllegalArgumentException
setCopyMode
public 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.
See Also:
-
CopyMode
Parameters:
mode
-
must be one of the final static variables defined in CopyMode
.
See CopyMode
class for an explanation of each mode and how the valueInterface
is used for CopyMode#COPY_ON_WRITE .
valueInterface
-
is a value interface Class object.
A non-null valueInterface is required when mode is set to
CopyMode.COPY_ON_WRITE
. It is ignored for all other modes.
Throws:
java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException
getCopyMode
public 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.
setLockStrategy
public 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.
See Also:
-
LockStrategy
Parameters:
lockStrategy
-
must be one of the final static variables defined in
LockStrategy. See LockStrategy
class for an explanation of each
locking strategy.
Throws:
java.lang.IllegalStateException
getLockStrategy
public LockStrategy getLockStrategy( | ) |
Gets the LockStrategy
object being used by this BackingMap
.
See Also:
-
LockStrategy
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.
setMapEventListeners
public void setMapEventListeners( | | List eventListenerList )
|
Sets the list of MapEventListener
objects.
If this BackingMap
already has a List
of
MapEventListener
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.
See Also:
-
MapEventListener
Parameters:
eventListenerList
-
A non-null reference to a List of
MapEventListener objects.
Throws:
java.lang.IllegalArgumentException
getMapEventListeners
public List getMapEventListeners( | ) |
Gets the current list of MapEventListener
s.
See Also:
-
MapEventListener
Returns:
the current list of MapEventListener
for this BackingMap
.
addMapEventListener
public void addMapEventListener( | | MapEventListener eventListener )
|
Adds a MapEventListener
to this BackingMap
.
Note, this method is allowed to be invoked before and after the
ObjectGrid#initialize() method.
See Also:
-
MapEventListener
Parameters:
eventListener
-
A non-null reference to a MapEventListener
to add to the list.
Throws:
java.lang.IllegalArgumentException
removeMapEventListener
public void removeMapEventListener( | | MapEventListener eventListener )
|
Removes a MapEventListener
from this BackingMap
.
Note, this method is allowed to be invoked before and after the
ObjectGrid#initialize() method.
See Also:
-
MapEventListener
Parameters:
eventListener
-
A non-null reference to an event listener that was
previously added by invoking either the #addMapEventListener(MapEventListener)
or #setMapEventListeners(List) method of this interface.
Throws:
java.lang.IllegalArgumentException
setPartitionId
public void setPartitionId( | | int partitionId )
|
This method should be used to set a partition identifier for this
BackingMap instance. Normally, the partitionId's are a 0-based
index into the list of configured partitions.
Parameters:
partitionId
-
A 0-based index identifying the partition for this BackingMap instance.
getPartitionId
public int getPartitionId( | ) |
Get the partion identifier being used by this BackingMap.
Returns:
the argument that was passed to the #setPartitionId(int) method of
this interface or 0 if there is only a single partition defined
for this BackingMap object (default).
setReadOnly
public void setReadOnly( | | boolean readOnlyEnabled )
|
Set the map type of this BackingMap.
A map can be a read only map or a read/write map. Passing true
as the parameter value will make this map a read only map; passing
false as the parameter value will make this map a read/write map.
Parameters:
readOnlyEnabled
-
If set to true, this BackingMap
will be a read only map. If false, the
map will be a read/write map.
getReadOnly
public 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.
getObjectGrid
public ObjectGrid getObjectGrid( | ) |
Gets the ObjectGrid
that owns this BackingMap
.
Returns:
the ObjectGrid instance that owns this BackingMap.
setNumberOfBuckets
public void setNumberOfBuckets( | | int numBuckets )
|
Sets the number of buckets used by this BackingMap
.
The BackingMap
implementation uses a hash map for its
implementation. If there are a lot of entries in the BackingMap
then more buckets means better performance because the risk of collisions
is lower as the number of buckets grows. More buckets also means more
concurrency.
Once the ObjectGrid
is initialized this parameter cannot be changed.
Therefore, to avoid an IllegalStateException, this method must be called
prior to the ObjectGrid#initialize() method. Also, keep in mind that the
ObjectGrid#getSession() method implicitly calls the
ObjectGrid.initialize()
method if it has yet to be called by the application.
Parameters:
numBuckets
-
The number of buckets to use.
Throws:
java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException
getNumberOfBuckets
public int getNumberOfBuckets( | ) |
Gets the number of buckets defined for this BackingMap
.
Returns:
the same value passed to the #setNumberOfBuckets(int) method or
#DEFAULT_NUMBER_OF_BUCKETS if setNumberOfBuckets
was never called.
setNumberOfLockBuckets
public void setNumberOfLockBuckets( | | int numBuckets )
|
Sets the number of lock buckets used by the lock manager for this
BackingMap
.
When com.ibm.websphere.objectgrid.LockStrategy#OPTIMISTIC or
com.ibm.websphere.objectgrid.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 com.ibm.websphere.objectgrid.LockStrategy#NONE, no lock manager
is used by this BackingMap
. In this case, a call to this
method does nothing.
Once the ObjectGrid
is initialized, the number of lock buckets
cannot be changed. Therefore, to avoid an IllegalStateException, this
method must be called prior to the ObjectGrid#initialize() method.
Also, keep in mind that the ObjectGrid#getSession() method
implicitly calls the ObjectGrid.initialize()
method if it
has yet to be called by the application.
Parameters:
numBuckets
-
The number of lock buckets to use.
Throws:
java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException
getNumberOfLockBuckets
public 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.
setLockTimeout
public void setLockTimeout( | | int seconds )
|
Sets the lock timeout used by the lock manager for this
BackingMap
.
When com.ibm.websphere.objectgrid.LockStrategy#OPTIMISTIC or
com.ibm.websphere.objectgrid.LockStrategy#PESSIMISTIC is used
for this BackingMap
, a lock manager is created for the
BackingMap
. To prevent deadlocks from occuring, the lock
manager has a default timeout value for waiting for a lock to be granted.
If this timeout limit is exceeeded, a com.ibm.websphere.objectgrid.LockTimeoutException
is thrown. The default value of #DEFAULT_LOCK_TIMEOUT should be sufficient for most
applications, but on a heavily loaded system, a timeout may occur when no
deadlock exists. In that case, this method can be used to increase the lock
timeout value from the default to whatever is desired to prevent false
timeout exceptions from occuring. When the lock strategy is
com.ibm.websphere.objectgrid.LockStrategy#NONE, no lock manager
is used by this BackingMap
. In this case, a call to this
method does nothing.
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.
Parameters:
seconds
-
is the lock timeout value to use in seconds.
Throws:
java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException
getLockTimeout
public 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.
setNullValuesSupported
public 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:
java.lang.IllegalStateException
getNullValuesSupported
public 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.
setCopyKey
public 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:
java.lang.IllegalStateException
getCopyKey
public 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.
setTimeToLive
public 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).
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.
See Also:
-
setTtlEvictorType(TTLType)setTimeToLive(int)
Parameters:
seconds
-
the number of seconds a map entry is allowed to live in map
before being evicted.
Throws:
java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException
getTimeToLive
public int getTimeToLive( | ) |
Gets the number of seconds for an entry to live.
This value returned is in seconds and 0 means forever.
Returns:
the value that was passed to the #setTimeToLive(int) method or
0 if setTimeToLive
was never called.
setTtlEvictorType
public void setTtlEvictorType( | | TTLType type )
|
Sets how expiration time of a BackingMap
entry is computed.
If this method is not called, then 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).
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.
See Also:
-
TTLType
Parameters:
type
-
must be one of the public constants declared in the
TTLType class.
Throws:
java.lang.IllegalStateException
getTtlEvictorType
public TTLType getTtlEvictorType( | ) |
Gets how expiration time of a BackingMap
entry is computed.
See Also:
-
TTLType
Returns:
the TTLType
that was passed to the #setTtlEvictorType(TTLType) or
TTLType.NONE
if setTtlEvictorType
was never called.
createDynamicIndex
public void createDynamicIndex( | String name , | | boolean isRangeIndex ,
| | String attributeName ,
| | DynamicIndexCallback dynamicIndexCallback )
|
Create a dynamic index on the BackingMap
.
Parameters:
name
-
the name of the index. The name can not be null.
isRangeIndex
-
Indicate whether to create a MapRangeIndex or a MapIndex.
If set to true, the index will be type of MapRangeIndex.
attributeName
-
The name of the attribute to be indexed. The attributeName can not be null.
dynamicIndexCallback
-
The callback that will invoke upon dynamic index events. The dynamicIndexCallback
is optional and can be null.
Throws:
com.ibm.websphere.objectgrid.IndexAlreadyDefinedExceptionjava.lang.UnsupportedOperationException
createDynamicIndex
public void createDynamicIndex( | MapIndexPlugin index , | | DynamicIndexCallback dynamicIndexCallback )
|
Create a dynamic index on the BackingMap
.
Parameters:
index
-
The index implementation. The index can not be null.
dynamicIndexCallback
-
The callback that will invoke upon dynamic index events. The dynamicIndexCallback
is optional and can be null.
Throws:
com.ibm.websphere.objectgrid.IndexAlreadyDefinedExceptionjava.lang.UnsupportedOperationException
removeDynamicIndex
public void removeDynamicIndex( | | String name )
|
Create a dynamic index on the BackingMap
.
Parameters:
name
-
the name of the index. The name can not be null.
Throws:
com.ibm.websphere.objectgrid.IndexUndefinedException
getPartitionManager
public PartitionManager getPartitionManager( | ) |
Allows access to the PartitionManager that is defined for this
BackingMap. This access may be useful for Loaders during preLoad
processing (to properly partition the data to be loaded).
Returns:
PartitionManager associated with this BackingMap
| IBM WebSphere Extended Deployment (XD)TM
Release 6.0 |