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.
This can be serialized by custom serializers in squidstore.core for libGDX Json or squidfreeze.core for Kryo. Fory doesn't need a serializer registered.

  • 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.

    • PARSER

      public static final com.github.tommyettinger.ds.support.util.PartialParser<UniqueIdentifier> PARSER
      A jdkgdxds PartialParser that can be used to read UniqueIdentifier values from String-serialized data structures containing them.

  • 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(CharSequence serialized)
      Given a String or other CharSequence containing the output of stringSerialize() or appendTo(CharSequence), this creates a new UniqueIdentifier with the same data as the UniqueIdentifier that was serialized.
      Parameters:
      serialized - a CharSequence often produced by stringSerialize() or appendTo(CharSequence)

    • UniqueIdentifier

      public UniqueIdentifier(CharSequence data, int start)
      Given a String or other CharSequence containing the output of stringSerialize() or appendTo(CharSequence), this creates a new UniqueIdentifier with the same data as the UniqueIdentifier that was serialized.
      Parameters:
      data - a CharSequence often produced by stringSerialize() or appendTo(CharSequence)
      start - the first index, inclusive, to read 35 chars from

  • 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(CharSequence). 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(CharSequence)

    • appendTo

      public <S extends CharSequence & Appendable> S appendTo(S sb)
      Appends the serialized String format for this UniqueIdentifier to the given Appendable CharSequence, such as a StringBuilder or CharList. This separates the four int values, printed as unsigned with Base.BASE16, with underscores.
      Type Parameters:
      S - any Appendable CharSequence, such as a StringBuilder or CharList
      Parameters:
      sb - any Appendable CharSequence, such as a StringBuilder
      Returns:
      sb, for chaining

    • stringDeserialize

      public UniqueIdentifier stringDeserialize(CharSequence data)
      Reads back a CharSequence produced by stringSerialize() or appendTo(CharSequence), storing the result in this UniqueIdentifier. Reads chars from index 0 (inclusive) to 34 (inclusive).
      Parameters:
      data - a CharSequence often produced by stringSerialize() or appendTo(CharSequence)
      Returns:
      this UniqueIdentifier, after it has been modified.

    • stringDeserialize

      public UniqueIdentifier stringDeserialize(CharSequence data, int start)
      Loads the state of another serialized UniqueIdentifier (or UniqueIdentifier.Generator) into this. This requires a 35-char CharSequence (such as a String) at minimum after start with four 8-hex-digit sections, but the delimiters between sections are permitted to be anything (such as '$' for UniqueIdentifier.Generator or '_' for this).
      Parameters:
      data - a CharSequence often produced by stringSerialize() or appendTo(CharSequence)
      start - the first index, inclusive, to read 35 chars from
      Returns:
      this Generator, after deserializing

    • 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>