@Deprecated public interface JavaMap extends Map
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
to java.util.Map if they want.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 ObjectGridException
s, which are
checked exceptions.The only methods that are supported from the java.util.Map
interface are:
java.util.Map
interface will throw
java.lang.UnsupportedOperationException
.ObjectMap
,
ObjectMap.getJavaMap()
,
Map
,
BackingMap.setCopyMode(CopyMode, Class)
,
BackingMap.setLockStrategy(LockStrategy)
Modifier and Type | Method and Description |
---|---|
void |
clear()
Deprecated.
Clear all keys from the Map.
|
void |
clearCopyMode()
Deprecated.
Resets the CopyMode back to the one in the BackingMap.
|
boolean |
containsKey(Object key)
Deprecated.
Returns
true if this map contains a mapping for the specified
key. |
boolean |
containsValue(Object value)
Deprecated.
This method of the
java.util.Map interface is not supported. |
Set |
entrySet()
Deprecated.
This method of the
java.util.Map interface is not supported. |
void |
flush()
Deprecated.
Pushes the current set of changes for the
JavaMap
instance to the Loader without committing the changes. |
Object |
get(Object key)
Deprecated.
Retrieves the object from the cache at the given key.
|
List |
getAll(List keyList)
Deprecated.
Gets a list of entries from the map.
|
List |
getAllForUpdate(List keyList)
Deprecated.
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.
Retrieve the metadata for the entity associated with this map.
|
Object |
getForUpdate(Object key)
Deprecated.
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)
Deprecated.
Returns a reference to the named index that can be used with this Map.
|
String |
getName()
Deprecated.
Returns the name of the JavaMap as defined by the configuration.
|
Object |
getNextKey(long timeout)
Deprecated.
Retrieves a key off the map in first-in-first-out (FIFO) insert order.
|
void |
insert(Object key,
Object value)
Deprecated.
Performs an explicit insert of a given entry.
|
void |
invalidate(Object key,
boolean isGlobal)
Deprecated.
Invalidates an entry in the cache based on the key parameter.
|
void |
invalidateAll(Collection keyList,
boolean isGlobal)
Deprecated.
Invalidate a set of cache entries based on the Collection of
keys provided.
|
boolean |
isEmpty()
Deprecated.
This method of the
java.util.Map interface is not supported. |
Set |
keySet()
Deprecated.
This method of the
java.util.Map interface is not supported. |
Object |
put(Object key,
Object value)
Deprecated.
Puts the Object value into the cache at location represented by key.
|
void |
putAll(Map map)
Deprecated.
Puts each of the Object values into the cache at location represented by the corresponding key contained in the Map.
|
Object |
remove(Object key)
Deprecated.
Removes the Object value from the cache represented by key.
|
void |
removeAll(Collection keyList)
Deprecated.
Batch remove from the Map.
|
void |
setCopyMode(CopyMode copyMode,
Class valueInterface)
Deprecated.
Allows the CopyMode for the Map to be overridden on this map on this session only.
|
int |
setTimeToLive(int ttl)
Deprecated.
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()
Deprecated.
This method of the
java.util.Map interface is not supported. |
void |
touch(Object key)
Deprecated.
Updates the last access time in the BackingMap without retrieving
the value to the JavaMap.
|
void |
update(Object key,
Object value)
Deprecated.
Performs an explicit update of a given entry.
|
Collection |
values()
Deprecated.
This method of the
java.util.Map interface is not supported. |
String getName()
Object getForUpdate(Object key) throws ObjectGridRuntimeException
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.
key
- The entry to fetchnull
IllegalArgumentException
- if key is null
ObjectGridRuntimeException
- if an error occurs during processingcontainsKey(Object)
,
get(Object)
,
CopyMode
,
LockStrategy.PESSIMISTIC
,
ObjectMap.getForUpdate(Object)
List getAll(List keyList) throws ObjectGridRuntimeException
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.
keyList
- A list of keys for identifying which entries to fetchIllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridRuntimeException
- if an error occurs during processingget(Object)
,
ObjectMap.getAll(List)
List getAllForUpdate(List keyList) throws ObjectGridRuntimeException
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.
keyList
- A list of keys for identifying which entries to fetchIllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridRuntimeException
- if an error occurs during processinggetAll(List)
,
getForUpdate(Object)
,
LockStrategy.PESSIMISTIC
,
ObjectMap.getAllForUpdate(List)
void removeAll(Collection keyList) throws ObjectGridRuntimeException
See ObjectMap.removeAll(Collection)
for additional specification details.
keyList
- A list of keys for identifying which entries to removeIllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridRuntimeException
- if an error occurs during processingremove(Object)
,
ObjectMap.removeAll(Collection)
void invalidate(Object key, boolean isGlobal) throws ObjectGridRuntimeException
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.
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 JavaMap (false).IllegalArgumentException
- if key is null
ObjectGridRuntimeException
- if an error occurs during processingObjectMap.invalidate(Object, boolean)
void invalidateAll(Collection keyList, boolean isGlobal) throws ObjectGridRuntimeException
See ObjectMap.invalidateAll(Collection, boolean)
for additional specification details.
keyList
- A Collection of keys representing the entries to be invalidatedisGlobal
- Indicates whether to remove the entry from the BackingMap (true) or just the JavaMap (false).IllegalArgumentException
- if keyList is null or contains a null
element.ObjectGridRuntimeException
- if an error occurs during processinginvalidate(Object, boolean)
,
ObjectMap.invalidateAll(Collection, boolean)
int setTimeToLive(int ttl)
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.
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.ObjectMap.TTL_FOREVER
can be used
to determine if the previous TTL was set to "forever".IllegalArgumentException
- if seconds argument is < 0.IllegalStateException
- if BackingMap.getTtlEvictorType()
returns anything other
than TTLType.LAST_ACCESS_TIME
.BackingMap.setTimeToLive(int)
,
ObjectMap.setTimeToLive(int)
,
TTLType.LAST_ACCESS_TIME
void update(Object key, Object value) throws ObjectGridRuntimeException
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.
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
.ObjectGridRuntimeException
- if an error occurs during processinginsert(Object, Object)
,
put(Object, Object)
,
CopyMode
,
LockStrategy.OPTIMISTIC
,
ObjectMap.update(Object, Object)
void insert(Object key, Object value) throws ObjectGridRuntimeException
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.
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
.ObjectGridRuntimeException
- if an error occurs during processingput(Object, Object)
,
update(Object, Object)
,
CopyMode
,
ObjectMap.insert(Object, Object)
Object getIndex(String name) throws IndexUndefinedException, IndexNotReadyException, UnsupportedOperationException
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 readyUnsupportedOperationException
- if the map is a distributed mapvoid flush() throws ObjectGridRuntimeException
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.ObjectGridRuntimeException
- if an error occurs during processingSession.flush()
,
ObjectMap.flush()
int size()
java.util.Map
interface is not supported.size
in interface Map
UnsupportedOperationException
- indicating this method is not supportedboolean isEmpty()
java.util.Map
interface is not supported.isEmpty
in interface Map
true
if this map contains no key-value mappings.UnsupportedOperationException
- indicating this method is not supportedboolean containsKey(Object key)
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.
containsKey
in interface Map
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 inObjectGridRuntimeException
- if an error occurs during processingObjectMap.containsKey(Object)
boolean containsValue(Object value)
java.util.Map
interface is not supported.containsValue
in interface Map
value
- value whose presence in this map is to be tested.true
if this map maps one or more keys to the
specified value.UnsupportedOperationException
- indicating this method is not supportedObject get(Object 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.
get
in interface Map
key
- The entry to fetchnull
, SerializedValue
or Tuple
IllegalArgumentException
- if key is null
ObjectGridRuntimeException
- if an error occurs during processingcontainsKey(Object)
,
getForUpdate(Object)
,
CopyMode
,
ObjectMap.get(Object)
Object put(Object key, Object value)
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.
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.
put
in interface Map
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
ObjectGridRuntimeException
- if an error occurs during processingCopyMode
,
ObjectMap.put(Object, Object)
Object remove(Object 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.
remove
in interface Map
key
- The entry to removeIllegalArgumentException
- if key is null
ObjectGridRuntimeException
- if an error occurs during processingObjectMap.remove(Object)
void putAll(Map 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.
putAll
in interface Map
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.ObjectGridRuntimeException
- if an error occurs during processingput(Object, Object)
,
ObjectMap.putAll(Map)
void clear()
This method is an auto-commit call, so a session should not be explicitly begun or committed when calling clear on the Map.
clear
in interface Map
ObjectGridRuntimeException
- if an error occurs during processingSet keySet()
java.util.Map
interface is not supported.keySet
in interface Map
UnsupportedOperationException
- indicating this method is not supportedCollection values()
java.util.Map
interface is not supported.values
in interface Map
UnsupportedOperationException
- indicating this method is not supportedSet entrySet()
java.util.Map
interface is not supported.entrySet
in interface Map
UnsupportedOperationException
- indicating this method is not supportedvoid touch(Object key)
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.
key
- key to be touchedIllegalArgumentException
- if key is null
ObjectGridRuntimeException
- if an error occurs during processingObjectMap.touch(Object)
void setCopyMode(CopyMode copyMode, Class valueInterface) throws ObjectGridRuntimeException
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
ObjectGridRuntimeException
- if a transaction is active and this map has already been used in the transaction or
an error occurs during processingBackingMap.setCopyMode(CopyMode, Class)
,
CopyMode
,
ObjectMap.setCopyMode(CopyMode, Class)
void clearCopyMode() throws ObjectGridRuntimeException
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.
ObjectGridRuntimeException
- if a transaction is active and this map has already been used in the transaction or
an error occurs during processingsetCopyMode(CopyMode, Class)
,
ObjectMap.clearCopyMode()
Object getNextKey(long timeout)
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.
timeout
- The period of time to wait for an entry to become available on the queue.ObjectMap.getNextKey(long)
EntityMetadata getEntityMetadata()