Skip navigation links

Oracle® Coherence Java API Reference
Release 3.7.0.0

E18683-01


com.tangosol.util
Class SimpleMapIndex

java.lang.Object
  extended by com.tangosol.util.Base
      extended by com.tangosol.util.SimpleMapIndex

All Implemented Interfaces:
MapIndex
Direct Known Subclasses:
ConditionalIndex

public class SimpleMapIndex
extends Base
implements MapIndex

SimpleMapIndex is a MapIndex implementation used to correlate property values extracted from resource map entries with corresponding keys using what is commonly known as an Inverted Index algorithm.

Since:
Coherence 3.5
Author:
tb 2009.03.19

Nested Class Summary
static class SimpleMapIndex.IndexCalculator
          A stateful calculator used to calculate the cost of a homogeneous index (holding all values of a single type).

 

Field Summary
protected  ConfigurableCacheMap.UnitCalculator m_calculator
          UnitCalculator used to estimate the cost of a value.
protected  java.util.Comparator m_comparator
          Comparator used to sort the index.
protected  BackingMapContext m_ctx
          The context associated with this index.
protected  java.util.concurrent.atomic.AtomicLong m_cUnits
          The size footprint of the index, in units (as defined by the UnitCalculator).
protected  ValueExtractor m_extractor
          ValueExtractor object that this MapIndex uses to extract an indexable property value from a [converted] value stored in the resource map.
protected  boolean m_fOrdered
          Specifies whether or not this MapIndex orders the contents of the indexed information.
protected  boolean m_fSplitCollection
          If a value extracted by the ValueExtractor is a Collection, this property specifies whether or not it should be treated as a Collection of contained attributes or indexed as a single composite attribute.
protected  java.util.Map m_mapForward
          Map that contains the index values (forward index).
protected  java.util.Map m_mapInverse
          Map that contains the index contents (inverse index).

 

Fields inherited from interface com.tangosol.util.MapIndex
NO_VALUE

 

Constructor Summary
  SimpleMapIndex(ValueExtractor extractor, boolean fOrdered, java.util.Comparator comparator, BackingMapContext ctx)
          Construct an index for the given map.
protected SimpleMapIndex(ValueExtractor extractor, boolean fOrdered, java.util.Comparator comparator, boolean fInit, BackingMapContext ctx)
          Construct an index for the given map.

 

Method Summary
protected  java.lang.Object addInverseCollectionMapping(java.util.Map mapIndex, java.lang.Object oIxValue, java.lang.Object oKey)
          Add new mappings from the elements of the given value to the given key in the supplied index.
protected  java.lang.Object addInverseMapping(java.util.Map mapIndex, java.lang.Object oIxValue, java.lang.Object oKey)
          Add a new mapping from the given indexed value to the given key in the supplied index.
protected  java.lang.Object addInverseMapping(java.lang.Object oIxValue, java.lang.Object oKey)
          Add a new mapping from the given indexed value to the given key in the inverse index.
protected  void addUnits(java.lang.Object oValue)
          Increase the size for the index by the estimated size of the specified added value.
 void delete(java.util.Map.Entry entry)
          Update this index in response to a remove operation on a cache.
protected  void deleteInternal(java.util.Map.Entry entry)
          Update this index in response to a remove operation on a cache.
 boolean equals(java.lang.Object o)
          Compares the specified object with this index for equality.
 java.lang.Object get(java.lang.Object oKey)
          Using the index information if possible, get the value associated with the specified key.
 ConfigurableCacheMap.UnitCalculator getCalculator()
          Return the UnitCalculator used to size this index's contents.
 java.util.Comparator getComparator()
          Get the Comparator used to sort the index.
