IBM WebSphere Extended Deployment (XD)TM
Release 6.0

com.ibm.websphere.objectgrid
JavaMap

All Implemented Interfaces
Map


This is a handle to a named Map. Maps should have homogenous 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. Keywords are applied within a transaction. A transaction rollback will roll back any keywords association applied during this transaction.

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

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

All other methods on the java.util.Map interface will throw java.lang.UnsupportedOperationException.
See Also:
    ObjectMapgetJavaMap()MapsetCopyMode(CopyMode, Class)setLockStrategy(LockStrategy)



Method Summary
public  StringgetName()
           Returns the name of the JavaMap as defined by the configuration.
public  Objectget(java.lang.Object, java.io.Serializable)
           Gets an entry and associates it with the specified keyword. .
public  ObjectgetForUpdate(java.lang.Object)
           Same as #get(Object) method except that if pessimistic lock strategy is used for this map, then a upgradable lock mode is obtained for this map entry.
public  ObjectgetForUpdate(java.lang.Object, java.io.Serializable)
           The same as getForUpdate except the returned entry is associated with the specified keyword.
public  voidput(java.lang.Object, java.lang.Object, java.io.Serializable)
           Puts an entry in the cache and associates it with the specified keyword. .
public  ListgetAll(java.util.List)
           Gets a list of entries from the map. .
public  ListgetAll(java.util.List, java.io.Serializable)
           Gets a list of entries from the map and associates them with the specified keyword

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

public  ListgetAllForUpdate(java.util.List)
           Same as #getAll(List) method except that if pessimistic lock strategy is used for this map, then a upgradable lock mode is obtained for this map entry.
public  ListgetAllForUpdate(java.util.List, java.io.Serializable)
           The same as getAllForUpdate except the returned entries is associated with the specified keyword.
public  voidremoveAll(java.util.Collection)
           Batch remove from the Map. If a key in the list cannot be found, .
public  voidputAll(java.util.Map, java.io.Serializable)
           Batch put to the Map, with the addition of associating a keyword with each entry.
public  voidinvalidate(java.lang.Object, boolean)
           Invalidates an entry in the cache based on the key parameter..
public  voidinvalidateAll(java.util.Collection, boolean)
           Invalidate a set of cache entries based on the Collection of keys provided.
public  voidinvalidateUsingKeyword(java.io.Serializable, boolean)
           Invalidates a set of cache entries based on the keyword provided.
public  intsetTimeToLive(int)
           Establishes the number of seconds that any given cache entry can live for, which is refered to as "time to live" or TTL.
public  voidupdate(java.lang.Object, java.lang.Object)
           Performs an explicit update of a given entry..
public  voidupdate(java.lang.Object, java.lang.Object, java.io.Serializable)
           Performs an explicit update of a given entry, also associating the given keyword with the entry.
public  voidinsert(java.lang.Object, java.lang.Object)
           Performs an explicit insert of a given entry. .
public  voidinsert(java.lang.Object, java.lang.Object, java.io.Serializable)
           Performs an explicit insert of a given entry, also associating the given keyword with the entry.
public  ObjectgetIndex(java.lang.String)
           This returns a reference to the named index that can be used with this Map. This index.
public  voidflush()
           Pushes the current set of changes for the JavaMap instance to the Loader without committing the changes.
public  intsize()
           This method of the java.
public  booleanisEmpty()
           This method of the java.
public  booleancontainsKey(java.lang.Object)
           Returns true if this map contains a mapping for the specified key.
public  booleancontainsValue(java.lang.Object)
           This method of the java.
public  Objectget(java.lang.Object)
           Retrieves the object from the cache at the given key..
public  Objectput(java.lang.Object, java.lang.Object)
           Puts the Object value into the cache at location represented by key. .
public  Objectremove(java.lang.Object)
           Removes the Object value from the cache represented by key. .
public  voidputAll(java.util.Map)
           Batch put to the Map. .
public  voidclear()
           This method of the java.
