KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > rmi > server > ObjID


1 /*
2  * @(#)ObjID.java 1.29 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7 package java.rmi.server;
8
9 import java.io.DataInput JavaDoc;
10 import java.io.DataOutput JavaDoc;
11 import java.io.EOFException JavaDoc;
12 import java.io.IOException JavaDoc;
13 import java.io.InputStream JavaDoc;
14 import java.io.ObjectInput JavaDoc;
15 import java.io.ObjectOutput JavaDoc;
16 import java.io.OutputStream JavaDoc;
17 import java.security.SecureRandom JavaDoc;
18 import java.util.Random JavaDoc;
19
20 /**
21  * An <code>ObjID</code> is used to identify a remote object exported
22  * to an RMI runtime. When a remote object is exported, it is assigned
23  * an object identifier either implicitly or explicitly, depending on
24  * the API used to export.
25  *
26  * <p>The {@link #ObjID()} constructor can be used to generate a unique
27  * object identifier. Such an <code>ObjID</code> is unique over time
28  * with respect to the host it is generated on.
29  *
30  * The {@link #ObjID(int)} constructor can be used to create a
31  * "well-known" object identifier. The scope of a well-known
32  * <code>ObjID</code> depends on the RMI runtime it is exported to.
33  *
34  * <p>An <code>ObjID</code> instance contains an object number (of type
35  * <code>long</code>) and an address space identifier (of type
36  * {@link UID}). In a unique <code>ObjID</code>, the address space
37  * identifier is unique with respect to a given host over time. In a
38  * well-known <code>ObjID</code>, the address space identifier is
39  * equivalent to one returned by invoking the {@link UID#UID(short)}
40  * constructor with the value zero.
41  *
42  * <p>If the system property <code>java.rmi.server.randomIDs</code>
43  * is defined to equal the string <code>"true"</code> (case insensitive),
44  * then the {@link #ObjID()} constructor will use a cryptographically
45  * strong random number generator to choose the object number of the
46  * returned <code>ObjID</code>.
47  *
48  * @author Ann Wollrath
49  * @author Peter Jones
50  * @version 1.29, 03/12/19
51  * @since JDK1.1
52  */
53 public final class ObjID implements java.io.Serializable JavaDoc {
54
55     /** Object number for well-known <code>ObjID</code> of the registry. */
56     public static final int REGISTRY_ID = 0;
57
58     /** Object number for well-known <code>ObjID</code> of the activator. */
59     public static final int ACTIVATOR_ID = 1;
60
61     /**
62      * Object number for well-known <code>ObjID</code> of
63      * the distributed garbage collector.
64      */
65     public static final int DGC_ID = 2;
66
67     /** indicate compatibility with JDK 1.1.x version of class */
68     private static final long serialVersionUID = -6386392263968365220L;
69
70     private static final UID JavaDoc mySpace;
71     private static final Random JavaDoc generator;
72
73     /**
74      * @serial object number
75      * @see #hashCode
76      */
77     private final long objNum;
78
79     /**
80      * @serial address space identifier (unique to host over time)
81      */
82     private final UID JavaDoc space;
83
84     /**
85      * Generates a unique object identifier.
86      *
87      * <p>If the system property <code>java.rmi.server.randomIDs</code>
88      * is defined to equal the string <code>"true"</code> (case insensitive),
89      * then this constructor will use a cryptographically
90      * strong random number generator to choose the object number of the
91      * returned <code>ObjID</code>.
92      */
93     public ObjID() {
94     /*
95      * Create a new UID if the SecureRandom generator is used (mySpace
96      * will be null in this case). Using a different UID for each ObjID
97      * ensures that ObjIDs will be unique in this VM incarnation when
98      * paired with the result of the secure random number generator.
99      */
100     space = (mySpace != null) ? mySpace : new UID JavaDoc();
101     objNum = generator.nextLong();
102     }
103
104     /**
105      * Creates a "well-known" object identifier.
106      *
107      * <p>An <code>ObjID</code> created via this constructor will not
108      * clash with any <code>ObjID</code>s generated via the no-arg
109      * constructor.
110      *
111      * @param objNum object number for well-known object identifier
112      */
113     public ObjID(int objNum) {
114     space = new UID JavaDoc((short) 0);
115     this.objNum = objNum;
116     }
117
118     /**
119      * Constructs an object identifier given data read from a stream.
120      */
121     private ObjID(long objNum, UID JavaDoc space) {
122     this.objNum = objNum;
123     this.space = space;
124     }
125
126     /**
127      * Marshals a binary representation of this <code>ObjID</code> to
128      * an <code>ObjectOutput</code> instance.
129      *
130      * <p>Specifically, this method first invokes the given stream's
131      * {@link ObjectOutput#writeLong(long)} method with this object
132      * identifier's object number, and then it writes its address
133      * space identifier by invoking its {@link UID#write(DataOutput)}
134      * method with the stream.
135      *
136      * @param out the <code>ObjectOutput</code> instance to write
137      * this <code>ObjID</code> to
138      *
139      * @throws IOException if an I/O error occurs while performing
140      * this operation
141      */
142     public void write(ObjectOutput JavaDoc out) throws IOException JavaDoc {
143     out.writeLong(objNum);
144     space.write(out);
145     }
146
147     /**
148      * Constructs and returns a new <code>ObjID</code> instance by
149      * unmarshalling a binary representation from an
150      * <code>ObjectInput</code> instance.
151      *
152      * <p>Specifically, this method first invokes the given stream's
153      * {@link ObjectInput#readLong()} method to read an object number,
154      * then it invokes {@link UID#read(DataInput)} with the
155      * stream to read an address space identifier, and then it
156      * creates and returns a new <code>ObjID</code> instance that
157      * contains the object number and address space identifier that
158      * were read from the stream.
159      *
160      * @param in the <code>ObjectInput</code> instance to read
161      * <code>ObjID</code> from
162      *
163      * @return unmarshalled <code>ObjID</code> instance
164      *
165      * @throws IOException if an I/O error occurs while performing
166      * this operation
167      */
168     public static ObjID JavaDoc read(ObjectInput JavaDoc in) throws IOException JavaDoc {
169     long num = in.readLong();
170     UID JavaDoc space = UID.read(in);
171     return new ObjID JavaDoc(num, space);
172     }
173
174     /**
175      * Returns the hash code value for this object identifier, the
176      * object number.
177      *
178      * @return the hash code value for this object identifier
179      */
180     public int hashCode() {
181     return (int) objNum;
182     }
183
184     /**
185      * Compares the specified object with this <code>ObjID</code> for
186      * equality.
187      *
188      * This method returns <code>true</code> if and only if the
189      * specified object is an <code>ObjID</code> instance with the same
190      * object number and address space identifier as this one.
191      *
192      * @param obj the object to compare this <code>ObjID</code> to
193      *
194      * @return <code>true</code> if the given object is equivalent to
195      * this one, and <code>false</code> otherwise
196      */
197     public boolean equals(Object JavaDoc obj) {
198     if (obj instanceof ObjID JavaDoc) {
199         ObjID JavaDoc id = (ObjID JavaDoc)obj;
200         return objNum == id.objNum && space.equals(id.space);
201     } else {
202         return false;
203     }
204     }
205
206     /**
207      * Returns a string representation of this object identifier.
208      *
209      * @return a string representation of this object identifier
210      */
211     /*
212      * The address space identifier is only included in the string
213      * representation if it does not denote the local address space
214      * (or if the randomIDs property was set).
215      */
216     public String JavaDoc toString() {
217     return "[" + (space.equals(mySpace) ? "" : space + ", ") +
218         objNum + "]";
219     }
220
221     private static final class InsecureRandom extends Random JavaDoc {
222
223     /** unnecessary serialVersionUID to keep watchdog tools happy */
224     private static final long serialVersionUID = -698228687531590145L;
225
226     private long nextNum;
227
228     public synchronized long nextLong() {
229         return nextNum++;
230     }
231     }
232
233     static {
234     boolean randomIDs =
235         ((Boolean JavaDoc) java.security.AccessController.doPrivileged(
236             new sun.security.action.GetBooleanAction(
237             "java.rmi.server.randomIDs"))).booleanValue();
238
239     if (randomIDs) {
240         generator = new SecureRandom JavaDoc();
241         mySpace = null;
242     } else {
243         generator = new InsecureRandom();
244         /*
245          * The InsecureRandom implementation guarantees that object
246          * numbers will not repeat, so the same UID value can be used
247          * for all instances of ObjID.
248          */
249         mySpace = new UID JavaDoc();
250     }
251     }
252 }
253
Popular Tags