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 2⁶⁴-1 invocations of getId(), an IllegalStateException will be thrown.

See Also:

IdMapper

Constructor Summary

IdGenerator()

Method Summary

void	flush() Flush any cleared weak references.
static IdGenerator	get() Get the IdGenerator associated with the current thread.
long	getId(Object obj) Get a unique ID for the given object.
Object	getObject(long id) Get the object assigned to the given ID.
static <R> R	run(Callable<R> action) Create a new IdGenerator and make it available via get() for the duration of the given operation.
static void	run(Runnable action) Create a new IdGenerator and make it available via get() for the duration of the given operation.
void	setId(Object obj, long id) Assign a unique ID to the given object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IdGenerator

public IdGenerator()

Method Detail

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.

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 2⁶⁴-1 values have been used up

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(), so it's 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 will cause new IdGenerator instances to be created and used for the duration of the nested action.

Parameters:

action - action to perform, and which may successfully invoke get()

Throws:

NullPointerException - if action is null

run

public static <R> R run(Callable<R> action)
             throws Exception

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 will cause new IdGenerator instances to be created and used for the duration of the nested action.

Parameters:

action - action to perform, and which may successfully invoke get()

Returns:

result of invoking action

Throws:

NullPointerException - if action is null

Exception

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