public  SetkeySet()
           This method of the java.
public  Collectionvalues()
           This method of the java.
public  SetentrySet()
           This method of the java.
public  voidtouch(java.lang.Object)
           Updates the last access time in the BackingMap without retrieving the value to the JavaMap.
public  voidtouch(java.lang.Object, java.io.Serializable)
           Updates the last access time in the BackingMap without retrieving the value to the JavaMap and also associate a keyword with this entry.
public  voidsetCopyMode(com.ibm.websphere.objectgrid.CopyMode, java.lang.Class)
           Allows the CopyMode for the Map to be overridden on this map on this session only. .
public  voidclearCopyMode()
           Resets the CopyMode back to the one in the BackingMap..
public  voidsetDefaultKeyword(java.io.Serializable)
           Allows the setting of a default keyword..

Inherited Methods

Methods inherited from java.util.Map
equals, hashCode

Method Detail

getName

public String getName()
Returns the name of the JavaMap as defined by the configuration.


Returns:
     name of JavaMap


get

public Object get(Object key,Serializable keyword)
Gets an entry and associates it with the specified keyword.

The keyword is associated only when the transaction commits. 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 #containsKey.
See Also:

    get(Object)get(Object, Serializable)
Parameters:
    key - The entry to fetch
    keyword - The keyword to associate with this entry if it exists.


Returns:
     the value or null


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


getForUpdate

public Object getForUpdate(Object key)
Same as #get(Object) method except that if pessimistic lock strategy is used for this map, then a 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 a value is null and this map allows null values. To distinguish the two, use #containsKey.
See Also:
    get(Object)getForUpdate(Object)
Parameters:
    key - The entry to fetch


Returns:
     the value retrieved for update or null


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


getForUpdate

public Object getForUpdate(Object key,Serializable keyword)
The same as getForUpdate except the returned entry is associated with the specified keyword.
See Also:
    getForUpdate(Object)get(Object, Serializable)getForUpdate(Object, Serializable)
Parameters:
    key - The entry to fetch
    keyword - The keyword to associate with the returned entry


Returns:
     the value retrieved for update purposes or null


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


put

public void put(Object key,Object value, Serializable keyword)
Puts an entry in the cache and associates it with the specified keyword.

The keyword is added to the current set of keywords for the entry. Whether or not a copy of the object is made when the transaction is committed is determined by the CopyMode setting for this map. See CopyMode for a description of each possible CopyMode.


See Also:

    put(Object, Object)put(Object, Object, Serializable)
Parameters:
    key - The key of the entry to update or insert
    value - The new value
    keyword - The keyword


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


getAll

public List getAll(List keyList)
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.
See Also:

    get(Object)getAll(List)
Parameters:
    keyList - A list of keys for identifying which entries to fetch


Returns:
     a list of values


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


getAll

public List getAll(List keyList,Serializable keyword)
Gets a list of entries from the map and associates them with the specified keyword

If a key in the list cannot be found, a null value will be set at the appropriate position in the returned list. All returned entries will also be associated with the specified keyword.
See Also:

    get(Object, Serializable)getAll(List)getAll(List, Serializable)
Parameters:
    keyList - A list of keys for identifying which entries to fetch
    keyword - the keyword to associate with each fetched entry


Returns:
     a list of values


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


getAllForUpdate

public List getAllForUpdate(List keyList)
Same as #getAll(List) method except that if pessimistic lock strategy is used for this map, then a upgradable lock mode is obtained for this map entry. 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.
See Also:
    getAll(List)getForUpdate(Object)getAllForUpdate(List)
Parameters:
    keyList - A list of keys for identifying which entries to fetch


Returns:
     a list of values


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


getAllForUpdate

public List getAllForUpdate(List keyList,Serializable keyword)
The same as getAllForUpdate except the returned entries is associated with the specified keyword.
See Also:
    getAll(List)getForUpdate(Object)getAllForUpdate(List, Serializable)
