Class CmsUUID

  • All Implemented Interfaces:
    java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<CmsUUID>

    public final class CmsUUID
    extends java.lang.Object
    implements java.lang.Cloneable, java.lang.Comparable<CmsUUID>, java.io.Externalizable
    Generates a UUID using spatial and temporal uniqueness.

    Spatial uniqueness is derived from ethernet address (MAC, 802.1); temporal from system clock.

    For more information about the algorithm used, please see draft-leach-uuids-guids-01.txt.

    Because Java is unable to read the MAC address of the machine (without using JNI), the MAC address has to be provided first by using the static init(String) method.

    This class is just a facade wrapper for the "real" UUID implementation.

    Since:
    6.0.0
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String UUID_REGEX
      A regular expression for matching UUIDs.
    • Constructor Summary

      Constructors 
      Constructor Description
      CmsUUID()
      Creates a new UUID.
      CmsUUID​(byte[] data)
      Create a UUID based on a binary data array.
      CmsUUID​(java.lang.String uuid)
      Create a UUID based on a String.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void checkId​(CmsUUID id, boolean canBeNull)
      Check that the given id is not the null id.
      java.lang.Object clone()
      Creates a clone of this CmsUUID.
      int compareTo​(CmsUUID obj)  
      boolean equals​(java.lang.Object obj)  
      static CmsUUID getConstantUUID​(java.lang.String name)
      Returns a constant (name based) UUID, based on the given name in the OpenCms name space.
      static java.lang.String getDummyEthernetAddress()
      Returns a String representing a dummy (random based) ethernet address.
      static CmsUUID getNullUUID()
      Returns a null UUID, use this null UUID to check if a UUID has been initialized or not.
      static CmsUUID getOpenCmsUUID()
      Returns a constant (name based) UUID for OpenCms, based on "www.opencms.org" in the dns name space.
      java.lang.String getStringValue()
      Returns the String representation of this UUID, same as toString().
      int hashCode()
      Optimized hashCode implementation for UUID's.
      static void init​(java.lang.String ethernetAddress)
      Initialize the UUID generator with the ethernet address of the server machine.
      boolean isNullUUID()
      Returns true if this UUID is equal to the null UUID.
      static boolean isValidUUID​(java.lang.String uuid)
      Returns true if the given UUID is valid.
      void readExternal​(java.io.ObjectInput in)  
      byte[] toByteArray()
      Returns the UUID as a 16-byte byte array.
      java.lang.String toString()  
      static CmsUUID valueOf​(java.lang.String uuid)
      Returns the given String transformed to a UUID in case the String is a valid UUID.
      void writeExternal​(java.io.ObjectOutput out)  
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • CmsUUID

        public CmsUUID()
        Creates a new UUID.

        Please note that the static init() method has to be called first to initialize the internet address of the machine.

      • CmsUUID

        public CmsUUID​(byte[] data)
        Create a UUID based on a binary data array.

        Parameters:
        data - a binary data array representing a UUID
      • CmsUUID

        public CmsUUID​(java.lang.String uuid)
                throws java.lang.NumberFormatException
        Create a UUID based on a String.

        Parameters:
        uuid - a String representing a UUID
        Throws:
        java.lang.NumberFormatException - in case uuid is not a valid UUID
    • Method Detail

      • checkId

        public static void checkId​(CmsUUID id,
                                   boolean canBeNull)
        Check that the given id is not the null id.

        Parameters:
        id - the id to check
        canBeNull - only if flag is set, null is accepted
        See Also:
        isNullUUID()
      • getConstantUUID

        public static CmsUUID getConstantUUID​(java.lang.String name)
        Returns a constant (name based) UUID, based on the given name in the OpenCms name space.
        Parameters:
        name - the name to derive the uuid from
        Returns:
        name based UUID of the given name
      • getDummyEthernetAddress

        public static java.lang.String getDummyEthernetAddress()
        Returns a String representing a dummy (random based) ethernet address.

        Returns:
        a String representing a dummy (random based) ethernet address
      • getNullUUID

        public static CmsUUID getNullUUID()
        Returns a null UUID, use this null UUID to check if a UUID has been initialized or not.

        Returns:
        a null UUID
      • getOpenCmsUUID

        public static CmsUUID getOpenCmsUUID()
        Returns a constant (name based) UUID for OpenCms, based on "www.opencms.org" in the dns name space.
        Returns:
        name based UUID of OpenCms
      • init

        public static void init​(java.lang.String ethernetAddress)
                         throws CmsInitException
        Initialize the UUID generator with the ethernet address of the server machine.

        The ethernetAddress parameter must represent a 'standard' ethernet MAC address string (e.g. '00:C0:F0:3D:5B:7C').

        Parameters:
        ethernetAddress - the ethernet address of the server machine
        Throws:
        CmsInitException - in case the ethernetAddress String is not a valid ethernet address
      • isValidUUID

        public static boolean isValidUUID​(java.lang.String uuid)
        Returns true if the given UUID is valid.

        Parameters:
        uuid - the UUID to check
        Returns:
        true if the given UUID is valid
      • valueOf

        public static CmsUUID valueOf​(java.lang.String uuid)
                               throws java.lang.NumberFormatException
        Returns the given String transformed to a UUID in case the String is a valid UUID.

        Parameters:
        uuid - the String to transform to a UUID
        Returns:
        the given String transformed to a UUID in case the String is a valid UUID
        Throws:
        java.lang.NumberFormatException - in case the String is no valid UUID
      • clone

        public java.lang.Object clone()
        Creates a clone of this CmsUUID.

        Overrides:
        clone in class java.lang.Object
        Returns:
        a clone of this CmsUUID
      • compareTo

        public int compareTo​(CmsUUID obj)
        Specified by:
        compareTo in interface java.lang.Comparable<CmsUUID>
        See Also:
        Comparable.compareTo(Object)
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
        See Also:
        Object.equals(java.lang.Object)
      • getStringValue

        public java.lang.String getStringValue()
        Returns the String representation of this UUID, same as toString().

        This method is useful if bean like access to the UUID String is required.

        Returns:
        the String representation of this UUID
      • hashCode

        public int hashCode()
        Optimized hashCode implementation for UUID's.

        Overrides:
        hashCode in class java.lang.Object
        See Also:
        Object.hashCode()
      • isNullUUID

        public boolean isNullUUID()
        Returns true if this UUID is equal to the null UUID.

        Returns:
        true if this UUID is equal to the null UUID
      • readExternal

        public void readExternal​(java.io.ObjectInput in)
        Specified by:
        readExternal in interface java.io.Externalizable
        See Also:
        Externalizable.readExternal(java.io.ObjectInput)
      • toByteArray

        public byte[] toByteArray()
        Returns the UUID as a 16-byte byte array.

        Returns:
        16-byte byte array that contains the UUID's bytes in the network byte order
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        See Also:
        Object.toString()
      • writeExternal

        public void writeExternal​(java.io.ObjectOutput out)
                           throws java.io.IOException
        Specified by:
        writeExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException
        See Also:
        Externalizable.writeExternal(java.io.ObjectOutput)