1 /*
2 * Copyright 1996-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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.SecureRandom;
35 import java.util.concurrent.atomic.AtomicLong;
36 import sun.security.action.GetPropertyAction;
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 JDK1.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 new GetPropertyAction("java.rmi.server.randomIDs"));
246 return value == null ? true : Boolean.parseBoolean(value);
247 }
248 }
Save This Page