Oracle Coherence for C++ API
Release 3.7.1.0
E22845-01

coherence::util::SimpleMapIndex

SimpleMapIndex Class Reference

#include <coherence/util/SimpleMapIndex.hpp>

Inherits Object, and MapIndex.

Inherited by ConditionalIndex.

List of all members.

Detailed Description

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.

.

Author:
tb 2009.02.09
Since:
Coherence 3.5
 

Public Types
typedef spec::Handle  Handle
  SimpleMapIndex Handle definition.
typedef spec::View  View
  SimpleMapIndex View definition.
typedef spec::Holder  Holder
  SimpleMapIndex Holder definition.

Public Member Functions
virtual
ValueExtractor::View 		 getValueExtractor () const
  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.

Returns:
a ValueExtractor object, never NULL
virtual bool  isOrdered () const
  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.

Returns:
true if the index contents are ordered, false otherwise
virtual bool  isPartial () const
  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.

Returns:
true if any entry of the indexed Map has been excluded from the index, false otherwise
Since:
Coherence 3.6
virtual Map::View  getIndexContents () const
  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.

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

Returns:
a Map (or a SortedMap) of the index contents
virtual Object::Holder  get (Object::View vKey) const
  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.

Parameters:
  vKey  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; getNoValue() if the index does not have the necessary information
virtual Object::Holder  get (Object::View vKey)
  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.

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
virtual Comparator::View  getComparator () const
  Get the Comparator used to sort the index.
Returns:
the comparator
Since:
Coherence 3.5
virtual void  insert (Map::Entry::View vEntry)
  Update the index in response to a insert operation on a cache.
Parameters:
  vEntry  the entry representing the object being inserted
Since:
Coherence 3.5
virtual void  update (Map::Entry::View vEntry)
  Update the index in response to an update operation on a cache.
Parameters:
  vEntry  the entry representing the object being updated
Since:
Coherence 3.5
virtual void  remove (Map::Entry::View vEntry)
  Update the index in response to a remove operation on a cache.
Parameters:
  vEntry  the entry representing the object being deleted
Since:
Coherence 3.5
virtual bool  equals (Object::View v) const
   
virtual size32_t  hashCode () const
  Return a hash code value for the Object.

This method is supported for the benefit of hash-based containers.

The general contract of hashCode is:

  • Whenever it is invoked on the same Object more than once during an execution of an application, the hashCode method must consistently return the same value, provided no information used in equals comparisons on the object is modified. This value need not remain consistent from one execution of an application to another execution of the same application.
  • If two Objects are equal according to the equals method, then calling the hashCode method on each of the two Objects must produce the same value.
  • It is not required that if two Objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct results. However, the programmer should be aware that producing distinct results for unequal objects may improve the performance of hash-based containers.

The default implementation is identity based.

Returns:
a hash code value for this Object
virtual void  toStream (std::ostream &out) const
  Output a human-readable description of this Object to the given stream.

coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.

 Object::View vKey   = ...
 Object::View vValue = ...
 std::cout << vKey << " = " << vValue << std::endl;

 String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);
Parameters:
  out  the stream used to output the description

Protected Member Functions
  SimpleMapIndex (ValueExtractor::View vExtractor, bool fOrdered, Comparator::View vComparator, bool fInit=true)
  Construct an index from the given map.
virtual void  init (bool fForwardIndex=true)
  Initialize the index's data structures.
virtual Map::Entry::View  getForwardEntry (Object::View vKey) const
  Get the forward index entry associated with the specified key.
virtual
Map::Entry::Handle 		 getForwardEntry (Object::View vKey)
  Get the forward index entry associated with the specified key.
Map::Handle  instantiateForwardIndex () const
  Instantiate and initialize the forward index.
virtual Map::Handle  instantiateInverseIndex (bool fOrdered, Comparator::View vComparator) const
  Instantiate and initialize the inverse index.
virtual Object::Holder  addInverseMapping (Object::Holder ohIxValue, Object::View vKey)
  Add a new mapping from the given indexed value to the given key in the inverse index.
virtual Object::Holder  addInverseMapping (Map::Handle hMapIndex, Object::Holder ohIxValue, Object::View vKey)
  Add a new mapping from the given indexed value to the given key in the supplied index.
virtual Object::Holder  addInverseCollectionMapping (Map::Handle hMapIndex, Object::Holder ohIxValue, Object::View vKey)
  Add new mappings from the elements of the given value to the given key in the supplied index.
virtual void  removeInverseMapping (Object::Holder ohIxValue, Object::View vKey)
  Remove the mapping from the given indexed value to the given key from the inverse index.
virtual void  removeInverseMapping (Map::Handle hMapIndex, Object::Holder ohIxValue, Object::View vKey)
  Remove the mapping from the given indexed value to the given key from the supplied index.
virtual void  insertInternal (Map::Entry::View vEntry)
  Update this index in response to a insert operation on a cache.
virtual void  updateInternal (Map::Entry::View vEntry)
  Update this index in response to an update operation on a cache.
virtual void  removeInternal (Map::Entry::View vEntry)
  Update this index in response to a remove operation on a cache.
virtual Set::Handle  instantiateSet () const
  Factory method used to create a new set containing the keys associated with a single value.

Protected Attributes
FinalView
< ValueExtractor > 		 m_vValueExtractor
  ValueExtractor object that this MapIndex uses to extract an indexable Object from a [converted] value stored in the Storage.
