Oracle® Fusion Middleware C++ API Reference for Oracle Coherence
12c (12.2.1.3.0)
E80355-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 TypedHandle
< const String > 		toString () const
 Output a human-readable description of this Object to the given stream.

Note that when overriding this method the return type must be TypedHandle<const String> rather then String::View. These two types are assignment compatible but not equivalent and declaring the override with String::View will not be a compatible override.

coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toString 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 and is generally how toString() will be implemented.

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

 String::View vs = COH_TO_STRING(vKey << " = " << vValue);

The COH_TO_STRING macro is also the most common way to implement the toString method. For example:

 virtual TypedHandle<const String> Person::toString() const
     {
     return COH_TO_STRING("Name: " << f_sName << " SSN: " << f_nSSN);
     }

Returns:
a string representation of this object


Protected Member Functions

 SimpleMapIndex (ValueExtractor::View vExtractor, bool fOrdered, Comparator::View vComparator, bool fInit=true)
 Construct an index from the given map.
void updateExcludedKeys (Map::Entry::View vEntry, bool fExclude)
 Check the entry against the set of entries not included in the index and update the set if necessary.
bool isKeyExcluded (Object::View vKey) const
 Check if the entry with the given key is excluded from the index.
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.
void removeForwardEntry (Object::View vKey)
 Remove the forward index entry for the specified key.
Object::Holder extractNewValue (Map::Entry::View vEntry)
 Extract the "new" value from the specified entry.
Object::Holder extractOldValue (MapTrigger::Entry::View vEntry)
 Extract the "old" value from the specified entry.
Collection::View ensureCollection (Object::View vValue)
 Return a Collection representation of the specified value, which could be a Collection, ObjectArray, scalar, or no_value.
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, Collection::View vColIgnore)
 Remove the mapping from the given indexed value to the given key from the inverse 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 void logMissingIdx (Object::View vIxValue, Object::View vKey)
 Log messages for missing inverse index.
virtual Set::Handle collectRemoved (Object::View vIxValueOld, Object::View vIxValueNew)
 Given that the old value is known to be a Collection or an array, collect all the enclosed elements that are not part of the new value.
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 > 		f_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 > f_vComparator
 Comparator used to sort the index.
FinalHandle< Map > f_hMapForward
 Map that contains the index values (forward index).
FinalHandle< Map > f_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.
int64_t m_ldtLogMissingIdx
 The time at which the most recent logging of "missing inverse index" messages started.
int m_cLogMissingIdx
 The number of "missing inverse index" messages that have been logged.
FinalHandle< Set > f_hSetKeyExcluded
 A set of keys for the entries, which could not be included in the index.
const bool m_fImmutableValues
 Specifies whether or not index updates are permitted(immutable values).

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

void updateExcludedKeys ( Map::Entry::View  vEntry,
bool  fExclude 
) [protected]

Check the entry against the set of entries not included in the index and update the set if necessary.

Parameters:
vEntry the entry to be checked
fExclude true if the insert or update of the entry into the index caused an exception

bool isKeyExcluded ( Object::View  vKey  )  const [protected]

Check if the entry with the given key is excluded from the index.

Parameters:
vKey the key to test
Returns:
true if the key is in the list of keys currently excluded from the index, false if the entry with the key is in the index

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.

void removeForwardEntry ( Object::View  vKey  )  [protected]

Remove the forward index entry for the specified key.

Parameters:
vKey the key to remove the forward index entry for

Reimplemented in ConditionalIndex.

Object::Holder extractNewValue ( Map::Entry::View  vEntry  )  [protected]

Extract the "new" value from the specified entry.

Parameters:
vEntry the entry to extract the "new" value from
Returns:
the extracted "new" value, or no_value if the extraction failed

Object::Holder extractOldValue ( MapTrigger::Entry::View  vEntry  )  [protected]

Extract the "old" value from the specified entry.

Parameters:
vEntry the entry to extract the "old" value from
Returns:
the extracted "old" value, or no_value if the extraction failed

Collection::View ensureCollection ( Object::View  vValue  )  [protected]

Return a Collection representation of the specified value, which could be a Collection, ObjectArray, scalar, or no_value.

Parameters:
vValue the value
Returns:
a Collection representation of the specified value, or an empty Collection if no_value

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,
Collection::View  vColIgnore 
) [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
vColIgnore the Collection of values to ignore (exclude from removal), or NULL

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 void logMissingIdx ( Object::View  vIxValue,
Object::View  vKey 
) [protected, virtual]

Log messages for missing inverse index.

Parameters:
vIxValue the indexed value
vKey the key

virtual Set::Handle collectRemoved ( Object::View  vIxValueOld,
Object::View  vIxValueNew 
) [protected, virtual]

Given that the old value is known to be a Collection or an array, collect all the enclosed elements that are not part of the new value.

Parameters:
vIxValueOld the old value (must be a collection or an array)
vIxValueNew the new value
Returns:
the set of values that are contained in the old collection or array, but not part of the new value

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> f_vComparator [protected]

Comparator used to sort the index.

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

FinalHandle<Map> f_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> f_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.

const bool m_fImmutableValues [protected]

Specifies whether or not index updates are permitted(immutable values).

Since:
Coherence 12.2.1

The documentation for this class was generated from the following file:
Copyright © 2000, 2017, Oracle and/or its affiliates. All rights reserved.