FileDocCategorySizeDatePackage
UID.javaAPI DocJava SE 6 API8085Tue Jun 10 00:25:44 BST 2008java.rmi.server

UID

public final class UID extends Object implements Serializable
A UID represents an identifier that is unique over time with respect to the host it is generated on, or one of 216 "well-known" identifiers.

The {@link #UID()} constructor can be used to generate an identifier that is unique over time with respect to the host it is generated on. The {@link #UID(short)} constructor can be used to create one of 216 well-known identifiers.

A UID instance contains three primitive values:

  • unique, an int that uniquely identifies the VM that this UID was generated in, with respect to its host and at the time represented by the time value (an example implementation of the unique value would be a process identifier), or zero for a well-known UID
  • time, a long equal to a time (as returned by {@link System#currentTimeMillis()}) at which the VM that this UID was generated in was alive, or zero for a well-known UID
  • count, a short to distinguish UIDs generated in the same VM with the same time value

An independently generated UID instance is unique over time with respect to the host it is generated on as long as the host requires more than one millisecond to reboot and its system clock is never set backward. A globally unique identifier can be constructed by pairing a UID instance with a unique host identifier, such as an IP address.

author
Ann Wollrath
author
Peter Jones
version
1.24, 06/02/23
since
JDK1.1

Fields Summary
private static int
hostUnique
private static boolean
hostUniqueSet
private static final Object
lock
private static long
lastTime
private static short
lastCount
private static final long
serialVersionUID
indicate compatibility with JDK 1.1.x version of class
private final int
unique
number that uniquely identifies the VM that this UID was generated in with respect to its host and at the given time
private final long
time
a time (as returned by {@link System#currentTimeMillis()}) at which the VM that this UID was generated in was alive
private final short
count
16-bit number to distinguish UID instances created in the same VM with the same time value
Constructors Summary
public UID()
Generates a UID that is unique over time with respect to the host that it was generated on.


                           
      
	
	synchronized (lock) {
	    if (!hostUniqueSet) {
		hostUnique = (new SecureRandom()).nextInt();
		hostUniqueSet = true;
	    }
	    unique = hostUnique;
	    if (lastCount == Short.MAX_VALUE) {
		boolean interrupted = Thread.interrupted();
		boolean done = false;
		while (!done) {
		    long now = System.currentTimeMillis();
		    if (now <= lastTime) {
			// wait for time to change
			try {
			    Thread.currentThread().sleep(1);
			} catch (InterruptedException e) {
			    interrupted = true;
			}
		    } else {
			lastTime = now;
			lastCount = Short.MIN_VALUE;
			done = true;
		    }
		}
		if (interrupted) {
		    Thread.currentThread().interrupt();
		}
	    }
	    time = lastTime;
	    count = lastCount++;
	}
    
public UID(short num)
Creates a "well-known" UID. There are 216 possible such well-known ids.

A UID created via this constructor will not clash with any UIDs generated via the no-arg constructor.

param
num number for well-known UID

	unique = 0;
	time = 0;
	count = num;
    
private UID(int unique, long time, short count)
Constructs a UID given data read from a stream.

	this.unique = unique;
	this.time = time;
	this.count = count;
    
Methods Summary
public booleanequals(java.lang.Object obj)
Compares the specified object with this UID for equality. This method returns true if and only if the specified object is a UID instance with the same unique, time, and count values as this one.

param
obj the object to compare this UID to
return
true if the given object is equivalent to this one, and false otherwise

	if (obj instanceof UID) {
	    UID uid = (UID) obj;
	    return (unique == uid.unique &&
		    count == uid.count &&
		    time == uid.time);
	} else {
	    return false;
	}
    
public inthashCode()
Returns the hash code value for this UID.

return
the hash code value for this UID

	return (int) time + (int) count;
    
public static java.rmi.server.UIDread(java.io.DataInput in)
Constructs and returns a new UID instance by unmarshalling a binary representation from an DataInput instance.

Specifically, this method first invokes the given stream's {@link DataInput#readInt()} method to read a unique value, then it invoke's the stream's {@link DataInput#readLong()} method to read a time value, then it invoke's the stream's {@link DataInput#readShort()} method to read a count value, and then it creates and returns a new UID instance that contains the unique, time, and count values that were read from the stream.

param
in the DataInput instance to read UID from
return
unmarshalled UID instance
throws
IOException if an I/O error occurs while performing this operation

	int unique = in.readInt();
	long time = in.readLong();
	short count = in.readShort();
	return new UID(unique, time, count);
    
public java.lang.StringtoString()
Returns a string representation of this UID.

return
a string representation of this UID

	return Integer.toString(unique,16) + ":" +
	    Long.toString(time,16) + ":" +
	    Integer.toString(count,16);
    
public voidwrite(java.io.DataOutput out)
Marshals a binary representation of this UID to a DataOutput instance.

Specifically, this method first invokes the given stream's {@link DataOutput#writeInt(int)} method with this UID's unique value, then it invokes the stream's {@link DataOutput#writeLong(long)} method with this UID's time value, and then it invokes the stream's {@link DataOutput#writeShort(int)} method with this UID's count value.

param
out the DataOutput instance to write this UID to
throws
IOException if an I/O error occurs while performing this operation

	out.writeInt(unique);
	out.writeLong(time);
	out.writeShort(count);