Skip navigation links

com.tangosol.util
Class SimpleMapEntry

java.lang.Object
com.tangosol.util.Base
com.tangosol.util.SimpleMapEntry

All Implemented Interfaces:

InvocableMap.Entry, MapTrigger.Entry, QueryMap.Entry, java.io.Serializable, java.lang.Cloneable, java.util.Map.Entry

Direct Known Subclasses:

AbstractKeyBasedMap.EntrySet.Entry, BinaryMap.Entry, InvocableMapHelper.SimpleEntry, SimpleElement.AttributeMap.Entry

public class SimpleMapEntry

extends Base

implements MapTrigger.Entry, java.lang.Cloneable, java.io.Serializable

A map entry (key-value pair). The Map.entrySet method returns a collection-view of the map, whose elements are of this class. The only way to obtain a reference to a map entry is from the iterator of this collection-view. These Map.Entry objects are valid only for the duration of the iteration; more formally, the behavior of a map entry is undefined if the backing map has been modified after the entry was returned by the iterator, except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator.

Author:

cp 2002.02.07

Field Summary

protected java.lang.Object	m_oKey The key.
protected java.lang.Object	m_oOrigValue The original value.
protected java.lang.Object	m_oValue The value.
protected static java.lang.Object	NO_VALUE Constant used to indicate that the original value does not exist.

Constructor Summary

protected	SimpleMapEntry() Default constructor.
	SimpleMapEntry(java.util.Map.Entry entry) Copy constructor.
protected	SimpleMapEntry(java.lang.Object oKey) Construct a SimpleMapEntry with just a key.
	SimpleMapEntry(java.lang.Object oKey, java.lang.Object oValue) Construct a SimpleMapEntry with a key and a value.
	SimpleMapEntry(java.lang.Object oKey, java.lang.Object oValue, java.lang.Object oOrigValue) Construct a SimpleMapEntry with a key, value and original value.

Method Summary

java.lang.Object	clone() Clone the Entry.
boolean	equals(java.lang.Object o) Compares the specified object with this entry for equality.
java.lang.Object	extract(ValueExtractor extractor) Extract a value out of the Entry's value.
java.lang.Object	getKey() Return the key corresponding to this entry.
java.lang.Object	getOriginalValue() Determine the value that existed before the start of the mutating operation that is being evaluated by the trigger.
java.lang.Object	getValue() Returns the value corresponding to this entry.
int	hashCode() Returns the hash code value for this map entry.
boolean	isOriginalPresent() Determine whether or not the Entry existed before the start of the mutating operation that is being evaluated by the trigger.
boolean	isPresent() Determine if this Entry exists in the Map.
void	remove(boolean fSynthetic) Remove this Entry from the Map if it is present in the Map.
java.lang.Object	setValue(java.lang.Object oValue) Replaces the value corresponding to this entry with the specified value (optional operation).
void	setValue(java.lang.Object oValue, boolean fSynthetic) Store the value corresponding to this entry.
java.lang.String	toString() Render the map entry as a String.
void	update(ValueUpdater updater, java.lang.Object oValue) Update the Entry's value.

Field Detail

NO_VALUE

protected static final java.lang.Object NO_VALUE

Constant used to indicate that the original value does not exist.

m_oKey

protected java.lang.Object m_oKey

The key. This object reference will not change for the life of the Entry.

m_oValue

protected java.lang.Object m_oValue

The value. This object reference can change within the life of the Entry.

m_oOrigValue

protected java.lang.Object m_oOrigValue

The original value. This object reference will not change within the life of the Entry.

Constructor Detail

SimpleMapEntry

protected SimpleMapEntry()

Default constructor.

SimpleMapEntry

protected SimpleMapEntry(java.lang.Object oKey)

Construct a SimpleMapEntry with just a key.

Parameters:

oKey - an object for the key

SimpleMapEntry

public SimpleMapEntry(java.util.Map.Entry entry)

Copy constructor.

Parameters:

entry - an entry to copy from

SimpleMapEntry

public SimpleMapEntry(java.lang.Object oKey,
                      java.lang.Object oValue)

Construct a SimpleMapEntry with a key and a value.

Parameters:

oKey - an object for the key

oValue - an object for the value

SimpleMapEntry

public SimpleMapEntry(java.lang.Object oKey,
                      java.lang.Object oValue,
                      java.lang.Object oOrigValue)

Construct a SimpleMapEntry with a key, value and original value.

Parameters:

oKey - an object for the key

oValue - an object for the value

oOrigValue - an object for the original value

Since:

Coherence 3.6

Method Detail

getKey

public java.lang.Object getKey()

Return the key corresponding to this entry. The resultant key does not necessarily exist within the containing Map, which is to say that InvocableMap.this.containsKey(getKey()) could return false. To test for the presence of this key within the Map, use InvocableMap.Entry.isPresent(), and to create the entry for the key, use InvocableMap.Entry.setValue(java.lang.Object).

Specified by:

getKey in interface InvocableMap.Entry

Specified by:

getKey in interface java.util.Map.Entry

Returns:

the key corresponding to this entry; may be null if the underlying Map supports null keys

getValue

public java.lang.Object getValue()

