com.ibm.websphere.objectgrid
Interface JavaMap

All Superinterfaces:

Map

public interface JavaMap
extends Map

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

Users can get an instance of JavaMap from an instance of ObjectMap by calling ObjectMap.getJavaMap(). There are two main differences between JavaMap and ObjectMap:

• JavaMap extends java.util.Map. Therefore, users can cast an instance of JavaMap to java.util.Map if they want.
• The methods in JavaMap are defined to throw Exceptions similar to those defined on the java.util.Map interface that is ObjectGridRuntimeException, which is a subclass of java.lang.RuntimeException is used for error conditions. The methods in ObjectMap are defined to throw ObjectGridExceptions, which are checked exceptions.

The only methods that are supported from the java.util.Map interface are:

• containsKey(Object)
• get(Object)
• put(Object, Object)
• putAll(Map)
• remove(Object)
• clear()

All other methods on the java.util.Map interface will throw java.lang.UnsupportedOperationException.

Since:

WAS XD 6.0, XC10

See Also:

ObjectMap, ObjectMap.getJavaMap(), Map, BackingMap.setCopyMode(CopyMode, Class), BackingMap.setLockStrategy(LockStrategy)

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

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.
boolean	containsValue(Object value) This method of the java.util.Map interface is not supported.
Set	entrySet() This method of the java.util.Map interface is not supported.
void	flush() Pushes the current set of changes for the JavaMap instance to the Loader without committing the changes.
Object	get(Object key) Retrieves the object from the cache at the given key.
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() Retrieve the metadata for the entity associated with this map.
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.
String	getName() Returns the name of the JavaMap as defined by the configuration.
Object	getNextKey(long timeout) Retrieves a key off the map in first-in-first-out (FIFO) insert order.
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	isEmpty() This method of the java.util.Map interface is not supported.
Set	keySet() This method of the java.util.Map interface is not supported.
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 values into the cache at location represented by the corresponding 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.
int	setTimeToLive(int ttl) Establishes the number of seconds that any given cache entry can live for, which is refered to as "time to live" or TTL.
int	size() This method of the java.util.Map interface is not supported.
void	touch(Object key) Updates the last access time in the BackingMap without retrieving the value to the JavaMap.
void	update(Object key, Object value) Performs an explicit update of a given entry.
Collection	values() This method of the java.util.Map interface is not supported.

Methods inherited from interface java.util.Map

equals, hashCode

Method Detail

getName

String getName()

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

Returns:

name of JavaMap

getForUpdate

Object getForUpdate(Object key)
                    throws ObjectGridRuntimeException

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.

See ObjectMap.getForUpdate(Object) for additional specification details.

Parameters:

key - The entry to fetch

Returns:

the value retrieved for update or null

Throws:

IllegalArgumentException - if key is null

ObjectGridRuntimeException - if an error occurs during processing

See Also:

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

getAll

List getAll(List keyList)
            throws ObjectGridRuntimeException

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.

See ObjectMap.getAll(List) for additional specification details.

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.

ObjectGridRuntimeException - if an error occurs during processing

See Also:

get(Object), ObjectMap.getAll(List)

getAllForUpdate

List getAllForUpdate(List keyList)
                     throws ObjectGridRuntimeException

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.

See ObjectMap.getAllForUpdate(List) for additional specification details.

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.

ObjectGridRuntimeException - if an error occurs during processing

See Also:

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

removeAll

void removeAll(Collection keyList)
               throws ObjectGridRuntimeException

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

See ObjectMap.removeAll(Collection) for additional specification details.

Parameters:

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

Throws:

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

ObjectGridRuntimeException - if an error occurs during processing

See Also:

remove(Object), ObjectMap.removeAll(Collection)

invalidate

void invalidate(Object key,
                boolean isGlobal)
                throws ObjectGridRuntimeException

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

If the key's value has changes pending in the JavaMap, 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 JavaMap. 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 JavaMap (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.

See ObjectMap.invalidate(Object, boolean) for additional specification details.

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 JavaMap (false).

Throws:

IllegalArgumentException - if key is null

ObjectGridRuntimeException - if an error occurs during processing

See Also:

ObjectMap.invalidate(Object, boolean)

invalidateAll

void invalidateAll(Collection keyList,
                   boolean isGlobal)
                   throws ObjectGridRuntimeException

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.

See ObjectMap.invalidateAll(Collection, boolean) for additional specification details.

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 JavaMap (false).

Throws:

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

ObjectGridRuntimeException - if an error occurs during processing

See Also:

invalidate(Object, boolean), ObjectMap.invalidateAll(Collection, boolean)

setTimeToLive

int setTimeToLive(int ttl)

Establishes the number of seconds that any given cache entry can live for, which is refered 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 JavaMap, any previous value set by the BackingMap.setTimeToLive(int) method is overridden for this JavaMap. If this method is never called on the JavaMap, the TTL value from the BackingMap setting is used by default. 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 on the BackingMap. If this method is called on the JavaMap and the TTLType is something other than LAST_ACCESS_TIME, an IllegalStateException is thrown.

Parameters:

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

Returns:

previous time-to-live value in seconds. The constant ObjectMap.TTL_FOREVER can be used to determine if the previous TTL was set to "forever".

Throws:

IllegalArgumentException - if seconds argument is < 0.

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

See Also:

BackingMap.setTimeToLive(int), ObjectMap.setTimeToLive(int), TTLType.LAST_ACCESS_TIME

update

void update(Object key,
            Object value)
            throws ObjectGridRuntimeException

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.

See ObjectMap.update(Object, Object) for additional specification details.

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.

ObjectGridRuntimeException - if an error occurs during processing

See Also:

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

insert

