com.ibm.websphere.objectgrid

Interface ObjectMap

public interface ObjectMap

This is a handle to a named Map. Maps should have homogeneous keys and values. An instance of this ObjectMap can only be used by the thread that is currently associated with the Session that was used to get this ObjectMap instance. Both Session and ObjectMap objects are not allowed to be shared by multiple threads concurrently.

The CopyMode setting on the map determines whether or not a copy of the value is returned by get methods. It also determines whether or not a copy of the committed value is made at commit time. The LockStrategy setting for the map determines whether or not a lock is obtained for each map entry accessed by the transaction, the lock mode of the lock obtained, and when the lock is obtained.

Each data access method includes a "Specification details" table that includes the following information:

Required permission:	The permission required to use the API.
Pessimistic read lock acquired:	The type of lock that is acquired when using pessimistic locking with repeatable read transaction isolation.
Pessimistic read lock held:	The type of lock that is held for the duration of the transaction when using pessimistic locking with repeatable read transaction isolation. Locks can be upgraded but not demoted during a transaction.
Transaction:	The state of the transaction when invoking the API. Manual - The transaction is explicitly demarcated using the associated Session and the specified API is used within the scope of that transaction. Automatic - The transaction is automatically demarcated. This is also referred to as an auto-commit transaction or API which the associated Session.isTransactionActive() is false when invoking the API.
Cache tier:	Identifies the map cache tiers that are included when fetching or updating cache entries in the call and under what circumstances. The following tiers are available for client maps: Transactional Cache Near Cache (if enabled) Server Cache Loader (if enabled) The following tiers are available for local maps: Transactional Cache Local Cache Loader (if enabled)

Since:

WAS XD 6.0, XC10

See Also:

Session.getMap(String), BackingMap.setCopyMode(CopyMode, Class), BackingMap.setLockStrategy(LockStrategy)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ObjectMap.PutMode Identifies the operation mode of the put(Object, Object), putAll(Map) , JavaMap.put(Object, Object) and JavaMap.putAll(Map) methods.

Field Summary

Fields

Modifier and Type	Field and Description
static long	QUEUE_TIMEOUT_INFINITE Used as a parameter on the getNextKey(long) method, specifies the method should block until a key becomes available.
static long	QUEUE_TIMEOUT_NONE Used as a parameter on the getNextKey(long) method, specifies to return a null value if the map is empty.
static int	TTL_FOREVER A constant indicating the time-to-live value is "forever".
static int	USE_DEFAULT A constant indicating the time-to-live value or lock timeout value is the default setting.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clear all keys from the Map.
void	clearCopyMode() Resets the CopyMode back to the one in the BackingMap.
boolean	containsKey(Object key) Returns true if this map contains a mapping for the specified key.
void	flush() Pushes the current set of changes for the ObjectMap instance to the Loader without committing the changes.
Object	get(Object key) Retrieves the object from the cache at the given key.
AgentManager	getAgentManager() Returns the Agent Manager that allows DataGrid operations to be performed on the objects within this Map.
List	getAll(List keyList) Gets a list of entries from the map.
List	getAllForUpdate(List keyList) Same as the getAll(List) method except that if pessimistic lock strategy is used for this map, an upgradable lock mode is obtained for these map entries.
EntityMetadata	getEntityMetadata() Deprecated. Deprecated in version 8.6.1.
Object	getForUpdate(Object key) Same as get(Object) method except that if pessimistic lock strategy is used for this map, an upgradable lock mode is obtained for this map entry.
Object	getIndex(String name) Returns a reference to the named index that can be used with this Map.
Object	getIndex(String name, boolean forUpdate) Returns a reference to the named index that can be used with this Map.
Map	getJavaMap() Returns an implementation of java.util.Map that is backed by this ObjectMap.
OutputFormat	getKeyOutputFormat() Retrieves the data format for all data access APIs that return cache keys for the current session.
int	getMapType() Returns the type of the underlying BackingMap.
String	getName() Returns the name of the ObjectMap as defined by the configuration.
Object	getNextKey(long timeout) Retrieves a key off the map in first-in-first-out (FIFO) insert order.
ObjectMap.PutMode	getPutMode() Retrieve the current PutMode set for this ObjectMap instance.
OutputFormat	getValueOutputFormat() Retrieves the data format for all data access APIs that return cache values for the current session.
void	insert(Object key, Object value) Performs an explicit insert of a given entry.
void	invalidate(Object key, boolean isGlobal) Invalidates an entry in the cache based on the key parameter.
void	invalidateAll(Collection keyList, boolean isGlobal) Invalidate a set of cache entries based on the Collection of keys provided.
boolean	lock(Object key, LockMode lockMode) Obtains a lock for the given key.
List<Boolean>	lockAll(List keyList, LockMode lockMode) Obtains locks for the given keys.
Object	put(Object key, Object value) Puts the Object value into the cache at location represented by key.
void	putAll(Map map) Puts each of the Object value into the cache at location represented by key contained in the Map.
Object	remove(Object key) Removes the Object value from the cache represented by key.
void	removeAll(Collection keyList) Batch remove from the Map.
void	setCopyMode(CopyMode copyMode, Class valueInterface) Allows the CopyMode for the Map to be overridden on this map on this session only.
void	setKeyOutputFormat(OutputFormat outputFormat) Sets the data format for all data access APIs that return cache keys for the current session.
void	setLockTimeout(int seconds) Overrides the BackingMap's lock timeout for this ObjectMap.
void	setPutMode(ObjectMap.PutMode putMode) Allows the default operation for the put(Object, Object) and putAll(Map) methods to be changed, allowing the put to use the optimized upsert(Object, Object) and upsertAll(LinkedHashMap) implementations.
int	setTimeToLive(int ttl) Establishes the number of seconds that any given cache entry can live for, which is referred to as "time to live" or TTL.
void	setValueOutputFormat(OutputFormat outputFormat) Sets the data format for all data access APIs that return cache values for the current session.
void	touch(Object key) Updates the last access time in the BackingMap without retrieving the value to the ObjectMap.
void	update(Object key, Object value) Performs an explicit update of a given entry.
void	upsert(Object key, Object value) Puts the Object value into the cache at location represented by key.
void	upsertAll(LinkedHashMap map) Puts each of the Object value into the cache at location represented by key contained in the Map.