Parameters:
    keyList - A list of keys for identifying which entries to fetch
    keyword - the keyword to associate with each fetched entry


Returns:
     the list of values


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


removeAll

public void removeAll(Collection keyList)
Batch remove from the Map. If a key in the list cannot be found, it will be ignored.
See Also:
    remove(Object)removeAll(Collection)
Parameters:
    keyList - A list of keys for identifying which entries to remove


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


putAll

public void putAll(Map map,Serializable keyword)
Batch put to the Map, with the addition of associating a keyword with each entry.
See Also:
    putAll(Map)putAll(Map, Serializable)
Parameters:
    map - The key/values to be put into the map.
    keyword - The keyword to associate with all these entries.


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


invalidate

public void invalidate(Object key,boolean isGlobal)
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, then 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, then when the transaction is committed, the key is removed from the BackingMap also. If a subsequent get operation is performed, then the BackingMap will be skipped and the Loader will be used to get the data. If isGlobal is false, then the entry is only invalidated in the JavaMap (transactional cache). If a subsequent get operation is performed then the BackingMap can be used and, if it's not in the BackingMap, then 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 Also:

    invalidate(Object, boolean)
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:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


invalidateAll

public void invalidateAll(Collection keyList,boolean isGlobal)
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 Also:
    invalidate(Object, boolean)invalidateAll(Collection, boolean)
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:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


invalidateUsingKeyword

public void invalidateUsingKeyword(Serializable keyword,boolean isGlobal)
Invalidates a set of cache entries based on the keyword provided.
See Also:
    invalidateUsingKeyword(Serializable, boolean)
Parameters:
    keyword - The keyword to be used for finding associated entries
    isGlobal - Indicates whether to remove the entry from the BackingMap (true) or just the JavaMap (false).


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


setTimeToLive

public 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 JsvaMap, 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, then 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 ObjectMap and the TTLType is something other than LAST_ACCESS_TIME, an IllegalStateException is thrown.
See Also:

    setTimeToLive(int)setTimeToLive(int)LAST_ACCESS_TIME
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:
    java.lang.IllegalArgumentExceptionjava.lang.IllegalStateException


update

public void update(Object key,Object value)
Performs an explicit update of a given entry.

A get operation is not required prior to invoking the update (unlike the put method). Also, an update invocation will never insert a new record. 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 description of each possible CopyMode.

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


See Also:
    insert(Object, Object)put(Object, Object)update(Object, Object)
Parameters:
    key - Identifies the entry to be updated
    value - The updated value for this entry


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


update

public void update(Object key,Object value, Serializable keyword)
Performs an explicit update of a given entry, also associating the given keyword with the entry.

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 description of each possible copy mode.


See Also:
    update(Object, Object)update(Object, Object, Serializable)
Parameters:
    key - Identifies the entry to be updated
    value - The updated value for this entry
    keyword - The keyword to associate with this entry.


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


insert

public void insert(Object key,Object value)
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 description of each possible CopyMode.

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


See Also:
    put(Object, Object)update(Object, Object)insert(Object, Object)
Parameters:
    key - Identifies the entry to be inserted
    value - The value for this entry


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


insert

public void insert(Object key,Object value, Serializable keyword)
Performs an explicit insert of a given entry, also associating the given keyword with the entry.

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 description of each possible copy mode.

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


See Also:
    insert(Object, Object)insert(Object, Object, Serializable)
Parameters:
    key - Identifies the entry to be inserted
    value - The value for this entry
    keyword - The keyword to associate with the entry.


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


getIndex

public Object getIndex(String name)
This 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 or MapRangeIndex or a custom index interface such as geo spatial index.
Parameters:
    name - The index name


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


Throws:
    com.ibm.websphere.objectgrid.IndexUndefinedExceptioncom.ibm.websphere.objectgrid.IndexNotReadyExceptionjava.lang.UnsupportedOperationException


flush

