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