Package org.dellroad.stuff.java

Class IdGenerator

java.lang.Object
org.dellroad.stuff.java.IdGenerator
public class IdGenerator extends Object
Registry of unique IDs for objects.

Instances support creating unique long ID numbers for objects, as well as setting the unique ID to a specific value for any unregistered object.

This class uses object identity, not Object.equals(), to distinguish objects.

Weak references are used to ensure that registered objects can be garbage collected normally.

New long ID numbers are issued serially; after 264-1 invocations of getId(), an IllegalStateException will be thrown.

Instances are thread safe.

See Also:

  • Constructor Details

    • IdGenerator

      public IdGenerator()

  • Method Details

    • getId

      public long getId(Object obj)
      Get a unique ID for the given object.

      If this method has been previously invoked on this instance with the same obj parameter (where "same" means object identity, not Object.equals() identity), then the same ID value will be returned. Otherwise a new ID value will be returned.

      New IDs are assigned sequentially starting at 1. No conflict avoidance with IDs assigned via setId() is performed; if there is a conflict, an exception is thrown.

      Parameters:
      obj - object to ID; must not be null
      Returns:
      a non-zero, unique identifier for obj
      Throws:
      IllegalArgumentException - if obj is null
      IllegalStateException - if the next sequential ID has already been assigned to a different object via setId()
      IllegalStateException - if all 264-1 values have been used up

    • nextId

      public long nextId()
      Get the next ID to be assigned.

      This method does not actually assign the ID; it only returns the ID that would be assigned by the next invocation of getId(java.lang.Object).

      Returns:
      next available ID

    • checkId

      public long checkId(Object obj)
      Test whether the given object is already registered with this instance.
      Parameters:
      obj - object to test; must not be null
      Returns:
      a non-zero, unique identifier for obj if already registered, otherwise zero
      Throws:
      IllegalArgumentException - if obj is null

    • setId

      public void setId(Object obj, long id)
      Assign a unique ID to the given object. Does nothing if the object and ID number are already associated.
      Parameters:
      obj - object to assign
      id - unique ID number to assign
      Throws:
      IllegalArgumentException - if obj is null
      IllegalArgumentException - if id has already been assigned to some other object

    • getObject

      public Object getObject(long id)
      Get the object assigned to the given ID.
      Parameters:
      id - unique ID
      Returns:
      object associated with that ID, or null if no object is assigned to id

    • flush

      public void flush()
      Flush any cleared weak references.

      This operation is invoked by getId() and setId(), so it's usually not necessary to explicitly invoke it. However, if a lot of previously ID'd objects have been garbage collected since the last call to getId(), then invoking this method may free up some additional memory.

    • run

      public static void run(Runnable action)
      Create a new IdGenerator and make it available via get() for the duration of the given operation.

      This method is re-entrant: nested invocations of this method in the same thread re-use the same IdGenerator instance.

      Parameters:
      action - action to perform, and which may successfully invoke get()
      Throws:
      IllegalArgumentException - if action is null

    • run

      public static <R> R run(Supplier<R> action)
      Create a new IdGenerator and make it available via get() for the duration of the given operation.

      This method is re-entrant: nested invocations of this method in the same thread re-use the same IdGenerator instance.

      Type Parameters:
      R - action return type
      Parameters:
      action - action to perform, and which may successfully invoke get()
      Returns:
      result of invoking action
      Throws:
      IllegalArgumentException - if action is null

    • get

      public static IdGenerator get()
      Get the IdGenerator associated with the current thread. This method only works when the current thread is running within an invocation of run(); otherwise, an IllegalStateException is thrown.
      Returns:
      the IdGenerator created in the most recent, still running invocation of run(java.lang.Runnable) in this thread
      Throws:
      IllegalStateException - if there is not such instance