Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

AbstractExtractor Class Reference

#include <coherence/util/extractor/AbstractExtractor.hpp>

Inherits Object, ValueExtractor, QueryMapComparator, and PortableObject.

Inherited by AbstractCompositeExtractor, EntryExtractor, IdentityExtractor, KeyExtractor, PofExtractor, and ReflectionExtractor.

List of all members.


Detailed Description

Abstract base for ValueExtractor implementations.

It provides common functionality that allows any extending extractor to be used as a value Comparator.

Starting with Coherence 3.5, when used to extract information that is coming from a Map, subclasses have the additional ability to operate against the Map::Entry instead of just the value. In other words, like the EntryExtractor class, this allows an extractor implementation to extract a desired value using all available information on the corresponding Map::Entry object and is intended to be used in advanced custom scenarios, when application code needs to look at both key and value at the same time or can make some very specific assumptions regarding to the implementation details of the underlying Entry object. To maintain full backwards compatibility, the default behavior remains to extract from the Value property of the Map::Entry.

Note: subclasses are responsible for initialization and POF serialization of the m_nTarget field.

Author:
djl 2008.03.10

Public Types

typedef spec::Handle  Handle
  AbstractExtractor Handle definition.
typedef spec::View  View
  AbstractExtractor View definition.
typedef spec::Holder  Holder
  AbstractExtractor Holder definition.

Public Member Functions

virtual Object::Holder  extract (Object::Holder ohTarget) const
  Extract the value from the passed object.

The returned value may be NULL.

Parameters:
ohTarget  an Object to retrieve the value from
Returns:
the extracted value; NULL is an acceptable value
Exceptions:
ClassCastException  if this ValueExtractor is incompatible with the passed object to extract a value from and the implementation requires the passed object to be of a certain type
Exception  if this ValueExtractor encounters an exception in the course of extracting the value
IllegalArgumentException  if this ValueExtractor cannot handle the passed object for any other reason; an implementor should include a descriptive message

virtual int32_t  compareEntries (QueryMap::Entry::View vEntry1, QueryMap::Entry::View vEntry2) const
  Compare two entries based on the rules specified by Comparator.

If possible, use the coherence::util::QueryMap.Entry::extract() method to optimize the value extraction process.

This method is expected to be implemented by Comparator wrappers, such as ChainedComparator and InverseComparator, which simply pass on this invocation to the wrapped Comparator objects if they too implement this interface, or to invoke their default compare method passing the actual objects (not the extracted values) obtained from the extractor using the passed entries.

This interface is also expected to be implemented by ValueExtractor implementations that implement the Comparator interface. It is expected that in most cases, the Comparator wrappers will eventually terminate at (i.e. delegate to) ValueExtractors that also implement this interface.

Parameters:
vEntry1  the first entry to compare values from; read-only
vEntry2  the second entry to compare values from; read-only
Returns:
a negative integer, zero, or a positive integer as the first entry denotes a value that is is less than, equal to, or greater than the value denoted by the second entry
Exceptions:
ClassCastException  if the arguments' types prevent them from being compared by this Comparator.
IllegalArgumentException  if the extractor cannot handle the passed objects for any other reason; an implementor should include a descriptive message

virtual int32_t  compare (Object::View v1, Object::View v2) const
  Compare two Objects.

If both Objects are comparable with this Comparator, return < 0, 0 or > 0 if the first Object is less than, equal to, or greater than the second Object.

The general contract for this method is:

  1. If either of two handles are NULL, a coherence::lang::NullPointerException shall be thrown;
  2. If either of two Objects are not comparable with this Comparator, a coherence::lang::IllegalArgumentException shall be thrown;
  3. It shall be consistent with the Object::equals() relation, i.e. compare(v1, v2) == 0 if and only if Object::equals(v1, v2) == true
  4. The subsequent calls to this method shall return the same value until either of arguments changed
  5. It shall be anti-symmetric, i.e. compare(v1, v2) == -compare(v2, v1)

A typical implementation of Comparator may look as follows:

 int32_t MyTypeComparator::compare(Object::View v1,
                                   Object::View v2) const
     {
     // compares instances of class MyType only
     if (!v1 || !v2)
         {
         COH_THROW(NullPointerException());
         }
     MyType::View vTypedObj1 = cast<MyType::View>(v1);
     MyType::View vTypedObj2 = cast<MyType::View>(v2);
     if (!vTypedObj1 || !vTypedObj1)
         {
         COH_THROW(IllegalArgumentException("Instances of MyType expected"));
         }
     // here we suppose that the state of the MyType is defined by
     // single field of integer type
     if (vTypedObj1->m_intField == vTypedObj2->m_intField)
         {
         return 0;
         }
     else if (vTypedObj1->m_intField < vTypedObj2->m_intField)
         {
         return -1;
         }
     else
         {
         return 1;
         }
     }
 

virtual Object::Holder  extractFromEntry (Map::Entry::Holder ohEntry) const
  Extract the value from the passed Entry object.

Static Public Attributes

static const int32_t  VALUE
  Indicates that the extractFromEntry operation should use the Entry's value.
static const int32_t  KEY
  Indicates that the extractFromEntry operation should use the Entry's value.

Protected Attributes

int32_t  m_nTarget
  Specifies which part of the entry should be used by the extractFromEntry operation.

Member Function Documentation

virtual Object::Holder extractFromEntry ( Map::Entry::Holder  ohEntry  )  const [virtual]

Extract the value from the passed Entry object.

The returned value should follow the conventions outlined in the extract method. By overriding this method, an extractor implementation is able to extract a desired value using all available information on the corresponding Map::Entry object and is intended to be used in advanced custom scenarios, when application code needs to look at both key and value at the same time or can make some very specific assumptions regarding to the implementation details of the underlying Entry object.

Parameters:
entry  an Entry object to extract a desired value from
Returns:
the extracted value
Since:
Coherence 3.5

Reimplemented in ChainedExtractor, MultiExtractor, and PofExtractor.


Member Data Documentation

const int32_t VALUE [static]

Indicates that the extractFromEntry operation should use the Entry's value.

Since:
Coherence 3.5

const int32_t KEY [static]

Indicates that the extractFromEntry operation should use the Entry's value.

Since:
Coherence 3.5

int32_t m_nTarget [protected]

Specifies which part of the entry should be used by the extractFromEntry operation.

Legal values are VALUE (default) or KEY.

Note: subclasses are responsible for initialization and POF serialization of this field.

Since:
Coherence 3.5

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