1 /*

     2  * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 package java.rmi.server;

    26 

    27 import java.io.DataInput;

    28 import java.io.DataOutput;

    29 import java.io.IOException;

    30 import java.io.ObjectInput;

    31 import java.io.ObjectOutput;

    32 import java.io.Serializable;

    33 import java.security.AccessController;

    34 import java.security.PrivilegedAction;

    35 import java.security.SecureRandom;

    36 import java.util.concurrent.atomic.AtomicLong;

    37 

    38 /**

    39  * An <code>ObjID</code> is used to identify a remote object exported

    40  * to an RMI runtime.  When a remote object is exported, it is assigned

    41  * an object identifier either implicitly or explicitly, depending on

    42  * the API used to export.

    43  *

    44  * <p>The {@link #ObjID()} constructor can be used to generate a unique

    45  * object identifier.  Such an <code>ObjID</code> is unique over time

    46  * with respect to the host it is generated on.

    47  *

    48  * The {@link #ObjID(int)} constructor can be used to create a

    49  * "well-known" object identifier.  The scope of a well-known

    50  * <code>ObjID</code> depends on the RMI runtime it is exported to.

    51  *

    52  * <p>An <code>ObjID</code> instance contains an object number (of type

    53  * <code>long</code>) and an address space identifier (of type

    54  * {@link UID}).  In a unique <code>ObjID</code>, the address space

    55  * identifier is unique with respect to a given host over time.  In a

    56  * well-known <code>ObjID</code>, the address space identifier is

    57  * equivalent to one returned by invoking the {@link UID#UID(short)}

    58  * constructor with the value zero.

    59  *

    60  * <p>If the system property <code>java.rmi.server.randomIDs</code>

    61  * is defined to equal the string <code>"true"</code> (case insensitive),

    62  * then the {@link #ObjID()} constructor will use a cryptographically

    63  * strong random number generator to choose the object number of the

    64  * returned <code>ObjID</code>.

    65  *

    66  * @author      Ann Wollrath

    67  * @author      Peter Jones

    68  * @since       1.1

    69  */

    70 public final class ObjID implements Serializable {

    71 

    72     /** Object number for well-known <code>ObjID</code> of the registry. */

    73     public static final int REGISTRY_ID = 0;

    74 

    75     /** Object number for well-known <code>ObjID</code> of the activator. */

    76     public static final int ACTIVATOR_ID = 1;

    77 

    78     /**

    79      * Object number for well-known <code>ObjID</code> of

    80      * the distributed garbage collector.

    81      */

    82     public static final int DGC_ID = 2;

    83 

    84     /** indicate compatibility with JDK 1.1.x version of class */

    85     private static final long serialVersionUID = -6386392263968365220L;

    86 

    87     private static final AtomicLong nextObjNum = new AtomicLong(0);

    88     private static final UID mySpace = new UID();

    89     private static final SecureRandom secureRandom = new SecureRandom();

    90 

    91     /**

    92      * @serial object number

    93      * @see #hashCode

    94      */

    95     private final long objNum;

    96 

    97     /**

    98      * @serial address space identifier (unique to host over time)

    99      */

   100     private final UID space;

   101 

   102     /**

   103      * Generates a unique object identifier.

   104      *

   105      * <p>If the system property <code>java.rmi.server.randomIDs</code>

   106      * is defined to equal the string <code>"true"</code> (case insensitive),

   107      * then this constructor will use a cryptographically

   108      * strong random number generator to choose the object number of the

   109      * returned <code>ObjID</code>.

   110      */

   111     public ObjID() {

   112         /*

   113          * If generating random object numbers, create a new UID to

   114          * ensure uniqueness; otherwise, use a shared UID because

   115          * sequential object numbers already ensure uniqueness.

   116          */

   117         if (useRandomIDs()) {

   118             space = new UID();

   119             objNum = secureRandom.nextLong();

   120         } else {

   121             space = mySpace;

   122             objNum = nextObjNum.getAndIncrement();

   123         }

   124     }

   125 

   126     /**

   127      * Creates a "well-known" object identifier.

   128      *

   129      * <p>An <code>ObjID</code> created via this constructor will not

   130      * clash with any <code>ObjID</code>s generated via the no-arg

   131      * constructor.

   132      *

   133      * @param   objNum object number for well-known object identifier

   134      */

   135     public ObjID(int objNum) {

   136         space = new UID((short) 0);

   137         this.objNum = objNum;

   138     }

   139 

   140     /**

   141      * Constructs an object identifier given data read from a stream.

   142      */

   143     private ObjID(long objNum, UID space) {

   144         this.objNum = objNum;

   145         this.space = space;

   146     }

   147 

   148     /**

   149      * Marshals a binary representation of this <code>ObjID</code> to

   150      * an <code>ObjectOutput</code> instance.

   151      *

   152      * <p>Specifically, this method first invokes the given stream's

   153      * {@link ObjectOutput#writeLong(long)} method with this object

   154      * identifier's object number, and then it writes its address

   155      * space identifier by invoking its {@link UID#write(DataOutput)}

   156      * method with the stream.

   157      *

   158      * @param   out the <code>ObjectOutput</code> instance to write

   159      * this <code>ObjID</code> to

   160      *

   161      * @throws  IOException if an I/O error occurs while performing

   162      * this operation

   163      */

   164     public void write(ObjectOutput out) throws IOException {

   165         out.writeLong(objNum);

   166         space.write(out);

   167     }

   168 

   169     /**

   170      * Constructs and returns a new <code>ObjID</code> instance by

   171      * unmarshalling a binary representation from an

   172      * <code>ObjectInput</code> instance.

   173      *

   174      * <p>Specifically, this method first invokes the given stream's

   175      * {@link ObjectInput#readLong()} method to read an object number,

   176      * then it invokes {@link UID#read(DataInput)} with the

   177      * stream to read an address space identifier, and then it

   178      * creates and returns a new <code>ObjID</code> instance that

   179      * contains the object number and address space identifier that

   180      * were read from the stream.

   181      *

   182      * @param   in the <code>ObjectInput</code> instance to read

   183      * <code>ObjID</code> from

   184      *

   185      * @return  unmarshalled <code>ObjID</code> instance

   186      *

   187      * @throws  IOException if an I/O error occurs while performing

   188      * this operation

   189      */

   190     public static ObjID read(ObjectInput in) throws IOException {

   191         long num = in.readLong();

   192         UID space = UID.read(in);

   193         return new ObjID(num, space);

   194     }

   195 

   196     /**

   197      * Returns the hash code value for this object identifier, the

   198      * object number.

   199      *

   200      * @return  the hash code value for this object identifier

   201      */

   202     public int hashCode() {

   203         return (int) objNum;

   204     }

   205 

   206     /**

   207      * Compares the specified object with this <code>ObjID</code> for

   208      * equality.

   209      *

   210      * This method returns <code>true</code> if and only if the

   211      * specified object is an <code>ObjID</code> instance with the same

   212      * object number and address space identifier as this one.

   213      *

   214      * @param   obj the object to compare this <code>ObjID</code> to

   215      *

   216      * @return  <code>true</code> if the given object is equivalent to

   217      * this one, and <code>false</code> otherwise

   218      */

   219     public boolean equals(Object obj) {

   220         if (obj instanceof ObjID) {

   221             ObjID id = (ObjID) obj;

   222             return objNum == id.objNum && space.equals(id.space);

   223         } else {

   224             return false;

   225         }

   226     }

   227 

   228     /**

   229      * Returns a string representation of this object identifier.

   230      *

   231      * @return  a string representation of this object identifier

   232      */

   233     /*

   234      * The address space identifier is only included in the string

   235      * representation if it does not denote the local address space

   236      * (or if the randomIDs property was set).

   237      */

   238     public String toString() {

   239         return "[" + (space.equals(mySpace) ? "" : space + ", ") +

   240             objNum + "]";

   241     }

   242 

   243     private static boolean useRandomIDs() {

   244         String value = AccessController.doPrivileged(

   245             (PrivilegedAction<String>) () -> System.getProperty("java.rmi.server.randomIDs"));

   246         return value == null ? true : Boolean.parseBoolean(value);

   247     }

   248 }