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_OBJECTS_HPP 00008 #define COH_OBJECTS_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/util/Comparator.hpp" 00013 00014 COH_OPEN_NAMESPACE2(coherence,util) 00015 00016 /** 00017 * This class consists of static NULL-safe or NULL-tolerant 00018 * utility methods for operating on Objects. 00019 * 00020 * @author phf 2015.07.10 00021 * 00022 * @since 12.2.1 00023 */ 00024 class COH_EXPORT Objects 00025 : public abstract_spec<Objects> 00026 { 00027 // ----- Objects interface ---------------------------------------------- 00028 00029 public: 00030 using Object::toString; 00031 00032 /** 00033 * Returns the result of calling toString on the first 00034 * argument if the first argument is not NULL and returns 00035 * the second argument otherwise. 00036 * 00037 * @param v an Object 00038 * @param vsNullDefault string to return if the first argument is 00039 * NULL 00040 * 00041 * @return the result of calling toString on the first 00042 * argument if it is not NULL and the second argument 00043 * otherwise. 00044 * 00045 * @see Object#toString(Object) 00046 */ 00047 static String::View toString(Object::View v, String::View vsNullDefault); 00048 00049 /** 00050 * Returns 0 if the arguments are identical and 00051 * vC->compare(vA, vB) otherwise. 00052 * Consequently, if both arguments are NULL, 0 00053 * is returned. 00054 * 00055 * Note that if one of the arguments is NULL, a 00056 * NullPointerException may or may not be thrown depending on 00057 * what ordering policy, if any, the Comparator 00058 * chooses to have for NULL values. 00059 * 00060 * @param vA an Object 00061 * @param vB an Object to be compared with vA 00062 * @param vC the Comparator to compare the first two arguments 00063 * 00064 * @return 0 if the arguments are identical and 00065 * c->compare(vA, vB) otherwise. 00066 * 00067 * @see Comparable 00068 * @see Comparator 00069 */ 00070 static int32_t compare(Object::View vA, Object::View vB, Comparator::View vC); 00071 00072 /** 00073 * Checks that the specified object reference is not NULL. This 00074 * method is designed primarily for doing parameter validation in methods 00075 * and constructors, as demonstrated below: 00076 * <blockquote><pre> 00077 * protected Foo(Bar::View vBar) { 00078 * this.vBar = Objects::requireNonNull(vBar); 00079 * } 00080 * </pre></blockquote> 00081 * 00082 * @param oh the Object reference to check for nullity 00083 * 00084 * @return oh if not NULL 00085 * 00086 * @throws NullPointerException if oh is NULL 00087 */ 00088 static Object::Holder requireNonNull(Object::Holder oh); 00089 00090 /** 00091 * Checks that the specified Object reference is not NULL and 00092 * throws a customized NullPointerException if it is. This method 00093 * is designed primarily for doing parameter validation in methods and 00094 * constructors with multiple parameters, as demonstrated below: 00095 * <blockquote><pre> 00096 * protected Foo(Bar::View vBar, Baz::View vBaz) { 00097 * this.vBar = Objects::requireNonNull(vBar, "vBar must not be null"); 00098 * this.vBaz = Objects::requireNonNull(vBaz, "vBaz must not be null"); 00099 * } 00100 * </pre></blockquote> 00101 * 00102 * @param oh the Object reference to check for nullity 00103 * @param vsMessage detail message to be used in the event that a 00104 * NullPointerException is thrown 00105 * 00106 * @return oh if not NULL 00107 * 00108 * @throws NullPointerException if oh is NULL 00109 */ 00110 static Object::Holder requireNonNull(Object::Holder oh, String::View vsMessage); 00111 00112 /** 00113 * Returns true if the provided reference is NULL otherwise 00114 * returns false. 00115 * 00116 * @param v an Object to be checked against NULL 00117 * 00118 * @return true if the provided reference is NULL otherwise false 00119 */ 00120 static bool isNull(Object::View v); 00121 00122 /** 00123 * Returns true if the provided reference is non-NULL 00124 * otherwise returns false. 00125 * 00126 * @param v an Object to be checked against NULL 00127 * 00128 * @return true if the provided reference is non-NULL otherwise false 00129 */ 00130 static bool nonNull(Object::View v); 00131 }; 00132 00133 COH_CLOSE_NAMESPACE2 00134 00135 #endif // COH_OBJECTS_HPP