public interface ObjectMap
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.
|
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:
|
Session.getMap(String)
,
BackingMap.setCopyMode(CopyMode, Class)
,
BackingMap.setLockStrategy(LockStrategy)
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. |
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.
|
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.
|
static final int TTL_FOREVER
static final int USE_DEFAULT
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
static final long QUEUE_TIMEOUT_NONE
getNextKey(long)
method, specifies to return a null value if the map is
empty.static final long QUEUE_TIMEOUT_INFINITE
getNextKey(long)
method, specifies the method should block until a key
becomes available.String getName()
Object get(Object key) throws ObjectGridException
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. |
key
- The entry to fetchnull
, SerializedValue
or Tuple
IllegalArgumentException
- if key is null
ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.containsKey(Object)
,
getForUpdate(Object)
,
CopyMode
Object put(Object key, Object value) throws ObjectGridException
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. |
key
- The entry to put into the mapvalue
- The value to put into the map using the keyObjectMap.PutMode.INSERTUPDATE
is set, return the previous value in this transaction. If ObjectMap.PutMode.UPSERT
is set,
the return value is null.IllegalArgumentException
- if key is null
, or if the map does not allow null
values and value is
null
ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.CopyMode
Object getForUpdate(Object key) throws ObjectGridException
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. |
key
- The entry to fetchnull
, SerializedValue
or Tuple
IllegalArgumentException
- if key is null
ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.containsKey(Object)
,
get(Object)
,
CopyMode
,
LockStrategy.PESSIMISTIC
Object remove(Object key) throws ObjectGridException
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. |
key
- The entry to removeIllegalArgumentException
- if key is null
ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.List getAll(List keyList) throws ObjectGridException
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. |
keyList
- A list of keys for identifying which entries to fetchIllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.get(Object)
List getAllForUpdate(List keyList) throws ObjectGridException
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. |
keyList
- A list of keys for identifying which entries to fetchIllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.getAll(List)
,
getForUpdate(Object)
,
LockStrategy.PESSIMISTIC
void removeAll(Collection keyList) throws ObjectGridException
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. |
keyList
- A list of keys for identifying which entries to removeIllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.remove(Object)
void putAll(Map map) throws ObjectGridException
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. |
map
- The key/values to be put into the map.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 processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.put(Object, Object)
void invalidate(Object key, boolean isGlobal) throws ObjectGridException
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. |
key
- Object representing the key to be used for cache entry invalidationisGlobal
- Indicates whether to remove the entry from the BackingMap (true) or just the ObjectMap (false).IllegalArgumentException
- if key is null
ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.void invalidateAll(Collection keyList, boolean isGlobal) throws ObjectGridException
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. |
keyList
- A Collection of keys representing the entries to be invalidatedisGlobal
- Indicates whether to remove the entry from the BackingMap (true) or just the ObjectMap (false).IllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.invalidate(Object, boolean)
int setTimeToLive(int ttl)
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
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.TTL_FOREVER
and
constant USE_DEFAULT
can be used to determine if the previous
TTL is one of the special values.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.TTL_FOREVER
,
USE_DEFAULT
,
BackingMap.setTimeToLive(int)
,
TTLType.LAST_ACCESS_TIME
,
TTLType.LAST_UPDATE_TIME
void update(Object key, Object value) throws KeyNotFoundException, ObjectGridException
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. |
key
- Identifies the entry to be updatedvalue
- The updated value for this entryIllegalArgumentException
- 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 mapObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.insert(Object, Object)
,
put(Object, Object)
,
CopyMode
,
LockStrategy.OPTIMISTIC
void insert(Object key, Object value) throws DuplicateKeyException, ObjectGridException
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. |
key
- Identifies the entry to be insertedvalue
- The value for this entryIllegalArgumentException
- 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 mapObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.put(Object, Object)
,
update(Object, Object)
,
CopyMode
Object getIndex(String name) throws IndexUndefinedException, IndexNotReadyException
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.name
- The index nameIndexUndefinedException
- if the index is not defined on the BackingMapIndexNotReadyException
- if the index is a dynamic index and it is not readyObject getIndex(String name, boolean forUpdate) throws IndexUndefinedException, IndexNotReadyException
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.name
- The index nameforUpdate
- if true, the returned index will always operate with forUpdate intent.IndexUndefinedException
- if the index is not defined on the BackingMapIndexNotReadyException
- if the index is a dynamic index and it is not readyvoid flush() throws ObjectGridException
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.ObjectGridException
- if an error occurs during processingSession.flush()
boolean containsKey(Object key) throws ObjectGridException
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. |
key
- key whose presence in this map is to be tested.true
if this map contains a mapping for the specified key.IllegalArgumentException
- if null
key parameter is passed inObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.Map getJavaMap()
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 RuntimeException
s instead of checked
ObjectGridException
s.
void touch(Object key) throws ObjectGridException
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. |
key
- key to be touchedIllegalArgumentException
- if key is null
ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.void setCopyMode(CopyMode copyMode, Class valueInterface) throws TransactionAlreadyActiveException, ObjectGridException
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.
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.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 processingBackingMap.setCopyMode(CopyMode, Class)
,
CopyMode
void clearCopyMode() throws TransactionAlreadyActiveException
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.
TransactionAlreadyActiveException
- if a transaction is active and this map has already been used in the transaction.setCopyMode(CopyMode, Class)
Object getNextKey(long timeout) throws ObjectGridException
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 |
timeout
- The period of time in milliseconds to wait for an entry to become available on the queue.ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.QUEUE_TIMEOUT_INFINITE
,
QUEUE_TIMEOUT_NONE
@Deprecated EntityMetadata getEntityMetadata()
int getMapType()
The return value is equivalent to one of the constants declared on the BackingMap interface,
BackingMap.LOCAL
, BackingMap.SERVER
, or BackingMap.CLIENT
.
AgentManager getAgentManager()
This method should only be called on a client ObjectGrid. If called on a non client ObjectGrid an
IllegalStateException
will be thrown
IllegalStateException
- if this method is invoked on a non client ObjectGridvoid setLockTimeout(int seconds)
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.
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.IllegalArgumentException
- if seconds argument is less than -1 (USE_DEFAULT)USE_DEFAULT
,
BackingMap.setLockTimeout(int)
,
BackingMap.setLockStrategy(LockStrategy)
,
LockStrategy.OPTIMISTIC
,
LockStrategy.PESSIMISTIC
void clear() throws ObjectGridException
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. |
ObjectGridException
- if an error occurs during processingTransactionAlreadyActiveException
- if a transaction is already started.AccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.boolean lock(Object key, LockMode lockMode) throws ObjectGridException
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. |
key
- the key to locklockMode
- the lockMode to obtain for the given keyIllegalArgumentException
- if key is null
IllegalStateException
- if this map is not using LockStrategy.PESSIMISTIC
LockStategyObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.List<Boolean> lockAll(List keyList, LockMode lockMode) throws ObjectGridException
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. |
keyList
- the keys to locklockMode
- the lockMode to obtain for the given keysBoolean
s indicating whether the entries exists in the grid or Loader (if one is
defined)IllegalStateException
- if this map is not using LockStrategy.PESSIMISTIC
LockStategyIllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.void upsert(Object key, Object value) throws ObjectGridException
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. |
key
- The entry to insert or update in the mapvalue
- The value to insert or update in the map using the keyIllegalArgumentException
- if key is null
, or if the map does not allow null
values and value is
null
ObjectGridException
- if an error occurs during processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.CopyMode
void upsertAll(LinkedHashMap map) throws ObjectGridException
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. |
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.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 processingAccessControlException
- if the Subject or Credential specified on the Session does not have the appropriate permission.CopyMode
OutputFormat getKeyOutputFormat()
void setKeyOutputFormat(OutputFormat outputFormat) throws TransactionAlreadyActiveException
This method supports map configurations with a KeyDataSerializer
plug-in defined, or with
eXtreme Data Format enabled.
outputFormat
- the data output format to use or OutputFormat.UNDEFINED
to use the default defined
on the parent BackingMap
.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.BackingMap.getKeyOutputFormat()
OutputFormat getValueOutputFormat()
void setValueOutputFormat(OutputFormat outputFormat) throws TransactionAlreadyActiveException
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.
outputFormat
- the data output format to use or OutputFormat.UNDEFINED
to use the default defined
on the parent BackingMap
.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.void setPutMode(ObjectMap.PutMode putMode) throws TransactionAlreadyActiveException, ObjectGridException
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
- the mode in which the put
methods operate.TransactionAlreadyActiveException
- if a transaction is active and this map has already been used in the transaction.ObjectGridException
- if an error occurs during processingObjectMap.PutMode getPutMode()
PutMode
set for this ObjectMap instance.PutMode
.