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