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 }