protected  java.util.Map.Entry getForwardEntry(java.lang.Object oKey)
          Get the forward index entry associated with the specified key.
 java.util.Map getIndexContents()
          Get the Map that contains the index contents.
 long getUnits()
          Retrieve the size of this index in units (as defined by the {@link #getCalculator() UnitCalculator).
protected  java.util.concurrent.atomic.AtomicLong getUnitsCounter()
          Get the counter for the size of this index.
 ValueExtractor getValueExtractor()
          Obtain the ValueExtractor object that the MapIndex uses to extract an indexable Object from a value stored in the indexed Map.
 int hashCode()
          Returns the hash code value for this MapIndex.
protected  void initialize()
          Initialize the index's data structures.
 void insert(java.util.Map.Entry entry)
          Update this index in response to a insert operation on a cache.
protected  void insertInternal(java.util.Map.Entry entry)
          Update this index in response to a insert operation on a cache.
protected  ConfigurableCacheMap.UnitCalculator instantiateCalculator()
          Factory method used to create a new calculator.
protected  java.util.Map instantiateForwardIndex()
          Instantiate the forward index.
protected  java.util.Map instantiateInverseIndex(boolean fOrdered, java.util.Comparator comparator)
          Instantiate the inverse index.
protected  java.util.Set instantiateSet()
          Factory method used to create a new set containing the keys associated with a single value.
 boolean isOrdered()
          Determine if the MapIndex orders the contents of the indexed information.
 boolean isPartial()
          Determine if indexed information for any entry in the indexed Map has been excluded from this index.
protected  void removeInverseMapping(java.util.Map mapIndex, java.lang.Object oIxValue, java.lang.Object oKey)
          Remove the mapping from the given indexed value to the given key from the supplied index.
protected  void removeInverseMapping(java.lang.Object oIxValue, java.lang.Object oKey)
          Remove the mapping from the given indexed value to the given key from the inverse index.
protected  void removeUnits(java.lang.Object oValue)
          Decrease the size of the index by the estimated size of the specified removed value.
 java.lang.String toString()
          Returns a string representation of this SimpleMapIndex.
 java.lang.String toString(boolean fVerbose)
          Returns a string representation of this SimpleMapIndex.
 void update(java.util.Map.Entry entry)
          Update this index in response to an update operation on a cache.
protected  void updateInternal(java.util.Map.Entry entry)
          Update this index in response to an update operation on a cache.

 

Field Detail

m_extractor

protected ValueExtractor m_extractor
ValueExtractor object that this MapIndex uses to extract an indexable property value from a [converted] value stored in the resource map.

m_comparator

protected java.util.Comparator m_comparator
Comparator used to sort the index. Used iff the Ordered flag is true. Null implies a natural order.

m_fOrdered

protected boolean m_fOrdered
Specifies whether or not this MapIndex orders the contents of the indexed information.

m_mapForward

protected java.util.Map m_mapForward
Map that contains the index values (forward index). The keys of the Map are the keys to the map being indexed and the values are the extracted values. This map is used by the IndexAwareComparators to avoid a conversion and value extraction steps.

m_mapInverse

protected java.util.Map m_mapInverse
Map that contains the index contents (inverse index). The keys of the Map are the return values from the ValueExtractor operating against the entries of the resource map, and for each key, the corresponding value stored in the Map is a Set of keys to the resource map.

m_fSplitCollection

protected boolean m_fSplitCollection
If a value extracted by the ValueExtractor is a Collection, this property specifies whether or not it should be treated as a Collection of contained attributes or indexed as a single composite attribute.

m_cUnits

protected final java.util.concurrent.atomic.AtomicLong m_cUnits
The size footprint of the index, in units (as defined by the UnitCalculator).

m_calculator

protected ConfigurableCacheMap.UnitCalculator m_calculator
UnitCalculator used to estimate the cost of a value.

m_ctx

protected BackingMapContext m_ctx
The context associated with this index.

Constructor Detail

SimpleMapIndex

public SimpleMapIndex(ValueExtractor extractor,
                      boolean fOrdered,
                      java.util.Comparator comparator,
                      BackingMapContext ctx)
Construct an index for the given map.
Parameters:
extractor - the ValueExtractor that is used to extract an indexed value from a resource map entry
fOrdered - true iff the contents of the indexed information should be ordered; false otherwise
comparator - the Comparator object which imposes an ordering on entries in the index map; or null if the entries' values natural ordering should be used
ctx - the context associated with the indexed cache

SimpleMapIndex

protected SimpleMapIndex(ValueExtractor extractor,
                         boolean fOrdered,
                         java.util.Comparator comparator,
                         boolean fInit,
                         BackingMapContext ctx)
Construct an index for the given map.
Parameters:
extractor - the ValueExtractor that is used to extract an indexed value from a resource map entry
fOrdered - true iff the contents of the indexed information should be ordered; false otherwise
comparator - the Comparator object which imposes an ordering on entries in the index map; or null if the entries' values natural ordering should be used
fInit - initialize the index if true
ctx - the context associated with the indexed cache

Method Detail

getValueExtractor

public ValueExtractor getValueExtractor()
Obtain the ValueExtractor object that the MapIndex uses to extract an indexable Object from a value stored in the indexed Map. This property is never null.
Specified by:
getValueExtractor in interface MapIndex
Returns:
a ValueExtractor object, never null

isOrdered

public boolean isOrdered()
Determine if the MapIndex orders the contents of the indexed information. To determine in which way the contents are ordered, get the Comparator from the index contents SortedMap object.
Specified by:
isOrdered in interface MapIndex
Returns:
true if the index contents are ordered, false otherwise

isPartial

public boolean isPartial()
Determine if indexed information for any entry in the indexed Map has been excluded from this index. This information is used for IndexAwareFilter implementations to determine the most optimal way to apply the index.
Specified by:
isPartial in interface MapIndex
Returns:
true if any entry of the indexed Map has been excluded from the index, false otherwise

getComparator

public java.util.Comparator getComparator()
Get the Comparator used to sort the index.
Specified by:
getComparator in interface MapIndex
Returns:
the comparator

getIndexContents

public java.util.Map getIndexContents()
Get the Map that contains the index contents.

The keys of the Map are the return values from the ValueExtractor operating against the indexed Map's values, and for each key, the corresponding value stored in the Map is a Set of keys to the indexed Map.

If the MapIndex is known to be ordered, then the returned Map object will be an instance of SortedMap. The SortedMap may or may not have a Comparator object associated with it; see SortedMap.comparator().

A client should assume that the returned Map object is read-only and must not attempt to modify it.

Specified by:
getIndexContents in interface MapIndex
Returns:
a Map (or a SortedMap) of the index contents

get

public java.lang.Object get(java.lang.Object oKey)
Using the index information if possible, get the value associated with the specified key. This is expected to be more efficient than using the ValueExtractor against an object containing the value, because the index should already have the necessary information at hand.
Specified by:
get in interface MapIndex
Parameters:
oKey - the key that specifies the object to extract the value from
Returns:
the value that would be extracted by this MapIndex's ValueExtractor from the object specified by the passed key; NO_VALUE if the index does not have the necessary information

insert

public void insert(java.util.Map.Entry entry)
Update this index in response to a insert operation on a cache.
Specified by:
insert in interface MapIndex
Parameters:
entry - the entry representing the object being inserted

update

public void update(java.util.Map.Entry entry)
Update this index in response to an update operation on a cache.
Specified by:
update in interface MapIndex
Parameters:
entry - the entry representing the object being updated

delete

public void delete(java.util.Map.Entry entry)
Update this index in response to a remove operation on a cache.
Specified by:
delete in interface MapIndex
Parameters:
entry - the entry representing the object being removed

getUnits

public long getUnits()
Retrieve the size of this index in units (as defined by the {@link #getCalculator() UnitCalculator).
Returns:
the index size

getUnitsCounter

protected java.util.concurrent.atomic.AtomicLong getUnitsCounter()
Get the counter for the size of this index.
Returns:
the size counter

getCalculator

public ConfigurableCacheMap.UnitCalculator getCalculator()
Return the UnitCalculator used to size this index's contents.
Returns:
the unit calculator

initialize

protected void initialize()
Initialize the index's data structures.

getForwardEntry

protected java.util.Map.Entry getForwardEntry(java.lang.Object oKey)
Get the forward index entry associated with the specified key.
Parameters:
oKey - the key
Returns:
the entry associated with the given key.

instantiateForwardIndex

protected java.util.Map instantiateForwardIndex()
Instantiate the forward index.

Note: To optimize the memory footprint of the forward index, any subclasses of the SimpleMapIndex that override this method must also implement the getForwardEntry(Object) method accordingly.

Returns:
the forward index

instantiateInverseIndex

protected java.util.Map instantiateInverseIndex(boolean fOrdered,
                                                java.util.Comparator comparator)
Instantiate the inverse index.
Parameters:
fOrdered - true iff the contents of the indexed information should be ordered; false otherwise
comparator - the Comparator object which imposes an ordering on entries in the index map; or null if the entries' values natural ordering should be used
Returns:
the inverse index

insertInternal

protected void insertInternal(java.util.Map.Entry entry)
Update this index in response to a insert operation on a cache.
Parameters:
entry - the entry representing the object being inserted

updateInternal

protected void updateInternal(java.util.Map.Entry entry)
Update this index in response to an update operation on a cache.
Parameters:
entry - the entry representing the object being updated

deleteInternal

protected void deleteInternal(java.util.Map.Entry entry)
Update this index in response to a remove operation on a cache.
Parameters:
entry - the entry representing the object being removed

addInverseMapping

protected java.lang.Object addInverseMapping(java.lang.Object oIxValue,
                                             java.lang.Object oKey)
Add a new mapping from the given indexed value to the given key in the inverse index.
Parameters:
oIxValue - the indexed value (serves as a key in the inverse index)
oKey - the key to insert into the inverse index
Returns:
an already existing reference that is "equal" to the specified value (if available)

addInverseMapping

protected java.lang.Object addInverseMapping(java.util.Map mapIndex,
                                             java.lang.Object oIxValue,
                                             java.lang.Object oKey)
Add a new mapping from the given indexed value to the given key in the supplied index.
Parameters:
mapIndex - the index to which to add the mapping
oIxValue - the indexed value (serves as a key in the inverse index)
oKey - the key to insert into the inverse index
Returns:
an already existing reference that is "equal" to the specified value (if available)

addInverseCollectionMapping

protected java.lang.Object addInverseCollectionMapping(java.util.Map mapIndex,
                                                       java.lang.Object oIxValue,
                                                       java.lang.Object oKey)
Add new mappings from the elements of the given value to the given key in the supplied index. The given value is expected to be either a Collection or an Object array.
Parameters:
mapIndex - the index to which to add the mapping
oIxValue - the indexed Collection value (each element serves as a key in the inverse index)
oKey - the key to insert into the inverse index
Returns:
an already existing reference that is "equal" to the specified value (if available)

removeInverseMapping

protected void removeInverseMapping(java.lang.Object oIxValue,
                                    java.lang.Object oKey)
Remove the mapping from the given indexed value to the given key from the inverse index.
Parameters:
oIxValue - the indexed value
oKey - the key

removeInverseMapping

protected void removeInverseMapping(java.util.Map mapIndex,
                                    java.lang.Object oIxValue,
                                    java.lang.Object oKey)
Remove the mapping from the given indexed value to the given key from the supplied index.
Parameters:
mapIndex - the index from which to remove the mapping
oIxValue - the indexed value
oKey - the key

instantiateSet

protected java.util.Set instantiateSet()
Factory method used to create a new set containing the keys associated with a single value.
Returns:
a Set

instantiateCalculator

protected ConfigurableCacheMap.UnitCalculator instantiateCalculator()
Factory method used to create a new calculator.
Returns:
a ConfigurableCacheMap.UnitCalculator

removeUnits

protected void removeUnits(java.lang.Object oValue)
Decrease the size of the index by the estimated size of the specified removed value.
Parameters:
oValue - the value being removed from the index

addUnits

protected void addUnits(java.lang.Object oValue)
Increase the size for the index by the estimated size of the specified added value.
Parameters:
oValue - the value being added to the index.

toString

public java.lang.String toString()
Returns a string representation of this SimpleMapIndex.
Returns:
a String representation of this SimpleMapIndex

toString

public java.lang.String toString(boolean fVerbose)
Returns a string representation of this SimpleMapIndex. If called in verbose mode, include the contents of the index (the inverse index). Otherwise, just print the number of entries in the index.
Parameters:
fVerbose - if true then print the content of the index otherwise print the number of entries
Returns:
a String representation of this SimpleMapIndex

equals

public boolean equals(java.lang.Object o)
Compares the specified object with this index for equality. Returns true if the given object is also a SimpleMapIndex and the two represent the same index.
Parameters:
o - object to be compared for equality with this MapIndex
Returns:
true if the specified object is equal to this index

hashCode

public int hashCode()
Returns the hash code value for this MapIndex.
Returns:
the hash code value for this MapIndex

Skip navigation links

Oracle® Coherence Java API Reference
Release 3.7.0.0

E18683-01


Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.