public void flush()
Pushes the current set of changes for the JavaMap instance to the Loader without committing the changes. The changes are not propogated to the BackingMap either. This is useful for re-priming the Loader's data without committing the current transaction and starting over.
See Also:
    flush()


Throws:
    com.ibm.websphere.objectgrid.ObjectGridRuntimeException


size

public int size()
This method of the java.util.Map interface is not supported.
See Also:
    size()


Throws:
    java.lang.UnsupportedOperationException


isEmpty

public boolean isEmpty()
This method of the java.util.Map interface is not supported.
See Also:
    isEmpty()


Throws:
    java.lang.UnsupportedOperationException


containsKey

public 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.
See Also:
    containsKey(Object)containsKey(Object)
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:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


containsValue

public boolean containsValue(Object value)
This method of the java.util.Map interface is not supported.
See Also:
    containsValue(Object)
Parameters:


Throws:
    java.lang.UnsupportedOperationException


get

public 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 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 #containsKey.
See Also:

    get(Object)getForUpdate(Object)get(Object)
Parameters:
    key - The entry to fetch


Returns:
     Object The value retrieved.


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


put

public Object put(Object key,Object value)
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 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 a map, a put following a get is an insert.

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 description of each possible copy mode.


See Also:
    put(java.lang.Object, java.lang.Object)put(Object, Object)
Parameters:
    key - The entry to put into the map
    value - The value to put into the map using the key


Returns:
     the previous value in this transaction


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


remove

public 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.
See Also:

    remove(Object)remove(Object)
Parameters:
    key - The entry to remove


Returns:
     the previous value in this transaction


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


putAll

public void putAll(Map map)
Batch put to the Map.

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 Also:

    putAll(Map)put(Object, Object)putAll(Map)
Parameters:
    map - The key/values to be put into the map.


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


clear

public void clear()
This method of the java.util.Map interface is not supported.
See Also:
    clear()


Throws:
    java.lang.UnsupportedOperationException


keySet

public Set keySet()
This method of the java.util.Map interface is not supported.
See Also:
    keySet()


Throws:
    java.lang.UnsupportedOperationException


values

public Collection values()
This method of the java.util.Map interface is not supported.
See Also:
    values()


Throws:
    java.lang.UnsupportedOperationException


entrySet

public Set entrySet()
This method of the java.util.Map interface is not supported.
See Also:
    entrySet()


Throws:
    java.lang.UnsupportedOperationException


touch

public 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 Also:

    touch(Object)
Parameters:
    key - key to be touched


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


touch

public void touch(Object key,Serializable keyword)
Updates the last access time in the BackingMap without retrieving the value to the JavaMap and also associate a keyword with this entry.

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 Also:

    touch(Object)touch(Object, Serializable)
Parameters:
    key - key to be touched
    keyword - keyword to add to this entry


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


setCopyMode

public void setCopyMode(CopyMode copyMode,Class valueInterface)
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.
See Also:

    setCopyMode(CopyMode, Class)CopyModesetCopyMode(CopyMode, Class)
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 - is a value interface Class object. A non-null valueInterface is required when mode is set to CopyMode.COPY_ON_WRITE. It is ignored for all other modes.


Throws:
    java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridRuntimeException


clearCopyMode

public void clearCopyMode()
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.
See Also:

    setCopyMode(CopyMode, Class)clearCopyMode()


Throws:
    com.ibm.websphere.objectgrid.ObjectGridRuntimeException


setDefaultKeyword

public void setDefaultKeyword(Serializable keyword)
Allows the setting of a default keyword.

The default keyword is used for any subsequent gets, updates, puts, etc. method invocations that do not have a keyword parameter. To reset the default keyword a parameter of null should be passed to this method. The default keyword is not used when any of the appropriate gets, updates, puts, etc. methods with a keyword paramater is invoked.
See Also:

    setDefaultKeyword(Serializable)
Parameters:
    keyword - default keyword value to use


IBM WebSphere Extended Deployment (XD)TM
Release 6.0