const bool  m_fOrdered
  Specifies whether or not this MapIndex orders the contents of the indexed information.
FinalView< Comparator >  m_vComparator
  Comparator used to sort the index.
FinalHandle< Map >  m_hMapForward
  Map that contains the index values (forward index).
FinalHandle< Map >  m_hMapInverse
  Map that contains the index contents (inverse index).
const bool  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.

Constructor & Destructor Documentation

SimpleMapIndex ( ValueExtractor::View  vExtractor,
    bool  fOrdered,
    Comparator::View  vComparator,
    bool  fInit = true  
  )     [protected]

Construct an index from the given map.

Parameters:
  vExtractor  the ValueExtractor object that is used to extract an indexable Object from a value stored in the indexed Map. Must not be NULL.
  fOrdered  true iff the contents of the indexed information should be ordered; false otherwise
  vComparator  the Comparator object which imposes an ordering on entries in the indexed map; or NULL if the entries' values natural ordering should be used
  fInit  initialize the index if true, default is true

Member Function Documentation

virtual void init ( bool  fForwardIndex = true  )  [protected, virtual]

Initialize the index's data structures.

Parameters:
  fForwardIndex  specifies whether or not a forward index map is supported, default is true

virtual Map::Entry::View getForwardEntry ( Object::View  vKey  )  const [protected, virtual]

Get the forward index entry associated with the specified key.

Parameters:
  vKey  the key
Returns:
the entry associated with the given key.

Reimplemented in ConditionalIndex.

virtual Map::Entry::Handle getForwardEntry ( Object::View  vKey  )  [protected, virtual]

Get the forward index entry associated with the specified key.

Parameters:
  vKey  the key
Returns:
the entry associated with the given key.

Reimplemented in ConditionalIndex.

Map::Handle instantiateForwardIndex (    )  const [protected]

Instantiate and initialize 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.

Reimplemented in ConditionalIndex.

virtual Map::Handle instantiateInverseIndex ( bool  fOrdered,
    Comparator::View  vComparator  
  )     const [protected, virtual]

Instantiate and initialize the inverse index.

Parameters:
  fOrdered  true iff the contents of the indexed information should be ordered; false otherwise
  vComparator  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.

virtual Object::Holder addInverseMapping ( Object::Holder  ohIxValue,
    Object::View  vKey  
  )     [protected, virtual]

Add a new mapping from the given indexed value to the given key in the inverse index.

Parameters:
  ohIxValue  the indexed value (serves as a key in the inverse index)
  vKey  the key to insert into the inverse index
Returns:
an already existing reference that is "equal" to the specified value (if available)

virtual Object::Holder addInverseMapping ( Map::Handle  hMapIndex,
    Object::Holder  ohIxValue,
    Object::View  vKey  
  )     [protected, virtual]

Add a new mapping from the given indexed value to the given key in the supplied index.

Parameters:
  hMapIndex  the index to which to add the mapping
  ohIxValue  the indexed value
  vKey  the key
Returns:
an already existing reference that is "equal" to the specified value (if available)

virtual Object::Holder addInverseCollectionMapping ( Map::Handle  hMapIndex,
    Object::Holder  ohIxValue,
    Object::View  vKey  
  )     [protected, virtual]

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:
  hMapIndex  the index to which to add the mapping
  ohIxValue  the indexed Collection value (each element serves as a key in the inverse index)
  vKey  the key to insert into the inverse index
Returns:
an already existing reference that is "equal" to the specified value (if available)

virtual void removeInverseMapping ( Object::Holder  ohIxValue,
    Object::View  vKey  
  )     [protected, virtual]

Remove the mapping from the given indexed value to the given key from the inverse index.

Parameters:
  ohIxValue  the indexed value
  vKey  the key

virtual void removeInverseMapping ( Map::Handle  hMapIndex,
    Object::Holder  ohIxValue,
    Object::View  vKey  
  )     [protected, virtual]

Remove the mapping from the given indexed value to the given key from the supplied index.

Parameters:
  hMapIndex  the index from which to remove the mapping
  ohIxValue  the indexed value
  vKey  the key

virtual void insertInternal ( Map::Entry::View  vEntry  )  [protected, virtual]

Update this index in response to a insert operation on a cache.

Parameters:
  vEntry  the entry representing the object being inserted

Reimplemented in ConditionalIndex.

virtual void updateInternal ( Map::Entry::View  vEntry  )  [protected, virtual]

Update this index in response to an update operation on a cache.

Parameters:
  vEntry  the entry representing the object being updated

Reimplemented in ConditionalIndex.

virtual void removeInternal ( Map::Entry::View  vEntry  )  [protected, virtual]

Update this index in response to a remove operation on a cache.

Parameters:
  vEntry  the entry representing the object being removed

Reimplemented in ConditionalIndex.

virtual Set::Handle instantiateSet (    )  const [protected, virtual]

Factory method used to create a new set containing the keys associated with a single value.

Returns:
a Set

Member Data Documentation

FinalView<Comparator> m_vComparator [protected]

Comparator used to sort the index.

Used iff the Ordered is true. Could be null, which implicates a natural order.

FinalHandle<Map> m_hMapForward [protected]

Map that contains the index values (forward index).

The keys of the Map are the keys to the ResourceMap and the values are the extracted values. This map is used by the IndexAwareComparators to avoid a conversion and value extraction steps.

FinalHandle<Map> m_hMapInverse [protected]

Map that contains the index contents (inverse index).

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

The documentation for this class was generated from the following file:

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