| IBM WebSphere Extended Deployment (XD)TM
Release 6.0.1 |
com.ibm.websphere.objectgrid
ObjectMap
This is a handle to a named Map. Maps should have homogenous keys and values.
An instance of this ObjectMap can only be used by the thread that is currently
associated with the Session that was used to get this ObjectMap instance.
Both Session and ObjectMap objects are not allowed to be shared by multiple
threads concurrently. Keywords are applied within a transaction. A transaction
rollback will rollback any keywords association applied during this transaction.
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.
See Also:
getMap(String)setCopyMode(CopyMode, Class)setLockStrategy(LockStrategy)
Field Summary |
public int | TTL_FOREVER
A constant indicating the time-to-live value is "forever".
|
Method Summary |
public
String | getName()
Returns the name of the ObjectMap as defined by the configuration.
|
public
Object | get(java.lang.Object)
Retrieves the object from the cache at the given key..
|
public
Object | get(java.lang.Object, java.io.Serializable)
Gets an entry and associates it with the specified keyword. .
|
public
Object | put(java.lang.Object, java.lang.Object)
Puts the Object value into the cache at location represented by key. .
|
public
Object | getForUpdate(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
Object | getForUpdate(java.lang.Object, java.io.Serializable)
The same as getForUpdate except the returned entry is associated with the specified
keyword.
|
public
Object | remove(java.lang.Object)
Removes the Object value from the cache represented by key. .
|
public
void | put(java.lang.Object, java.lang.Object, java.io.Serializable)
Puts an entry in the cache and associates it with the specified keyword. .
|
public
List | getAll(java.util.List)
Gets a list of entries from the map. .
|
public
List | getAll(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
List | getAllForUpdate(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
List | getAllForUpdate(java.util.List, java.io.Serializable)
The same as getAllForUpdate except the returned entries is associated with the specified
keyword.
|
public
void | removeAll(java.util.Collection)
Batch remove from the Map. If a key in the list cannot be found, .
|
public
void | putAll(java.util.Map)
Batch put to the Map. .
|
public
void | putAll(java.util.Map, java.io.Serializable)
Batch put to the Map, with the addition of associating a keyword
with each entry.
|
public
void | invalidate(java.lang.Object, boolean)
Invalidates an entry in the cache based on the key parameter..
|
public
void | invalidateAll(java.util.Collection, boolean)
Invalidate a set of cache entries based on the Collection of
keys provided.
|
public
void | invalidateUsingKeyword(java.io.Serializable, boolean)
Invalidates a set of cache entries based on the keyword provided.
|
public
int | setTimeToLive(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
void | update(java.lang.Object, java.lang.Object)
Performs an explicit update of a given entry..
|
public
void | update(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
void | insert(java.lang.Object, java.lang.Object)
Performs an explicit insert of a given entry. .
|
public
void | insert(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
Object | getIndex(java.lang.String)
This returns a reference to the named index that can be used with this Map. This index.
|
public
void | flush()
Pushes the current set of changes for the ObjectMap
instance to the Loader without committing the changes.
|
public
boolean | containsKey(java.lang.Object)
Returns true if this map contains a mapping for the specified
key.
|
public
Map | getJavaMap()
Returns an implementation of java.util.Map that is.
|
public
void | touch(java.lang.Object)
Updates the last access time in the BackingMap without retrieving
the value to the ObjectMap.
|
public
void | touch(java.lang.Object, java.io.Serializable)
Updates the last access time in the BackingMap without retrieving
the value to the ObjectMap and also associate a keyword with this entry.
|
public
void | setCopyMode(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
void | clearCopyMode()
Resets the CopyMode back to the one in the BackingMap..
|
public
void | setDefaultKeyword(java.io.Serializable)
Allows the setting of a default keyword..
|
TTL_FOREVER
public
static TTL_FOREVER
A constant indicating the time-to-live value is "forever".
getName
Returns the name of the ObjectMap as defined by the configuration.
Returns:
name of ObjectMap
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)
Parameters:
key
-
The entry to fetch
Returns:
Object The value retrieved.
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.ObjectGridException
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.
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.ObjectGridException
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)
Parameters:
key
-
The entry to fetch
Returns:
the value retrieved for update or null
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.ObjectGridException
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.
Parameters:
key
-
The entry to remove
Returns:
the previous value in this transaction
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.ObjectGridException
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)
Parameters:
keyList
-
A list of keys for identifying which entries to fetch
Returns:
a list of values
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.ObjectGridException
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)
Parameters:
keyList
-
A list of keys for identifying which entries to fetch
Returns:
a list of values
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.ObjectGridException
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)
Parameters:
keyList
-
A list of keys for identifying which entries to remove
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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:
-
put(Object, Object)
Parameters:
map
-
The key/values to be put into the map.
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.ObjectGridException
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 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, then 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, 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 ObjectMap (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.
Parameters:
key
-
Object representing the key to be used for cache entry invalidation
isGlobal
-
Indicates whether to remove the entry from the BackingMap (true) or just the ObjectMap (false).
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
Parameters:
keyList
-
A Collection of keys representing the entries to be invalidated
isGlobal
-
Indicates whether to remove the entry from the BackingMap (true) or just the ObjectMap (false).
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
invalidateUsingKeyword
public void invalidateUsingKeyword( | Serializable keyword , | | boolean isGlobal )
|
Invalidates a set of cache entries based on the keyword provided.
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 ObjectMap (false).
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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 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 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)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 #TTL_FOREVER is recommended when "forever" is desired.
Returns:
previous time-to-live value in seconds. The constant #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)
Parameters:
key
-
Identifies the entry to be updated
value
-
The updated value for this entry
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.KeyNotFoundExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.KeyNotFoundExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
Parameters:
key
-
Identifies the entry to be inserted
value
-
The value for this entry
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.DuplicateKeyExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)
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.DuplicateKeyExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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
Pushes the current set of changes for the ObjectMap
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.ObjectGridException
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.
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.ObjectGridException
getJavaMap
Returns an implementation of java.util.Map
that is
backed by this ObjectMap
.
The returned java.util.Map
implementation can be cast to com.ibm.websphere.objectgrid.JavaMap
to be able to use the rest of the ObjectGrid programming model, but
with java.util.Map
's use of RuntimeException
s
instead of checked ObjectGridException
s.
See Also:
-
MapJavaMap
Returns:
a java.util.Map
backed by this ObjectMap
touch
public void touch( | | Object key )
|
Updates the last access time in the BackingMap without retrieving
the value to the ObjectMap.
The last access time is updated during
commit. If the key does not exist in the BackingMap, a
TransactionException will be returned during commit processing.
Parameters:
key
-
key to be touched
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
touch
public void touch( | Object key , | | Serializable keyword )
|
Updates the last access time in the BackingMap without retrieving
the value to the ObjectMap 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)
Parameters:
key
-
key to be touched
keyword
-
keyword to add to this entry
Throws:
java.lang.IllegalArgumentExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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)CopyMode
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.TransactionAlreadyActiveExceptioncom.ibm.websphere.objectgrid.ObjectGridException
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 ObjectMap.
This method can only be called when no transaction is active on the associated session.
See Also:
-
setCopyMode(CopyMode, Class)
Throws:
com.ibm.websphere.objectgrid.TransactionAlreadyActiveException
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.
Parameters:
keyword
-
default keyword value to use
| IBM WebSphere Extended Deployment (XD)TM
Release 6.0.1 |