void insert(Object key,
            Object value)
            throws ObjectGridRuntimeException

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.

See ObjectMap.insert(Object, Object) for additional specification details.

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.

ObjectGridRuntimeException - if an error occurs during processing

See Also:

put(Object, Object), update(Object, Object), CopyMode, ObjectMap.insert(Object, Object)

getIndex

Object getIndex(String name)
                throws IndexUndefinedException,
                       IndexNotReadyException,
                       UnsupportedOperationException

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

UnsupportedOperationException - if the map is a distributed map

Since:

WAS XD 6.0.1

flush

void flush()
           throws ObjectGridRuntimeException

Pushes the current set of changes for the JavaMap 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:

ObjectGridRuntimeException - if an error occurs during processing

See Also:

Session.flush(), ObjectMap.flush()

size

int size()

This method of the java.util.Map interface is not supported.

Specified by:

size in interface Map

Returns:

the number of key-value mappings in this map.

Throws:

UnsupportedOperationException - indicating this method is not supported

isEmpty

boolean isEmpty()

This method of the java.util.Map interface is not supported.

Specified by:

isEmpty in interface Map

Returns:

true if this map contains no key-value mappings.

Throws:

UnsupportedOperationException - indicating this method is not supported

containsKey

boolean containsKey(Object key)

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.

See ObjectMap.containsKey(Object) for additional specification details.

Specified by:

containsKey in interface Map

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

ObjectGridRuntimeException - if an error occurs during processing

See Also:

ObjectMap.containsKey(Object)

containsValue

boolean containsValue(Object value)

This method of the java.util.Map interface is not supported.

Specified by:

containsValue in interface Map

Parameters:

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

Returns:

true if this map maps one or more keys to the specified value.

Throws:

UnsupportedOperationException - indicating this method is not supported

get

Object get(Object key)

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.

See ObjectMap.get(Object) for additional specification details.

Specified by:

get in interface Map

Parameters:

key - The entry to fetch

Returns:

the value, null, SerializedValue or Tuple

Throws:

IllegalArgumentException - if key is null

ObjectGridRuntimeException - if an error occurs during processing

See Also:

containsKey(Object), getForUpdate(Object), CopyMode, ObjectMap.get(Object)

put

Object put(Object key,
           Object value)

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

The values will be pushed down to the BackingMap/Loader at commit time and has two behaviors, which can be altered using the ObjectMap.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 ObjectMap.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.

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.

See ObjectMap.put(Object, Object) for additional specification details.

Specified by:

put in interface Map

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

ObjectGridRuntimeException - if an error occurs during processing

See Also:

CopyMode, ObjectMap.put(Object, Object)

remove

Object remove(Object key)

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.

See ObjectMap.remove(Object) for additional specification details.

Specified by:

remove in interface Map

Parameters:

key - The entry to remove

Returns:

the current value at invocation time

Throws:

IllegalArgumentException - if key is null

ObjectGridRuntimeException - if an error occurs during processing

See Also:

ObjectMap.remove(Object)

putAll

void putAll(Map map)

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

The value will be pushed down to the BackingMap/Loader at commit time and has two behaviors, which can be altered using the ObjectMap.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 ObjectMap.upsert(Object, Object).

Whether or not a copy of the objects contained in the map 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.

See ObjectMap.putAll(Map) for additional specification details.

Specified by:

putAll in interface Map

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.

ObjectGridRuntimeException - if an error occurs during processing

See Also:

put(Object, Object), ObjectMap.putAll(Map)

clear

void clear()

Clear all keys from the Map.

This method is an auto-commit call, so a session should not be explicitly begun or committed when calling clear on the Map.

Specified by:

clear in interface Map

Throws:

ObjectGridRuntimeException - if an error occurs during processing

Since:

WAS XD 6.1.0.3

keySet

Set keySet()

This method of the java.util.Map interface is not supported.

Specified by:

keySet in interface Map

Returns:

a set view of the keys contained in this map.

Throws:

UnsupportedOperationException - indicating this method is not supported

values

Collection values()

This method of the java.util.Map interface is not supported.

Specified by:

values in interface Map

Returns:

a collection view of the values contained in this map.

Throws:

UnsupportedOperationException - indicating this method is not supported

entrySet

Set entrySet()

This method of the java.util.Map interface is not supported.

Specified by:

entrySet in interface Map

Returns:

a set view of the mappings contained in this map.

Throws:

UnsupportedOperationException - indicating this method is not supported

touch

void touch(Object key)

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

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.

See ObjectMap.touch(Object) for additional specification details.

Parameters:

key - key to be touched

Throws:

IllegalArgumentException - if key is null

ObjectGridRuntimeException - if an error occurs during processing

See Also:

ObjectMap.touch(Object)

setCopyMode

void setCopyMode(CopyMode copyMode,
                 Class valueInterface)
                 throws ObjectGridRuntimeException

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

ObjectGridRuntimeException - if a transaction is active on the associated session or an error occurs during processing

See Also:

BackingMap.setCopyMode(CopyMode, Class), CopyMode, ObjectMap.setCopyMode(CopyMode, Class)

clearCopyMode

void clearCopyMode()
                   throws ObjectGridRuntimeException

Resets the CopyMode back to the one in the BackingMap.

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

Throws:

ObjectGridRuntimeException - if a transaction is active on the associated session

See Also:

setCopyMode(CopyMode, Class), ObjectMap.clearCopyMode()

getNextKey

Object getNextKey(long timeout)

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.

See ObjectMap.getNextKey(long) for additional specification details.

Parameters:

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

Returns:

The next available key in the map.

See Also:

ObjectMap.getNextKey(long)

getEntityMetadata

EntityMetadata getEntityMetadata()

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