coherence/util/extractor/AbstractExtractor.hpp

/*
* AbstractExtractor.hpp
*
* Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_ABSTRACT_EXTRACTOR_HPP
#define COH_ABSTRACT_EXTRACTOR_HPP

#include "coherence/lang.ns"

#include "coherence/io/pof/PortableObject.hpp"
#include "coherence/util/QueryMap.hpp"
#include "coherence/util/ValueExtractor.hpp"
#include "coherence/util/comparator/QueryMapComparator.hpp"

COH_OPEN_NAMESPACE3(coherence,util,extractor)

using coherence::io::pof::PortableObject;
using coherence::util::comparator::QueryMapComparator;


/**
* 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.
*
* <b>Note:</b> subclasses are responsible for initialization and POF
* serialization of the {@link #m_nTarget} field.
*
* @author djl  2008.03.10
*/
class COH_EXPORT AbstractExtractor
    : public abstract_spec<AbstractExtractor,
        extends<Object>,
        implements<ValueExtractor, QueryMapComparator, PortableObject> >
    {
    // ----- constructors ---------------------------------------------------

    protected:
        /**
        * @internal
        */
        AbstractExtractor();


    // ----- ValueExtractor interface ---------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual Object::Holder extract(Object::Holder ohTarget) const;


    // ----- QueryMapComparator interface -----------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual int32_t compareEntries(QueryMap::Entry::View vEntry1,
                QueryMap::Entry::View vEntry2) const;


    // ----- Comparator interface -------------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual int32_t compare(Object::View v1, Object::View v2) const;


    // ----- subclassing support --------------------------------------------

    public:
        /**
        * Extract the value from the passed Entry object. The returned value
        * should follow the conventions outlined in the {@link #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.
        *
        * @param entry  an Entry object to extract a desired value from
        *
        * @return the extracted value
        *
        * @since Coherence 3.5
        */
        virtual Object::Holder extractFromEntry(Map::Entry::Holder ohEntry) const;


    // ----- constants ------------------------------------------------------

    public:
        /**
        * Indicates that the {@link #extractFromEntry} operation should use
        * the Entry's value.
        *
        * @since Coherence 3.5
        */
        static const int32_t VALUE = 0;

        /**
        * Indicates that the {@link #extractFromEntry} operation should use
        * the Entry's value.
        *
        * @since Coherence 3.5
        */
        static const int32_t KEY = 1;


    // ----- data members ---------------------------------------------------

    protected:
        /**
        * Specifies which part of the entry should be used by the
        * {@link #extractFromEntry} operation. Legal values are {@link #VALUE}
        * (default) or {@link #KEY}.
        *
        * <b>Note:</b> subclasses are responsible for initialization and POF
        * serialization of this field.
        *
        * @since Coherence 3.5
        */
        int32_t m_nTarget;
    };

COH_CLOSE_NAMESPACE3

#endif // COH_ABSTRACT_EXTRACTOR_HPP

Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.