Returns the value corresponding to this entry. If the mapping has been removed from the backing map (by the iterator's remove operation), the results of this call are undefined.

Specified by:

getValue in interface InvocableMap.Entry

Specified by:

getValue in interface java.util.Map.Entry

Returns:

the value corresponding to this entry.

setValue

public java.lang.Object setValue(java.lang.Object oValue)

Replaces the value corresponding to this entry with the specified value (optional operation). (Writes through to the map.) The behavior of this call is undefined if the mapping has already been removed from the map (by the iterator's remove operation).

Specified by:

setValue in interface InvocableMap.Entry

Specified by:

setValue in interface java.util.Map.Entry

Parameters:

oValue - new value to be stored in this entry

Returns:

old value corresponding to the entry

getOriginalValue

public java.lang.Object getOriginalValue()

Determine the value that existed before the start of the mutating operation that is being evaluated by the trigger.

Specified by:

getOriginalValue in interface MapTrigger.Entry

Returns:

the original value corresponding to this Entry; may be null if the value is null or if the Entry did not exist in the Map

isOriginalPresent

public boolean isOriginalPresent()

Determine whether or not the Entry existed before the start of the mutating operation that is being evaluated by the trigger.

Specified by:

isOriginalPresent in interface MapTrigger.Entry

Returns:

true iff this Entry was existent in the containing Map

setValue

public void setValue(java.lang.Object oValue,
                     boolean fSynthetic)

Store the value corresponding to this entry. If the entry does not exist, then the entry will be created by invoking this method, even with a null value (assuming the Map supports null values).

Unlike the other form of setValue, this form does not return the previous value, and as a result may be significantly less expensive (in terms of cost of execution) for certain Map implementations.

Specified by:

setValue in interface InvocableMap.Entry

Parameters:

oValue - the new value for this Entry

fSynthetic - pass true only if the insertion into or modification of the Map should be treated as a synthetic event

update

public void update(ValueUpdater updater,
                   java.lang.Object oValue)

Update the Entry's value. Calling this method is semantically equivalent to:

   Object oTarget = entry.getValue();
   updater.update(oTarget, oValue);
   entry.setValue(oTarget, false);
 

The benefit of using this method is that it may allow the Entry implementation to significantly optimize the operation, such as for purposes of delta updates and backup maintenance.

Specified by:

update in interface InvocableMap.Entry

Parameters:

updater - a ValueUpdater used to modify the Entry's value

oValue - the new value for this Entry

isPresent

public boolean isPresent()

Determine if this Entry exists in the Map. If the Entry is not present, it can be created by calling InvocableMap.Entry.setValue(Object) or InvocableMap.Entry.setValue(Object, boolean). If the Entry is present, it can be destroyed by calling InvocableMap.Entry.remove(boolean).

Specified by:

isPresent in interface InvocableMap.Entry

Returns:

true iff this Entry is existent in the containing Map

remove

public void remove(boolean fSynthetic)

Description copied from interface: InvocableMap.Entry

Remove this Entry from the Map if it is present in the Map.

This method supports both the operation corresponding to Map.remove(java.lang.Object) as well as synthetic operations such as eviction. If the containing Map does not differentiate between the two, then this method will always be identical to InvocableMap.this.remove(getKey()).

Specified by:

remove in interface InvocableMap.Entry

Parameters:

fSynthetic - pass true only if the removal from the Map should be treated as a synthetic event

Throws:

java.lang.UnsupportedOperationException

extract

public java.lang.Object extract(ValueExtractor extractor)

Extract a value out of the Entry's value. Calling this method is semantically equivalent to extractor.extract(entry.getValue()), but this method may be significantly less expensive. For example, the resultant value may be obtained from a forward index, avoiding a potential object de-serialization.

Specified by:

extract in interface QueryMap.Entry

Parameters:

extractor - a ValueExtractor to apply to the Entry's value

Returns:

the extracted value

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this entry for equality. Returns true if the given object is also a map entry and the two entries represent the same mapping. More formally, two entries e1 and e2 represent the same mapping if

     (e1.getKey()==null ?
      e2.getKey()==null : e1.getKey().equals(e2.getKey()))  &&
     (e1.getValue()==null ?
      e2.getValue()==null : e1.getValue().equals(e2.getValue()))
 

This ensures that the equals method works properly across different implementations of the Map.Entry interface.

Specified by:

equals in interface java.util.Map.Entry

Parameters:

o - object to be compared for equality with this map entry

Returns:

true if the specified object is equal to this map entry

hashCode

public int hashCode()

Returns the hash code value for this map entry. The hash code of a map entry e is defined to be:

     (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
     (e.getValue()==null ? 0 : e.getValue().hashCode())
 

This ensures that e1.equals(e2) implies that e1.hashCode()==e2.hashCode() for any two Entries e1 and e2, as required by the general contract of Object.hashCode.

Specified by:

hashCode in interface java.util.Map.Entry

Returns:

the hash code value for this map entry.

toString

public java.lang.String toString()

Render the map entry as a String.

Returns:

the details about this entry

clone

public java.lang.Object clone()

Clone the Entry.

Returns:

a clone of this Entry

Skip navigation links