C++ Client API Reference for Oracle Coherence
14c (14.1.2.0.0)

F79659-03

coherence/util/comparator/SafeComparator.hpp

00001 /*
00002  * Copyright (c) 2000, 2020, Oracle and/or its affiliates.
00003  *
00004  * Licensed under the Universal Permissive License v 1.0 as shown at
00005  * http://oss.oracle.com/licenses/upl.
00006  */
00007 #ifndef COH_SAFE_COMPARATOR_HPP
00008 #define COH_SAFE_COMPARATOR_HPP
00009 
00010 #include "coherence/lang.ns"
00011 
00012 #include "coherence/io/pof/PofReader.hpp"
00013 #include "coherence/io/pof/PofWriter.hpp"
00014 #include "coherence/io/pof/PortableObject.hpp"
00015 #include "coherence/util/Comparator.hpp"
00016 #include "coherence/util/QueryMap.hpp"
00017 #include "coherence/util/comparator/EntryAwareComparator.hpp"
00018 #include "coherence/util/comparator/QueryMapComparator.hpp"
00019 
00020 COH_OPEN_NAMESPACE3(coherence,util,comparator)
00021 
00022 using coherence::io::pof::PofReader;
00023 using coherence::io::pof::PofWriter;
00024 using coherence::io::pof::PortableObject;
00025 
00026 
00027 /**
00028 * NULL-safe delegating comparator. NULL values are evaluated as "less then"
00029 * any non-null value. If the wrapped comparator is not specified then all
00030 * non-null values must implement the coherence::util::Comparable interface.
00031 * Use SafeComparator::getInstance to obtain an instance of non-delegating
00032 * SafeComparator.
00033 *
00034 * @author djl  2008.05.05
00035 */
00036 class COH_EXPORT SafeComparator
00037     : public class_spec<SafeComparator,
00038         extends<Object>,
00039         implements<Comparator,
00040                    QueryMapComparator,
00041                    EntryAwareComparator,
00042                    PortableObject> >
00043     {
00044     friend class factory<SafeComparator>;
00045 
00046     // ----- constructors ---------------------------------------------------
00047 
00048     protected:
00049         /**
00050         * Default constructor (necessary for the PortableObject interface).
00051         */
00052         SafeComparator();
00053 
00054         /**
00055         * Construct a SafeComparator delegating to the specified (wrapped)
00056         * comparator.
00057         *
00058         * @param vComparator  Comparator object to delegate comparison of
00059         *                     non-null values (optional)
00060         */
00061         SafeComparator(Comparator::View vComparator);
00062 
00063     private:
00064         /**
00065         * Blocked copy constructor.
00066         */
00067         SafeComparator(const SafeComparator&);
00068 
00069 
00070     // ----- Comparator interface -------------------------------------------
00071 
00072     public:
00073         /**
00074         * Compares its two arguments for order.  Returns a negative integer,
00075         * zero, or a positive integer as the first argument is less than, equal
00076         * to, or greater than the second. Null values are evaluated as "less
00077         * then" any non-null value. If the wrapped comparator is not specified,
00078         * all non-null values must implement the Comparable interface.
00079         *
00080         * @param vO1  the first object to be compared
00081         * @param vO2  the second object to be compared
00082         *
00083         * @return a negative integer, zero, or a positive integer as the first
00084         *         argument is less than, equal to, or greater than the second
00085         *
00086         * @throws ClassCastException if the arguments' types prevent them from
00087         *         being compared by this Comparator.
00088         */
00089         virtual int32_t compare(Object::View vO1, Object::View vO2) const;
00090 
00091 
00092     // ----- QueryMap interface ---------------------------------------------
00093 
00094     public:
00095         /**
00096         * Compare two entries using the underlying comparator. If the wrapped
00097         * comparator does not implement the QueryMapComparator interface, revert
00098         * to the entry values comparison.
00099         */
00100         virtual int32_t compareEntries(QueryMap::Entry::View vEntry1,
00101                     QueryMap::Entry::View vEntry2) const;
00102 
00103 
00104     // ----- EntryAwareComparator interface ---------------------------------
00105 
00106     public:
00107         /**
00108         * {@inheritDoc}
00109         */
00110         virtual bool isKeyComparator() const;
00111 
00112         /**
00113         * Check whether the specified comparator expects to compare keys
00114         * or values.
00115         *
00116         * @param vComparator  a Comparator to check
00117         *
00118         * @return true if the comparator expects keys; false otherwise
00119         */
00120         static bool isKeyComparator(Comparator::View vComparator);
00121 
00122 
00123     // ----- PortableObject interface ---------------------------------------
00124 
00125     public:
00126         /**
00127         * {@inheritDoc}
00128         */
00129         virtual void readExternal(PofReader::Handle hIn);
00130 
00131         /**
00132         * {@inheritDoc}
00133         */
00134         virtual void writeExternal(PofWriter::Handle hOut) const;
00135 
00136 
00137     // ----- Object interface -----------------------------------------------
00138 
00139     public:
00140         /**
00141         * {@inheritDoc}
00142         */
00143         virtual bool equals(Object::View v) const;
00144 
00145         /**
00146         * {@inheritDoc}
00147         */
00148         virtual size32_t hashCode() const;
00149 
00150         /**
00151         * {@inheritDoc}
00152         */
00153         virtual TypedHandle<const String> toString() const;
00154 
00155 
00156     // ----- data member accessors ------------------------------------------
00157 
00158     public:
00159         /**
00160         * Obtain the wrapped Comparator.
00161         *
00162         * @return the wrapped Comparator
00163         */
00164         virtual Comparator::View getComparator() const;
00165 
00166 
00167     // ----- Helpers --------------------------------------------------------
00168 
00169     public:
00170         /**
00171         * Compares its two arguments for order.  Returns a negative integer,
00172         * zero, or a positive integer as the first argument is less than, equal
00173         * to, or greater than the second. Null values are evaluated as
00174         * "less then" any non-null value. Non-null values must implement the
00175         * coherence::util::Comparable interface.
00176         *
00177         * @param vComparator  a comparator to use for the comparison (optional)
00178         * @param vO1          the first object to be compared
00179         * @param vO2          the second object to be compared
00180         *
00181         * @return a negative integer, zero, or a positive integer as the first
00182         *         argument is less than, equal to, or greater than the second
00183         *
00184         * @throws ClassCastException if the arguments are not Comparable
00185         */
00186         static int32_t compareSafe(Comparator::View vComparator,
00187                 Object::View vO1, Object::View vO2);
00188 
00189 
00190     // ----- constants ------------------------------------------------------
00191 
00192     public:
00193         /**
00194         * An instance of the SafeComparator.
00195         */
00196         static SafeComparator::Handle getInstance();
00197 
00198 
00199     // ----- data members ---------------------------------------------------
00200 
00201     protected:
00202         /**
00203         * The wrapped Comparator. Could be null.
00204         */
00205         FinalView<Comparator> f_vComparator;
00206     };
00207 
00208 COH_CLOSE_NAMESPACE3
00209 
00210 #endif // COH_SAFE_COMPARATOR_HPP
Copyright © 2000, 2025, Oracle and/or its affiliates. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.