Field Detail

TTL_FOREVER

static final int TTL_FOREVER

A constant indicating the time-to-live value is "forever".

See Also:

Constant Field Values

USE_DEFAULT

static final int USE_DEFAULT

A constant indicating the time-to-live value or lock timeout value is the default setting.

The default setting is to retain the time-to-live value for any existing map entry and to use the default value from BackingMap setting if a new map entry is being created.

For lock timeout override the default setting is to use the value defined on the BackingMap

See Also:

setLockTimeout(int), setTimeToLive(int), BackingMap.setTimeToLive(int), BackingMap.getTimeToLive(), BackingMap.setLockTimeout(int), Constant Field Values

QUEUE_TIMEOUT_NONE

static final long QUEUE_TIMEOUT_NONE

Used as a parameter on the getNextKey(long) method, specifies to return a null value if the map is empty.

See Also:

Constant Field Values

QUEUE_TIMEOUT_INFINITE

static final long QUEUE_TIMEOUT_INFINITE

Used as a parameter on the getNextKey(long) method, specifies the method should block until a key becomes available.

See Also:

Constant Field Values

Method Detail

getName

String getName()

Returns the name of the ObjectMap as defined by the configuration.

Returns:

name of ObjectMap

get

Object get(Object key)
           throws ObjectGridException

Retrieves the object from the cache at the given key.

Whether or not a copy of the object is returned is determined by the CopyMode setting for this map. See CopyMode for a description of each possible CopyMode. If the key cannot be found in the map, a null value will be returned. A null value is also returned if a value is null and this map allows null values. To distinguish the two, use the containsKey method.

The return value is a SerializedValue when using the CopyMode.COPY_TO_BYTES_RAW CopyMode or OutputFormat.RAW OutputFormat with a ValueSerializerPlugin plug-in defined on the BackingMap. The SerializedValue allows access to the value in its serialized form, or its native Java Object form.

The return value is a Tuple when an an EntityManager API entity is associated with the BackingMap.

Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.SHARED
Pessimistic read lock held:	Yes
Transaction:	Automatic or manual
Cache tier:	Progresses to all tiers until the key is found.

Parameters:

key - The entry to fetch

Returns:

the value, null, SerializedValue or Tuple

Throws:

IllegalArgumentException - if key is null

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

containsKey(Object), getForUpdate(Object), CopyMode

put

Object put(Object key,
         Object value)
           throws ObjectGridException

Puts the Object value into the cache at location represented by key.

The value will be pushed down to the BackingMap/Loader at commit time and has two behaviors, which can be altered using the setPutMode(PutMode) property:

