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 */
25package java.rmi.server;
26
27import java.io.DataInput;
28import java.io.DataOutput;
29import java.io.IOException;
30import java.io.ObjectInput;
31import java.io.ObjectOutput;
32import java.io.Serializable;
33import java.security.AccessController;
34import java.security.PrivilegedAction;
35import java.security.SecureRandom;
36import 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 */
70public 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}
249