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