ObjectMap.PutMode.INSERTUPDATE	(Deprecated) A put without a preceding get is an insert. For an entry in a map, a put following a get is always an update. However, if the entry is not in the map, a put following a get is an insert.
ObjectMap.PutMode.UPSERT	The value is put into the map using the specification of the upsert(Object, Object).

Whether or not a copy of the object is made when transaction is committed is determined by the copy mode setting for this map. See CopyMode for a description of each possible copy mode.

The return value is a SerializedValue when using the CopyMode.COPY_TO_BYTES_RAW CopyMode or OutputFormat.RAW OutputFormat with a ValueSerializerPlugin plug-in defined on the BackingMap. The SerializedValue allows access to the value in its serialized form, or its native Java Object form.

The return value is a Tuple when an an EntityManager API entity is associated with the BackingMap.

Specification details:

Required permission:	MapPermission.WRITE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

key - The entry to put into the map

value - The value to put into the map using the key

Returns:

If ObjectMap.PutMode.INSERTUPDATE is set, return the previous value in this transaction. If ObjectMap.PutMode.UPSERT is set, the return value is null.

Throws:

IllegalArgumentException - if key is null, or if the map does not allow null values and value is null

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

CopyMode

getForUpdate

Object getForUpdate(Object key)
                    throws ObjectGridException

Same as get(Object) method except that if pessimistic lock strategy is used for this map, an upgradable lock mode is obtained for this map entry. See LockStrategy.PESSIMISTIC for additional information. Whether or not a copy of the object is returned is determined by the CopyMode setting for this map. See CopyMode for a description of each possible CopyMode. If the key cannot be found in the map, a null value will be returned. A null value is also returned if the value is null and this map allows null values. To distinguish the two, use the containsKey method.

The return value is a SerializedValue when using the CopyMode.COPY_TO_BYTES_RAW CopyMode or OutputFormat.RAW OutputFormat with a ValueSerializerPlugin plug-in defined on the BackingMap. The SerializedValue allows access to the value in its serialized form, or its native Java Object form.

The return value is a Tuple when an an EntityManager API entity is associated with the BackingMap.

Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.UPGRADABLE Note: Transaction isolation is ignored.
Pessimistic locks held:	Yes
Transaction:	Automatic or manual
Cache tier:	Progresses to all tiers until the key is found and the appropriate lock is acquired.

Parameters:

key - The entry to fetch

Returns:

the value, null, SerializedValue or Tuple

Throws:

IllegalArgumentException - if key is null

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

containsKey(Object), get(Object), CopyMode, LockStrategy.PESSIMISTIC

remove

Object remove(Object key)
              throws ObjectGridException

Removes the Object value from the cache represented by key.

This removal will be pushed down to the BackingMap/Loader at commit time. If the key cannot be found in the map, a null value will be returned.

The return value is a SerializedValue when using the CopyMode.COPY_TO_BYTES_RAW CopyMode or OutputFormat.RAW OutputFormat with a ValueSerializerPlugin plug-in defined on the BackingMap. The SerializedValue allows access to the value in its serialized form, or its native Java Object form.

The return value is a Tuple when an an EntityManager API entity is associated with the BackingMap.

Specification details:

Required permission:	MapPermission.REMOVE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

key - The entry to remove

Returns:

the current value at invocation time

Throws:

IllegalArgumentException - if key is null

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

getAll

List getAll(List keyList)
            throws ObjectGridException

Gets a list of entries from the map.

If a key in the list cannot be found, a null value will be set at the appropriate position in the returned list.

The return value is a SerializedValue when using the CopyMode.COPY_TO_BYTES_RAW CopyMode or OutputFormat.RAW OutputFormat with a ValueSerializerPlugin plug-in defined on the BackingMap. The SerializedValue allows access to the value in its serialized form, or its native Java Object form.

A return value is a Tuple when an an EntityManager API entity is associated with the BackingMap.

Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.SHARED
Pessimistic read lock held:	Yes
Transaction:	Automatic or manual
Cache tier:	For each key, progresses to all tiers until the key is found.

Parameters:

keyList - A list of keys for identifying which entries to fetch

Returns:

a list of values

Throws:

IllegalArgumentException - if keyList is null or contains a null element.

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

get(Object)

getAllForUpdate

List getAllForUpdate(List keyList)
                     throws ObjectGridException

Same as the getAll(List) method except that if pessimistic lock strategy is used for this map, an upgradable lock mode is obtained for these map entries. See LockStrategy.PESSIMISTIC for additional information. If a key in the list cannot be found, a null value will be set at the appropriate position in the returned list.

