Class UniqueIdentifier

java.lang.Object
com.github.yellowstonegames.core.UniqueIdentifier
All Implemented Interfaces:
Comparable<UniqueIdentifier>
public final class UniqueIdentifier extends Object implements Comparable<UniqueIdentifier>
A substitute for the UUID class, since it isn't available on GWT. The typical usage is to call next() when you want a new UniqueIdentifier. If the app is closing down and needs to save its state to be resumed later, GENERATOR must be serialized as well, and deserialized before calling next() again after resuming. Without this last step, the generated identifiers are extremely likely to be unique, but not guaranteed to be unique.
This can be serialized out-of-the-box to Strings using stringSerialize(), but if you do, so must the GENERATOR that produces new UniqueIdentifier instances and ensures they are unique. If you are using Fory or another type of serializer that can register arbitrary classes, this can be sent directly to that without needing any extra serialization code. Like with the String serialization, you must serialize the GENERATOR field and restore it when restarting from a serialized state. The Base class (in digital) is all this uses from other code.
This is also Comparable, for some reason (UUID is, but since these should all be random, it doesn't mean much). UniqueIdentifier supports up to 2 to the 128 minus 1 unique instances, which should be far more than enough for centuries of generation. If you were using UUID, it only supports 2 to the 122 unique random UUIDs, with a collision 50% likely after 2 to the 61 UUIDs were generated. If this is used properly, it can't collide until all (2 to the 128 minus 1) identifiers have been generated.

  • Field Details

    • GENERATOR

      public static UniqueIdentifier.Generator GENERATOR
      The UniqueIdentifier.Generator that actually produces unique identifiers. If your application pauses and needs to be resumed later by loading serialized state, you must include this field in what you serialize, and load it before creating any additional UniqueIdentifier values with next() or UniqueIdentifier.Generator.generate(). Failure to maintain the previous GENERATOR value can result in identifiers not being unique.

  • Constructor Details

    • UniqueIdentifier

      public UniqueIdentifier()
      Creates a new, invalid UniqueIdentifier. All states will be 0. Use next() to generate random UniqueIdentifiers.

    • UniqueIdentifier

      public UniqueIdentifier(long hi, long lo)
      Creates a new UniqueIdentifier that may or may not actually be unique. This uses the given states verbatim. If both all states are 0, this will be treated as an invalid identifier. Most usage should prefer next() instead.
      Parameters:
      hi - the high 64 bits, as a long
      lo - the low 64 bits, as a long

    • UniqueIdentifier

      public UniqueIdentifier(int stateA, int stateB, int stateC, int stateD)
      Creates a new UniqueIdentifier that may or may not actually be unique. This uses the given states verbatim. If all states are 0, this will be treated as an invalid identifier. Most usage should prefer next() instead.
      Parameters:
      stateA - will be used verbatim for state a
      stateB - will be used verbatim for state b
      stateC - will be used verbatim for state c
      stateD - will be used verbatim for state d

    • UniqueIdentifier

      public UniqueIdentifier(String serialized)
      Given a String containing the output of stringSerialize(), this creates a new UniqueIdentifier with the same data as the UniqueIdentifier that was serialized.
      Parameters:
      serialized - a String almost always produced by stringSerialize()

  • Method Details

    • getA

      public int getA()

    • getB

      public int getB()

    • getC

      public int getC()

    • getD

      public int getD()

    • getHi

      public long getHi()

    • getLo

      public long getLo()

    • isValid

      public boolean isValid()
      Returns:
      false if this instance is the invalid all-0 value; true otherwise

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • stringSerialize

      public String stringSerialize()
      Serializes this UniqueIdentifier to a String, where it can be read back by stringDeserialize(String). This is different from most other stringSerialize() methods in that it always produces a 35-character String, consisting of getA(), then a '_', then getB(), then another underscore, c, underscore, and finally d, with a, b, c, and d represented as unsigned hex int Strings.
      Returns:
      a 35-character-long String storing this identifier; can be read back with stringDeserialize(String)

    • stringDeserialize

      public UniqueIdentifier stringDeserialize(String data)
      Reads back a String produced by stringSerialize(), storing the result in this UniqueIdentifier.
      Parameters:
      data - a String almost certainly produced by stringSerialize()
      Returns:
      this UniqueIdentifier, after it has been modified.

    • next

      public static UniqueIdentifier next()
      Generates a UniqueIdentifier that will actually be unique, assuming GENERATOR is non-null and has had its state tracked with the rest of the program (see the docs for GENERATOR).
      Returns:
      a new UniqueIdentifier that should be actually unique

    • compareTo

      public int compareTo(UniqueIdentifier other)
      Specified by:
      compareTo in interface Comparable<UniqueIdentifier>