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