00001 /* 00002 * Comparator.hpp 00003 * 00004 * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_COMPARATOR_HPP 00017 #define COH_COMPARATOR_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 COH_OPEN_NAMESPACE2(coherence,util) 00022 00023 00024 /** 00025 * The Comparator defines a partial order on the collection of Objects. 00026 * 00027 * Such ordering is required, for example, for tree-based collections like 00028 * HashMap or TreeSet. As there are no "natural" ordering defined for Objects, 00029 * the tree-based collections require some Comparator at creation time, and 00030 * further can contain only Objects that are comparable with that Comparator. 00031 * 00032 * The implementations of the Comparator shall take care to keep "less-than" 00033 * and "equals" relations impiled by them to satisfy the natural rules for 00034 * the corresponding mathematical relations. See the comments for method 00035 * {@link Comparator::compare compare(Object::View v1, Object::View v2)} 00036 * for more details. 00037 */ 00038 class COH_EXPORT Comparator 00039 : public interface_spec<Comparator> 00040 { 00041 // ----- Comparator interface ------------------------------------------- 00042 00043 public: 00044 /** 00045 * Compare two {@link coherence::lang::Object Objects}. If both 00046 * Objects are comparable with this 00047 * Comparator, return < 0, 0 or > 0 if the first Object is less than, 00048 * equal to, or greater than the second Object. 00049 * 00050 * The general contract for this method is: 00051 * <ol> 00052 * <li> If either of two handles are <tt>NULL</tt>, a 00053 * coherence::lang::NullPointerException shall be thrown; 00054 * </li> 00055 * <li> If either of two Objects are not comparable with this 00056 * Comparator, a coherence::lang::IllegalArgumentException 00057 * shall be thrown; 00058 * </li> 00059 * <li> It shall be consistent with the {@link 00060 * coherence::lang::Object::equals() Object::equals()} 00061 * relation, i.e. <code>compare(v1, v2) == 0</code> if and only 00062 * if <code>Object::equals(v1, v2) == true</code> 00063 * </li> 00064 * <li> The subsequent calls to this method shall return the same 00065 * value until either of arguments changed</li> 00066 * </li> 00067 * <li> It shall be <i>anti-symmetric</i>, i.e. 00068 * <code>compare(v1, v2) == -compare(v2, v1)</code> 00069 * </li> 00070 * </ol> 00071 * 00072 * A typical implementation of Comparator may look as follows: 00073 * <pre> 00074 * int32_t MyTypeComparator::compare(Object::View v1, 00075 * Object::View v2) const 00076 * { 00077 * // compares instances of class MyType only 00078 * if (!v1 || !v2) 00079 * { 00080 * COH_THROW(NullPointerException()); 00081 * } 00082 * MyType::View vTypedObj1 = cast<MyType::View>(v1); 00083 * MyType::View vTypedObj2 = cast<MyType::View>(v2); 00084 * if (!vTypedObj1 || !vTypedObj1) 00085 * { 00086 * COH_THROW(IllegalArgumentException("Instances of MyType expected")); 00087 * } 00088 * // here we suppose that the state of the MyType is defined by 00089 * // single field of integer type 00090 * if (vTypedObj1->m_intField == vTypedObj2->m_intField) 00091 * { 00092 * return 0; 00093 * } 00094 * else if (vTypedObj1->m_intField < vTypedObj2->m_intField) 00095 * { 00096 * return -1; 00097 * } 00098 * else 00099 * { 00100 * return 1; 00101 * } 00102 * } 00103 * </pre> 00104 */ 00105 virtual int32_t compare(Object::View v1, Object::View v2) const = 0; 00106 }; 00107 00108 COH_CLOSE_NAMESPACE2 00109 00110 #endif // COH_COMPARATOR_HPP