The return value is a SerializedValue when using the CopyMode.COPY_TO_BYTES_RAW CopyMode or OutputFormat.RAW OutputFormat with a ValueSerializerPlugin plug-in defined on the BackingMap. The SerializedValue allows access to the value in its serialized form, or its native Java Object form.

A return value is a Tuple when an an EntityManager API entity is associated with the BackingMap.

Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.UPGRADABLE Note: Transaction isolation is ignored.
Pessimistic locks held:	Yes
Transaction:	Automatic or manual
Cache tier:	Progresses to all tiers until the keys are found and the appropriate locks are acquired.

Parameters:

keyList - A list of keys for identifying which entries to fetch

Returns:

a list of values

Throws:

IllegalArgumentException - if keyList is null or contains a null element.

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

getAll(List), getForUpdate(Object), LockStrategy.PESSIMISTIC

removeAll

void removeAll(Collection keyList)
               throws ObjectGridException

Batch remove from the Map. If a key in the list cannot be found, it will be ignored.

Specification details:

Required permission:	MapPermission.REMOVE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

keyList - A list of keys for identifying which entries to remove

Throws:

IllegalArgumentException - if keyList is null or contains a null element.

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

remove(Object)

putAll

void putAll(Map map)
            throws ObjectGridException

Puts each of the Object value into the cache at location represented by key contained in the Map.

The values will be pushed down to the BackingMap/Loader at commit time and has two behaviors, which can be altered using the setPutMode(PutMode) property:

ObjectMap.PutMode.INSERTUPDATE	(Deprecated) A put without a preceding get is an insert. For an entry in a map, a put following a get is always an update. However, if the entry is not in the map, a put following a get is an insert.
ObjectMap.PutMode.UPSERT	The values are put into the map using the specification of the upsertAll(LinkedHashMap).

Whether or not a copy of the object is made when transaction is committed is determined by the copy mode setting for this map. See CopyMode for a description of each possible copy mode.

An existing Map object will be passed in to use for obtaining the keys and values to be inserted or updated into the existing Map.

Specification details:

Required permission:	MapPermission.WRITE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

map - The key/values to be put into the map.

Throws:

IllegalArgumentException - if map is null or contains a null key or if null values are not allowed and map contains a null value.

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

put(Object, Object)

invalidate

void invalidate(Object key,
              boolean isGlobal)
                throws ObjectGridException

Invalidates an entry in the cache based on the key parameter.

If the key's value has changes pending in the ObjectMap, it is the application's responsibility to flush these changes to the Loader before invalidation. If a flush is not performed prior to invoking the invalidate operation, all pending changes for this key will be removed from the ObjectMap. If the key cannot be found in the map, it will be ignored.

The isGlobal parameter is used to indicate which cache level is used to invalidate the entries. If isGlobal is true, when the transaction is committed, the key is removed from the BackingMap also. If a subsequent get operation is performed, the BackingMap will be skipped and the Loader will be used to get the data. If isGlobal is false, the entry is only invalidated in the ObjectMap (transactional cache). If a subsequent get operation is performed, the BackingMap can be used; and, if it's not in the BackingMap, the Loader will be used to get the data.

A typical use of isGlobal being false is when a large number of records are touched in a transaction and the application wants to evict records that are no longer used in the cache.

Specification details:

Required permission:	MapPermission.INVALIDATE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit except the Loader. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps. Set the isGlobal parameter to false to limit the operation to the transaction cache tier.

Parameters:

key - Object representing the key to be used for cache entry invalidation

isGlobal - Indicates whether to remove the entry from the BackingMap (true) or just the ObjectMap (false).

Throws:

IllegalArgumentException - if key is null

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

invalidateAll

void invalidateAll(Collection keyList,
                 boolean isGlobal)
                   throws ObjectGridException

Invalidate a set of cache entries based on the Collection of keys provided. If a key in the collection cannot be found, it will be ignored.

Specification details:

Required permission:	MapPermission.INVALIDATE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit except the Loader. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps. Set the isGlobal parameter to false to limit the operation to the transaction cache tier.

Parameters:

keyList - A Collection of keys representing the entries to be invalidated

isGlobal - Indicates whether to remove the entry from the BackingMap (true) or just the ObjectMap (false).

Throws:

IllegalArgumentException - if keyList is null or contains a null element.

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

invalidate(Object, boolean)

setTimeToLive

int setTimeToLive(int ttl)

