Oracle Coherence for C++ API
Release 3.7.1.0

E22845-01

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< Comparatorm_vComparator
 Comparator used to sort the index.
FinalHandle< Mapm_hMapForward
 Map that contains the index values (forward index).
FinalHandle< Mapm_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.