ObjID is used to identify a remote object exported
+ * to an RMI runtime. When a remote object is exported, it is assigned
+ * an object identifier either implicitly or explicitly, depending on
+ * the API used to export.
+ *
+ * The {@link #ObjID()} constructor can be used to generate a unique
+ * object identifier. Such an ObjID is unique over time
+ * with respect to the host it is generated on.
+ *
+ * The {@link #ObjID(int)} constructor can be used to create a
+ * "well-known" object identifier. The scope of a well-known
+ * ObjID depends on the RMI runtime it is exported to.
+ *
+ *
An ObjID instance contains an object number (of type
+ * long) and an address space identifier (of type
+ * {@link UID}). In a unique ObjID, the address space
+ * identifier is unique with respect to a given host over time. In a
+ * well-known ObjID, the address space identifier is
+ * equivalent to one returned by invoking the {@link UID#UID(short)}
+ * constructor with the value zero.
+ *
+ *
If the system property java.rmi.server.randomIDs
+ * is defined to equal the string "true" (case insensitive),
+ * then the {@link #ObjID()} constructor will use a cryptographically
+ * strong random number generator to choose the object number of the
+ * returned ObjID.
+ *
+ * @author Ann Wollrath
+ * @author Peter Jones
+ * @since 1.1
+ */
+public final class ObjID implements Serializable {
+
+ /** Object number for well-known ObjID of the registry. */
+ public static final int REGISTRY_ID = 0;
+
+ /** Object number for well-known ObjID of the activator. */
+ public static final int ACTIVATOR_ID = 1;
+
+ /**
+ * Object number for well-known ObjID of
+ * the distributed garbage collector.
+ */
+ public static final int DGC_ID = 2;
+
+ /** indicate compatibility with JDK 1.1.x version of class */
+ private static final long serialVersionUID = -6386392263968365220L;
+
+ private static final AtomicLong nextObjNum = new AtomicLong(0);
+ private static final UID mySpace = new UID();
+ private static final SecureRandom secureRandom = new SecureRandom();
+
+ /**
+ * @serial object number
+ * @see #hashCode
+ */
+ private final long objNum;
+
+ /**
+ * @serial address space identifier (unique to host over time)
+ */
+ private final UID space;
+
+ /**
+ * Generates a unique object identifier.
+ *
+ *
If the system property java.rmi.server.randomIDs
+ * is defined to equal the string "true" (case insensitive),
+ * then this constructor will use a cryptographically
+ * strong random number generator to choose the object number of the
+ * returned ObjID.
+ */
+ public ObjID() {
+ /*
+ * If generating random object numbers, create a new UID to
+ * ensure uniqueness; otherwise, use a shared UID because
+ * sequential object numbers already ensure uniqueness.
+ */
+ if (useRandomIDs()) {
+ space = new UID();
+ objNum = secureRandom.nextLong();
+ } else {
+ space = mySpace;
+ objNum = nextObjNum.getAndIncrement();
+ }
+ }
+
+ /**
+ * Creates a "well-known" object identifier.
+ *
+ *
An ObjID created via this constructor will not
+ * clash with any ObjIDs generated via the no-arg
+ * constructor.
+ *
+ * @param objNum object number for well-known object identifier
+ */
+ public ObjID(int objNum) {
+ space = new UID((short) 0);
+ this.objNum = objNum;
+ }
+
+ /**
+ * Constructs an object identifier given data read from a stream.
+ */
+ private ObjID(long objNum, UID space) {
+ this.objNum = objNum;
+ this.space = space;
+ }
+
+ /**
+ * Marshals a binary representation of this ObjID to
+ * an ObjectOutput instance.
+ *
+ *
Specifically, this method first invokes the given stream's
+ * {@link ObjectOutput#writeLong(long)} method with this object
+ * identifier's object number, and then it writes its address
+ * space identifier by invoking its {@link UID#write(DataOutput)}
+ * method with the stream.
+ *
+ * @param out the ObjectOutput instance to write
+ * this ObjID to
+ *
+ * @throws IOException if an I/O error occurs while performing
+ * this operation
+ */
+ public void write(ObjectOutput out) throws IOException {
+ out.writeLong(objNum);
+ space.write(out);
+ }
+
+ /**
+ * Constructs and returns a new ObjID instance by
+ * unmarshalling a binary representation from an
+ * ObjectInput instance.
+ *
+ *
Specifically, this method first invokes the given stream's
+ * {@link ObjectInput#readLong()} method to read an object number,
+ * then it invokes {@link UID#read(DataInput)} with the
+ * stream to read an address space identifier, and then it
+ * creates and returns a new ObjID instance that
+ * contains the object number and address space identifier that
+ * were read from the stream.
+ *
+ * @param in the ObjectInput instance to read
+ * ObjID from
+ *
+ * @return unmarshalled ObjID instance
+ *
+ * @throws IOException if an I/O error occurs while performing
+ * this operation
+ */
+ public static ObjID read(ObjectInput in) throws IOException {
+ long num = in.readLong();
+ UID space = UID.read(in);
+ return new ObjID(num, space);
+ }
+
+ /**
+ * Returns the hash code value for this object identifier, the
+ * object number.
+ *
+ * @return the hash code value for this object identifier
+ */
+ public int hashCode() {
+ return (int) objNum;
+ }
+
+ /**
+ * Compares the specified object with this ObjID for
+ * equality.
+ *
+ * This method returns true if and only if the
+ * specified object is an ObjID instance with the same
+ * object number and address space identifier as this one.
+ *
+ * @param obj the object to compare this ObjID to
+ *
+ * @return true if the given object is equivalent to
+ * this one, and false otherwise
+ */
+ public boolean equals(Object obj) {
+ if (obj instanceof ObjID) {
+ ObjID id = (ObjID) obj;
+ return objNum == id.objNum && space.equals(id.space);
+ } else {
+ return false;
+ }
+ }
+
+ /**
+ * Returns a string representation of this object identifier.
+ *
+ * @return a string representation of this object identifier
+ */
+ /*
+ * The address space identifier is only included in the string
+ * representation if it does not denote the local address space
+ * (or if the randomIDs property was set).
+ */
+ public String toString() {
+ return "[" + (space.equals(mySpace) ? "" : space + ", ") +
+ objNum + "]";
+ }
+
+ private static boolean useRandomIDs() {
+ String value = AccessController.doPrivileged(
+ (PrivilegedAction