Establishes the number of seconds that any given cache entry can live for, which is referred to as "time to live" or TTL. Setting a new TTL value affects cache entries that are accessed after this method call occurs. It does not affect any cache entry that was created or accessed prior to this method call. By calling this method on this ObjectMap, any previous value set by the BackingMap.setTimeToLive(int) method is overridden for this ObjectMap. If this method is never called on the ObjectMap, the default setting is used. The default setting is to retain the time-to-live value for any existing map entry and to use the default value from BackingMap setting if a new map entry is being created. If TTL is never set on the BackingMap, the cache entry can live "forever".

This method can only be used when the TTLType is set to LAST_ACCESS_TIME or LAST_UPDATE_TIME on the BackingMap. If this method is called on the ObjectMap and the TTLType is something other than LAST_ACCESS_TIME or LAST_UPDATE_TIME, an IllegalStateException is thrown.

Required permission: MapPermission.INVALIDATE

Parameters:

ttl - is the time-to-live value in seconds. The value must be >= -1. A value of 0 is used to indicate the cache entry can live "forever" and -1 to indicate to use default setting. Use of the constant TTL_FOREVER is recommended when "forever" is desired and the constantUSE_DEFAULT is recommended when "use default" setting is desired.

Returns:

previous time-to-live value in seconds. The constant TTL_FOREVER and constant USE_DEFAULTcan be used to determine if the previous TTL is one of the special values.

Throws:

IllegalArgumentException - if seconds argument is < -1.

IllegalStateException - if BackingMap.getTtlEvictorType() returns anything other than TTLType.LAST_ACCESS_TIME or TTLType.LAST_UPDATE_TIME.

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

TTL_FOREVER, USE_DEFAULT, BackingMap.setTimeToLive(int), TTLType.LAST_ACCESS_TIME, TTLType.LAST_UPDATE_TIME

update

void update(Object key,
          Object value)
            throws KeyNotFoundException,
                   ObjectGridException

Performs an explicit update of a given entry.

A get operation is not required prior to invoking the update method (unlike the put method). Also, an update invocation will never insert a new record. If a the map's LockStrategy is LockStrategy.OPTIMISTIC this method will implicitly get the entry so as to have the version value of the object for when this method was invoked. Whether or not a copy of the object is made when transaction is committed is determined by the CopyMode setting for this map. See CopyMode for a description of each possible CopyMode.

If a key cannot be found in the map during commit, a TransactionException will be thrown.

Specification details:

Required permission:	MapPermission.WRITE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

key - Identifies the entry to be updated

value - The updated value for this entry

Throws:

IllegalArgumentException - if key is null or if the map does not allow null values and value is null.

KeyNotFoundException - if the key cannot be found in the map

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

insert(Object, Object), put(Object, Object), CopyMode, LockStrategy.OPTIMISTIC

insert

void insert(Object key,
          Object value)
            throws DuplicateKeyException,
                   ObjectGridException

Performs an explicit insert of a given entry.

The key must not exist before executing this method. Also, an insert invocation will never update an existing record. Whether or not a copy of the object is made when a transaction is committed is determined by the CopyMode setting for this map. See CopyMode for a description of each possible CopyMode.

If the key is already in the map, a TransactionException will be thrown during commit.

Specification details:

Required permission:	MapPermission.INSERT
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

key - Identifies the entry to be inserted

value - The value for this entry

Throws:

IllegalArgumentException - if key is null or if the map does not allow null values and value is null.

DuplicateKeyException - if this entries already exists in the map

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

See Also:

put(Object, Object), update(Object, Object), CopyMode

getIndex

Object getIndex(String name)
                throws IndexUndefinedException,
                       IndexNotReadyException

Returns a reference to the named index that can be used with this Map. This index cannot be shared between threads and works on the same rules as Session. The returned value should be cast to the right index interface such as MapIndex, MapRangeIndex or a custom index interface such as a geo spatial index.

Parameters:

name - The index name

Returns:

A reference to the index, it must be cast to the appropriate index interface.

Throws:

IndexUndefinedException - if the index is not defined on the BackingMap

IndexNotReadyException - if the index is a dynamic index and it is not ready

Since:

WAS XD 6.0.1

getIndex

Object getIndex(String name,
              boolean forUpdate)
                throws IndexUndefinedException,
                       IndexNotReadyException

Returns a reference to the named index that can be used with this Map. This index cannot be shared between threads and works on the same rules as Session. The returned value should be cast to the right index interface such as MapIndex, MapRangeIndex or a custom index interface such as a geo spatial index.

Parameters:

name - The index name

forUpdate - if true, the returned index will always operate with forUpdate intent.

