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_VALUE_EXTRACTOR_HPP 00008 #define COH_VALUE_EXTRACTOR_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 COH_OPEN_NAMESPACE2(coherence,util) 00013 00014 00015 /** 00016 * ValueExtractor is used to both extract values (for example, for sorting 00017 * or filtering) from an object, and to provide an identity for that 00018 * extraction. 00019 * 00020 * <b>Important Note:</b> all classes that implement the ValueExtractor 00021 * interface must explicitly implement the Object::hashCode() and 00022 * Object::equals methods in a way that is based solely on the object's 00023 * serializable state. 00024 * 00025 * @author jh 2008.02.26 00026 */ 00027 class COH_EXPORT ValueExtractor 00028 : public interface_spec<ValueExtractor> 00029 { 00030 // ----- ValueExtractor interface --------------------------------------- 00031 00032 public: 00033 /** 00034 * Extract the value from the passed object. The returned value may be 00035 * NULL. 00036 * 00037 * @param ohTarget an Object to retrieve the value from 00038 * 00039 * @return the extracted value; NULL is an acceptable value 00040 * 00041 * @throws ClassCastException if this ValueExtractor is incompatible with 00042 * the passed object to extract a value from and the 00043 * implementation <b>requires</b> the passed object to be of a 00044 * certain type 00045 * @throws Exception if this ValueExtractor encounters an exception in 00046 * the course of extracting the value 00047 * @throws IllegalArgumentException if this ValueExtractor cannot 00048 * handle the passed object for any other reason; an 00049 * implementor should include a descriptive message 00050 */ 00051 virtual Object::Holder extract(Object::Holder ohTarget) const = 0; 00052 00053 00054 // ----- Object interface ----------------------------------------------- 00055 00056 public: 00057 /** 00058 * Compare the ValueExtractor with another object to determine 00059 * equality. Two ValueExtractor objects, <i>ve1</i> and <i>ve2</i> are 00060 * considered equal iff <tt>ve1->extract(v)</tt> equals 00061 * <tt>ve2->extract(v)</tt> for all values of <tt>v</tt>. 00062 * 00063 * @param v the reference object with which to compare 00064 * 00065 * @return true iff this ValueExtractor and the passed object are 00066 * equivalent ValueExtractors 00067 */ 00068 using Object::equals; 00069 }; 00070 00071 COH_CLOSE_NAMESPACE2 00072 00073 #endif // COH_VALUE_EXTRACTOR_HPP