00001 /* 00002 * UUID.hpp 00003 * 00004 * Copyright (c) 2000, 2020, 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_UUID_HPP 00017 #define COH_UUID_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/io/pof/PortableObject.hpp" 00022 #include "coherence/io/pof/PofReader.hpp" 00023 #include "coherence/io/pof/PofWriter.hpp" 00024 #include "coherence/util/Random.hpp" 00025 #include "coherence/net/InetAddress.hpp" 00026 00027 COH_OPEN_NAMESPACE2(coherence,util) 00028 00029 using coherence::net::InetAddress; 00030 using coherence::io::pof::PortableObject; 00031 using coherence::io::pof::PofReader; 00032 using coherence::io::pof::PofWriter; 00033 00034 00035 /** 00036 * A UUID is a 256-bit identifier that, if it is generated, is statistically 00037 * guaranteed to be unique. 00038 * 00039 * @author jh 2007.12.20 00040 * @author js 2008.03.24 00041 */ 00042 class COH_EXPORT UUID 00043 : public class_spec<UUID, 00044 extends<Object>, 00045 implements<Comparable, PortableObject> > 00046 { 00047 friend class factory<UUID>; 00048 00049 // ----- constructors --------------------------------------------------- 00050 00051 protected: 00052 /** 00053 * Generate a UUID. 00054 */ 00055 UUID(); 00056 00057 /** 00058 * Build a UUID from its constituent members (advanced constructor). 00059 * <p/> 00060 * It is guaranteed that a generated UUID will never equal a built 00061 * UUID. 00062 * 00063 * @param lDateTime the creation date/time millis portion of the UUID 00064 * @param vAddr the InetAddress portion of the UUID 00065 * @param nPort the port number portion of the UUID; a port 00066 * number is 16 bits, but up to 28 bits of data from 00067 * this value will be maintained by the UUID 00068 * @param nCount the counter portion of the UUID 00069 */ 00070 UUID(int64_t lDateTime, InetAddress::View vAddr, 00071 int32_t nPort, int32_t nCount); 00072 00073 /** 00074 * Build a UUID from its constituent members (advanced constructor). 00075 * <p/> 00076 * It is guaranteed that a generated UUID will never equal a built 00077 * UUID. 00078 * 00079 * @param lDateTime the creation date/time millis portion of the UUID 00080 * @param vabIP the InetAddress portion of the UUID 00081 * @param nPort the port number portion of the UUID; a port 00082 * number is 16 bits, but up to 28 bits of data from 00083 * this value will be maintained by the UUID 00084 * @param nCount the counter portion of the UUID 00085 */ 00086 UUID(int64_t lDateTime, Array<octet_t>::View vabIP, int32_t nPort, 00087 int32_t nCount); 00088 00089 /** 00090 * Construct a UUID from a String. 00091 * 00092 * @param vs a string as would be returned from UUID.toString() 00093 */ 00094 UUID(String::View vs); 00095 00096 /** 00097 * Construct a UUID from a byte array. 00098 * 00099 * @param vab a byte array as would be returned from 00100 * UUID.toByteArray() 00101 */ 00102 UUID(Array<octet_t>::View vab); 00103 00104 00105 // ----- UUID interface ------------------------------------------------- 00106 00107 public: 00108 /** 00109 * True if the UUID was generated, and false if it was built. A 00110 * generated UUID is universally unique. Note that the port number is 00111 * random if the UUID is generated. 00112 * 00113 * @return true if the UUID was generated 00114 */ 00115 virtual bool isGenerated() const; 00116 00117 /** 00118 * Determine the date/time value for the UUID. 00119 * 00120 * @return date/time value in millis 00121 */ 00122 virtual int64_t getTimestamp() const; 00123 00124 /** 00125 * True if the IP address is a real IP address. This is only false 00126 * if two conditions are met: The UUID is generated, and it could not 00127 * get an IP address (or one that is not a loopback/localhost address). 00128 * 00129 * @return true if the UUID has IP address information 00130 */ 00131 virtual bool isAddressIncluded() const; 00132 00133 /** 00134 * Determine the internet address of the host that generated the UUID 00135 * instance. 00136 * 00137 * @return an array of bytes containing the IP address information; 00138 * the array can be zero bytes (no address,) four bytes (IPv4) 00139 * or 16 bytes (IPv6) 00140 */ 00141 virtual Array<octet_t>::View getAddress() const; 00142 00143 /** 00144 * Determine the port portion of the UUID. Note that the port is a 00145 * 28-bit value; the first nibble is always 0x0. 00146 * 00147 * @return the port portion of the UID 00148 */ 00149 virtual int32_t getPort() const; 00150 00151 /** 00152 * Determine the "counter" portion of the UUID that ensures that two 00153 * UUIDs generated at the same exact time by the same process are 00154 * unique. 00155 * 00156 * @return a number that helps to make the UUID unique 00157 */ 00158 virtual int32_t getCount() const; 00159 00160 /** 00161 * Convert the UUID to a byte array of 32 bytes. 00162 * 00163 * @return the UUID data as a byte array of 32 bytes 00164 */ 00165 virtual Array<octet_t>::View toByteArray() const; 00166 00167 00168 // ----- Comparable interface ------------------------------------------- 00169 00170 public: 00171 /** 00172 * {@inheritDoc} 00173 */ 00174 virtual int32_t compareTo(Object::View v) const; 00175 00176 00177 // ----- PortableObject interface --------------------------------------- 00178 00179 public: 00180 /** 00181 * {@inheritDoc} 00182 */ 00183 virtual void readExternal(PofReader::Handle hIn); 00184 00185 /** 00186 * {@inheritDoc} 00187 */ 00188 virtual void writeExternal(PofWriter::Handle hOut) const; 00189 00190 00191 // ----- Object interface ----------------------------------------------- 00192 00193 public: 00194 /** 00195 * {@inheritDoc} 00196 */ 00197 virtual TypedHandle<const String> toString() const; 00198 00199 /** 00200 * {@inheritDoc} 00201 */ 00202 virtual bool equals(Object::View v) const; 00203 00204 /** 00205 * {@inheritDoc} 00206 */ 00207 virtual size32_t hashCode() const; 00208 00209 00210 // ----- helper methods ------------------------------------------------- 00211 00212 private: 00213 /** 00214 * If this UUID is being used as a generated UUID but its fields have 00215 * not yet been initialized, this method ensures that the 00216 * initialization occurs. All public methods, except for 00217 * deserialization methods, must call this method to ensure that the 00218 * UUID is properly constructed. 00219 */ 00220 void ensureConstructed() const; 00221 00222 /** 00223 * Finish construction or deserialization. The UUID's internally 00224 * cached hashcode value is zero until construction is completed, or 00225 * until deserialization is completed, and never zero otherwise. Every 00226 * constructor, except for the deserialization constructor, must call 00227 * this method. 00228 */ 00229 void initHashcode() const; 00230 00231 /** 00232 * Finish construction by setting Addr1..4 from an IP address. 00233 */ 00234 void initFromAddress(Array<octet_t>::View vabIP, int32_t nPort); 00235 00236 /** 00237 * Finish construction from a byte array. 00238 */ 00239 void initFromBytes(Array<octet_t>::View vab); 00240 00241 // ----- data members --------------------------------------------------- 00242 00243 protected: 00244 /** 00245 * System date/time value that the UUID instance was generated. 00246 */ 00247 mutable int64_t m_lDateTime; 00248 00249 /** 00250 * Internet address of host that generated the UUID instance. For IPv4, 00251 * this contains the entire IP address. For IPv6, this contains only 00252 * the first four bytes of the address. If the UUID is auto-generated 00253 * and it could not obtain a real address, then this is a random 00254 * number. 00255 */ 00256 mutable int32_t m_nAddr1; 00257 00258 /** 00259 * The second four bytes of the IP address. For IPv6, this is the 00260 * second four bytes of the IP address. If the UUID is auto-generated 00261 * and it could not obtain a real address, then this is a random 00262 * number. Otherwise if the UUID is built (not generated) and the 00263 * address is IPv4, then this is zero. 00264 */ 00265 mutable int32_t m_nAddr2; 00266 00267 /** 00268 * The third four bytes of the IP address. For IPv6, this is the third 00269 * four bytes of the IP address. If the UUID is auto-generated and it 00270 * could not obtain a real address, then this is a random number. 00271 * Otherwise if the UUID is built (not generated) and the address is 00272 * IPv4, then this is zero. 00273 */ 00274 mutable int32_t m_nAddr3; 00275 00276 /** 00277 * The fourth four bytes of the IP address. For IPv6, this is the 00278 * fourth four bytes of the IP address. If the UUID is auto-generated 00279 * and it could not obtain a real address, then this is a random 00280 * number. Otherwise if the UUID is built (not generated) and the 00281 * address is IPv4, then this is zero. 00282 */ 00283 mutable int32_t m_nAddr4; 00284 00285 /** 00286 * The least significant two bytes of this value are the port number 00287 * if the UUID is built (not generated). Otherwise this is a random 00288 * number, with the exception of the most significant nibble. The most 00289 * significant nibble contains the flags of the UUID. 00290 */ 00291 mutable int32_t m_nPort; 00292 00293 /** 00294 * A rolling counter. 00295 */ 00296 mutable int32_t m_nCount; 00297 00298 /** 00299 * Cache the hash. Only zero pending deserialization or generation. 00300 */ 00301 mutable Volatile<size32_t> m_nHash; 00302 00303 00304 // ----- constants ------------------------------------------------------ 00305 00306 protected: 00307 /** 00308 * A bit mask that represents the portion of the "port" value reserved 00309 * for bit flags. 00310 */ 00311 static const int32_t mask_allflags = 0xF0000000; 00312 00313 /** 00314 * The bit mask for the "is generated UUID" flag. 00315 */ 00316 static const int32_t mask_generated = 1 << 31; 00317 00318 /** 00319 * The bit mask for the "is a real IP address" flag. 00320 */ 00321 static const int32_t mask_realaddr = 1 << 30; 00322 00323 /** 00324 * The bit mask for the "is an IPv6 address" flag. 00325 */ 00326 static const int32_t mask_ipv6addr = 1 << 29; 00327 00328 /** 00329 * The one remaining bit for future use. 00330 */ 00331 static const int32_t mask_unused = 1 << 28; 00332 }; 00333 00334 COH_CLOSE_NAMESPACE2 00335 00336 #endif // COH_UUID_HPP