Returns:

A reference to the index, it must be cast to the appropriate index interface.

Throws:

IndexUndefinedException - if the index is not defined on the BackingMap

IndexNotReadyException - if the index is a dynamic index and it is not ready

Since:

WAS XD 6.1.0.1

flush

void flush()
           throws ObjectGridException

Pushes the current set of changes for the ObjectMap instance to the Loader without committing the changes. The changes are not propagated to the BackingMap either. This is useful for re-priming the Loader's data without committing the current transaction and starting over.

Throws:

ObjectGridException - if an error occurs during processing

See Also:

Session.flush()

containsKey

boolean containsKey(Object key)
                    throws ObjectGridException

Returns true if this map contains a mapping for the specified key. ObjectGrid does not support null keys. If you configured the map to support null values, this method can be used to determine whether a key is contained in the map or not.

This API does not hold any locks when using pessimistic locking.

Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.SHARED
Pessimistic locks held:	None
Transaction:	Automatic or manual
Cache tier:	Progresses to all tiers until the key is found.

Parameters:

key - key whose presence in this map is to be tested.

Returns:

true if this map contains a mapping for the specified key.

Throws:

IllegalArgumentException - if null key parameter is passed in

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

getJavaMap

Map getJavaMap()

Returns an implementation of java.util.Map that is backed by this ObjectMap.

The returned java.util.Map implementation can be cast to com.ibm.websphere.objectgrid.JavaMap to be able to use the rest of the ObjectGrid programming model, but with java.util.Map's use of RuntimeExceptions instead of checked ObjectGridExceptions.

Returns:

a java.util.Map backed by this ObjectMap

See Also:

Map, JavaMap

touch

void touch(Object key)
           throws ObjectGridException

Updates the last access time in the BackingMap without retrieving the value to the ObjectMap.

The last access time is updated during commit. If the key does not exist in the BackingMap, a TransactionException will be returned during commit processing. Specification details:

Required permission:	None
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

key - key to be touched

Throws:

IllegalArgumentException - if key is null

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

setCopyMode

void setCopyMode(CopyMode copyMode,
               Class valueInterface)
                 throws TransactionAlreadyActiveException,
                        ObjectGridException

Allows the CopyMode for the Map to be overridden on this map on this session only.

This method allows an application to use an optimal CopyMode TRANSACTION by TRANSACTION as its needs dictate. The CopyMode cannot be changed during a transaction. There must be no active transaction when this method is called.

Parameters:

copyMode - 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 copyMode is null or COPY_ON_WRITE CopyMode is specified and the required value interface parameter is null

TransactionAlreadyActiveException - if a transaction is active and this map has already been used in the transaction.

ObjectGridException - if an error occurs during processing

See Also:

BackingMap.setCopyMode(CopyMode, Class), CopyMode

clearCopyMode

void clearCopyMode()
                   throws TransactionAlreadyActiveException

Resets the CopyMode back to the one in the BackingMap.

This method is used to reverse a previous setCopyMode method call for this ObjectMap. This method can only be called when no transaction is active on the associated session.

Throws:

TransactionAlreadyActiveException - if a transaction is active and this map has already been used in the transaction.

See Also:

setCopyMode(CopyMode, Class)

getNextKey

Object getNextKey(long timeout)
                  throws ObjectGridException

Retrieves a key off the map in first-in-first-out (FIFO) insert order.

The entry is locked by the session such that other calls to getNextKey will not return the same key. The key can be used to remove or manipulate the value although leaving the entry will result in the key remaining at the beginning of the queue. This order is optimized for performance and is not guaranteed especially across partitions or in highly concurrent environments.

The return value is a SerializedKey when OutputFormat.RAW is set for the keys. The default key output format for maps that are associated with a KeySerializerPlugin is OutputFormat.RAW. The SerializedKey allows access to the value in its serialized form, or its native Java Object form.

The return value is a Tuple when an an EntityManager API entity is associated with the BackingMap.

Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.EXCLUSIVE
Pessimistic read lock held:	Yes
Transaction:	Automatic or manual

Parameters:

timeout - The period of time in milliseconds to wait for an entry to become available on the queue.

Returns:

the next key

Throws:

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

Since:

WAS XD 6.1

See Also:

QUEUE_TIMEOUT_INFINITE, QUEUE_TIMEOUT_NONE

getEntityMetadata

@Deprecated
EntityMetadata getEntityMetadata()

Deprecated. Deprecated in version 8.6.1.

Retrieve the metadata for the entity associated with this map.

