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      */
ObjID()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      */
ObjID(int objNum)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      */
ObjID(long objNum, UID space)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      */
write(ObjectOutput out)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      */
read(ObjectInput in)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      */
hashCode()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      */
equals(Object obj)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      */
toString()238     public String toString() {
239         return "[" + (space.equals(mySpace) ? "" : space + ", ") +
240             objNum + "]";
241     }
242 
useRandomIDs()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 }
249