/*
 * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package java.rmi.server;

import java.io.DataInput;
import java.io.DataOutput;
import java.io.IOException;
import java.io.ObjectInput;
import java.io.ObjectOutput;
import java.io.Serializable;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.security.SecureRandom;
import java.util.concurrent.atomic.AtomicLong;

An 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 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 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 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 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 ObjID() constructor will use a cryptographically strong random number generator to choose the object number of the returned ObjID.
Author:
     Ann Wollrath,      Peter Jones
Since:
      1.1/**
 * An <code>ObjID</code> 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.
 *
 * <p>The {@link #ObjID()} constructor can be used to generate a unique
 * object identifier.  Such an <code>ObjID</code> 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
 * <code>ObjID</code> depends on the RMI runtime it is exported to.
 *
 * <p>An <code>ObjID</code> instance contains an object number (of type
 * <code>long</code>) and an address space identifier (of type
 * {@link UID}).  In a unique <code>ObjID</code>, the address space
 * identifier is unique with respect to a given host over time.  In a
 * well-known <code>ObjID</code>, the address space identifier is
 * equivalent to one returned by invoking the {@link UID#UID(short)}
 * constructor with the value zero.
 *
 * <p>If the system property {@systemProperty java.rmi.server.randomIDs}
 * is defined to equal the string <code>"true"</code> (case insensitive),
 * then the {@link #ObjID()} constructor will use a cryptographically
 * strong random number generator to choose the object number of the
 * returned <code>ObjID</code>.
 *
 * @author      Ann Wollrath
 * @author      Peter Jones
 * @since       1.1
 */
public final class ObjID implements Serializable {

    
Object number for well-known ObjID of the registry. /** Object number for well-known <code>ObjID</code> of the registry. */
    public static final int REGISTRY_ID = 0;

    
Object number for well-known ObjID of the activator. /** Object number for well-known <code>ObjID</code> of the activator. */
    public static final int ACTIVATOR_ID = 1;

    
Object number for well-known ObjID of
the distributed garbage collector.
/**
     * Object number for well-known <code>ObjID</code> of
     * the distributed garbage collector.
     */
    public static final int DGC_ID = 2;

    
indicate compatibility with JDK 1.1.x version of class /** 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();

    
See Also:
hashCode
@serial
object number/**
     * @serial object number
     * @see #hashCode
     */
    private final long objNum;

    
@serial
address space identifier (unique to host over time)/**
     * @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.
/**
     * Generates a unique object identifier.
     *
     * <p>If the system property <code>java.rmi.server.randomIDs</code>
     * is defined to equal the string <code>"true"</code> (case insensitive),
     * then this constructor will use a cryptographically
     * strong random number generator to choose the object number of the
     * returned <code>ObjID</code>.
     */
    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.
Params:
objNum – object number for well-known object identifier/**
     * Creates a "well-known" object identifier.
     *
     * <p>An <code>ObjID</code> created via this constructor will not
     * clash with any <code>ObjID</code>s 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.
/**
     * 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 DataOutput.writeLong(long) method with this object identifier's object number, and then it writes its address space identifier by invoking its UID.write(DataOutput) method with the stream. 
Params:
out – the ObjectOutput instance to write
this ObjID to
Throws:
IOException – if an I/O error occurs while performing
this operation/**
     * Marshals a binary representation of this <code>ObjID</code> to
     * an <code>ObjectOutput</code> instance.
     *
     * <p>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 <code>ObjectOutput</code> instance to write
     * this <code>ObjID</code> 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 DataInput.readLong() method to read an object number, then it invokes 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.
Params:
in – the ObjectInput instance to read
ObjID from
Throws:
IOException – if an I/O error occurs while performing
this operation
Returns:
 unmarshalled ObjID instance/**
     * Constructs and returns a new <code>ObjID</code> instance by
     * unmarshalling a binary representation from an
     * <code>ObjectInput</code> instance.
     *
     * <p>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 <code>ObjID</code> instance that
     * contains the object number and address space identifier that
     * were read from the stream.
     *
     * @param   in the <code>ObjectInput</code> instance to read
     * <code>ObjID</code> from
     *
     * @return  unmarshalled <code>ObjID</code> 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.
Returns:
 the hash code value for this object identifier/**
     * 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.
Params:
obj – the object to compare this ObjID to
Returns:
 true if the given object is equivalent to
this one, and false otherwise/**
     * Compares the specified object with this <code>ObjID</code> for
     * equality.
     *
     * This method returns <code>true</code> if and only if the
     * specified object is an <code>ObjID</code> instance with the same
     * object number and address space identifier as this one.
     *
     * @param   obj the object to compare this <code>ObjID</code> to
     *
     * @return  <code>true</code> if the given object is equivalent to
     * this one, and <code>false</code> 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.
Returns:
 a string representation of this object identifier/**
     * 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<String>) () -> System.getProperty("java.rmi.server.randomIDs"));
        return value == null ? true : Boolean.parseBoolean(value);
    }
}