Returns:

the EntityMetadata if an entity is associated with this map or null if there is no entity associated with this map.

Since:

WAS XD 6.1

getMapType

int getMapType()

Returns the type of the underlying BackingMap.

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

Returns:

the BackingMap type

Since:

WAS XD 6.1

getAgentManager

AgentManager getAgentManager()

Returns the Agent Manager that allows DataGrid operations to be performed on the objects within this Map.

This method should only be called on a client ObjectGrid. If called on a non client ObjectGrid an IllegalStateException will be thrown

Returns:

AgentManager

Throws:

IllegalStateException - if this method is invoked on a non client ObjectGrid

Since:

WAS XD 6.1

setLockTimeout

void setLockTimeout(int seconds)

Overrides the BackingMap's lock timeout for this ObjectMap.

Establishes the number of seconds that any given fetch (get, getForUpdate, find, findForUpdate) of a cache entry will wait to get a lock. When the lock strategy is LockStrategy.NONE, no lock manager is used by this map. In this case, a call to this method does nothing.

Parameters:

seconds - is the lock timeout in seconds. The value must be >= -1. A value of -1 is used to indicate to use the default setting. Use of the constantUSE_DEFAULT is recommended when "use default" setting is desired. A value of 0 indicates that if a lock cannot be retrieved immediately to time out without waiting for any period of time for the lock to be released and made available.

Throws:

IllegalArgumentException - if seconds argument is less than -1 (USE_DEFAULT)

Since:

WAS XD 6.1

See Also:

USE_DEFAULT, BackingMap.setLockTimeout(int), BackingMap.setLockStrategy(LockStrategy), LockStrategy.OPTIMISTIC, LockStrategy.PESSIMISTIC

clear

void clear()
           throws ObjectGridException

Clear all keys from the Map.

This method is an automatic transaction call. The Session.isTransactionActive() must answer false prior to invoking this method.

Specification details:

Required permission:	MapPermission.REMOVE
Pessimistic read lock acquired:	Map exclusive lock is acquired.
Transaction:	Hybrid. Each shard is cleared in a separate transaction.
Cache tier:	Applies to all cache tiers except the Loader.

Throws:

ObjectGridException - if an error occurs during processing

TransactionAlreadyActiveException - if a transaction is already started.

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

Since:

WAS XD 6.1.0.3

lock

boolean lock(Object key,
           LockMode lockMode)
             throws ObjectGridException

Obtains a lock for the given key. Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.SHARED, LockMode.UPGRADABLE or LockMode.EXCLUSIVE Note: Transaction isolation is ignored.
Pessimistic locks held:	Yes
Transaction:	Automatic or manual
Cache tier:	Progresses to all tiers until the key is found and the appropriate lock is acquired.

Parameters:

key - the key to lock

lockMode - the lockMode to obtain for the given key

Returns:

true if the entry exists in the grid or Loader (if one is defined)

Throws:

IllegalArgumentException - if key is null

IllegalStateException - if this map is not using LockStrategy.PESSIMISTIC LockStategy

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

Since:

8.6, XC10 2.5

lockAll

List<Boolean> lockAll(List keyList,
                    LockMode lockMode)
                      throws ObjectGridException

Obtains locks for the given keys. Specification details:

Required permission:	MapPermission.READ
Pessimistic read lock acquired:	LockMode.SHARED, LockMode.UPGRADABLE or LockMode.EXCLUSIVE Note: Transaction isolation is ignored.
Pessimistic locks held:	Yes
Transaction:	Automatic or manual
Cache tier:	Progresses to all tiers until the keys are found and the appropriate locks are acquired.

Parameters:

keyList - the keys to lock

lockMode - the lockMode to obtain for the given keys

Returns:

a List of Booleans indicating whether the entries exists in the grid or Loader (if one is defined)

Throws:

IllegalStateException - if this map is not using LockStrategy.PESSIMISTIC LockStategy

IllegalArgumentException - if keyList is null or contains a null element.

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

Since:

8.6, XC10 2.5

upsert

void upsert(Object key,
          Object value)
            throws ObjectGridException

Puts the Object value into the cache at location represented by key.

The value will be pushed down to the BackingMap/Loader at commit time. The semantics of this method are that the Loader will receive a LogElement.UPSERT operation and the map will either do an insert or an update to cause the map to contain this updated value. Note that this operation will not perform an implicit get of the entry from the map, and therefore it will not throw OptimisticCollisionException if the map's LockStrategy is LockStrategy.OPTIMISTIC. Whether or not a copy of the object is made when transaction is committed is determined by the copy mode setting for this map. See CopyMode for a description of each possible copy mode.

Specification details:

Required permission:	MapPermission.WRITE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

key - The entry to insert or update in the map

value - The value to insert or update in the map using the key

Throws:

IllegalArgumentException - if key is null, or if the map does not allow null values and value is null

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

Since:

8.6, XC10 2.5

See Also:

CopyMode

upsertAll

void upsertAll(LinkedHashMap map)
               throws ObjectGridException

Puts each of the Object value into the cache at location represented by key contained in the Map. The values will be pushed down to the BackingMap/Loader at commit time. The semantics of this method are that the Loader will receive a LogElement.UPSERT operation and the map will either do an insert or an update to cause the map to contain this updated value. Whether or not a copy of the objects is made when transaction is committed is determined by the copy mode setting for this map. See CopyMode for a description of each possible copy mode.

Specification details:

Required permission:	MapPermission.WRITE
Transaction:	Automatic or manual
Cache tier:	Applied to all tiers during commit. Use Session.beginNoWriteThrough() to limit the operation to the Client Cache tier for client maps, or the Server Cache tier for local or shard maps.

Parameters:

map - The key/values to be inserted or updated in the map. The type is LinkedHashMap so that the order can be controlled to avoid deadlocks.

Throws:

IllegalArgumentException - if map is null or contains a null key or if null values are not allowed and map contains a null value.

ObjectGridException - if an error occurs during processing

AccessControlException - if the Subject or Credential specified on the Session does not have the appropriate permission.

Since:

8.6, XC10 2.5

See Also:

CopyMode

getKeyOutputFormat

OutputFormat getKeyOutputFormat()

Retrieves the data format for all data access APIs that return cache keys for the current session.

Returns:

the data output format or null if the default should be used.

Since:

8.6, XC10 2.5

setKeyOutputFormat

void setKeyOutputFormat(OutputFormat outputFormat)
                        throws TransactionAlreadyActiveException

Sets the data format for all data access APIs that return cache keys for the current session.

This method supports map configurations with a KeyDataSerializer plug-in defined, or with eXtreme Data Format enabled.

Parameters:

outputFormat - the data output format to use or OutputFormat.UNDEFINED to use the default defined on the parent BackingMap.

Throws:

IllegalArgumentException - thrown when the data format is not valid for the current configuration.

TransactionAlreadyActiveException - if a transaction is active and this map has already been used in the transaction.

Since:

8.6, XC10 2.5

See Also:

BackingMap.getKeyOutputFormat()

getValueOutputFormat

OutputFormat getValueOutputFormat()

Retrieves the data format for all data access APIs that return cache values for the current session.

Returns:

the data output format or null if the default should be used.

Since:

8.6, XC10 2.5

setValueOutputFormat

void setValueOutputFormat(OutputFormat outputFormat)
                          throws TransactionAlreadyActiveException

Sets the data format for all data access APIs that return cache values for the current session.

This method is functionally equivalent to the setCopyMode(CopyMode, Class) with the CopyMode.COPY_TO_BYTES and CopyMode.COPY_TO_BYTES_RAW values when used with a ValueDataSerializer or eXtreme Data Format.

This method supports map configurations with a ValueDataSerializer plug-in defined, or with eXtreme Data Format enabled.

Parameters:

outputFormat - the data output format to use or OutputFormat.UNDEFINED to use the default defined on the parent BackingMap.

Throws:

IllegalArgumentException - thrown when the data format is not valid for the current configuration.

TransactionAlreadyActiveException - if a transaction is active and this map has already been used in the transaction.

Since:

8.6, XC10 2.5

setPutMode

void setPutMode(ObjectMap.PutMode putMode)
                throws TransactionAlreadyActiveException,
                       ObjectGridException

Allows the default operation for the put(Object, Object) and putAll(Map) methods to be changed, allowing the put to use the optimized upsert(Object, Object) and upsertAll(LinkedHashMap) implementations.

The PutMode cannot be changed during a transaction. There must be no active transaction when this method is called.

Parameters:

putMode - the mode in which the put methods operate.

Throws:

TransactionAlreadyActiveException - if a transaction is active and this map has already been used in the transaction.

ObjectGridException - if an error occurs during processing

Since:

8.6, XC10 2.5

getPutMode

ObjectMap.PutMode getPutMode()

Retrieve the current PutMode set for this ObjectMap instance.

Returns:

the current PutMode.

Since:

8.6, XC10 2.5