001 /*
002 * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming;
027
028 import java.util.Vector;
029 import java.util.Enumeration;
030
031 /**
032 * This class represents a reference to an object that is found outside of
033 * the naming/directory system.
034 *<p>
035 * Reference provides a way of recording address information about
036 * objects which themselves are not directly bound to the naming/directory system.
037 *<p>
038 * A Reference consists of an ordered list of addresses and class information
039 * about the object being referenced.
040 * Each address in the list identifies a communications endpoint
041 * for the same conceptual object. The "communications endpoint"
042 * is information that indicates how to contact the object. It could
043 * be, for example, a network address, a location in memory on the
044 * local machine, another process on the same machine, etc.
045 * The order of the addresses in the list may be of significance
046 * to object factories that interpret the reference.
047 *<p>
048 * Multiple addresses may arise for
049 * various reasons, such as replication or the object offering interfaces
050 * over more than one communication mechanism. The addresses are indexed
051 * starting with zero.
052 *<p>
053 * A Reference also contains information to assist in creating an instance
054 * of the object to which this Reference refers. It contains the class name
055 * of that object, and the class name and location of the factory to be used
056 * to create the object.
057 * The class factory location is a space-separated list of URLs representing
058 * the class path used to load the factory. When the factory class (or
059 * any class or resource upon which it depends) needs to be loaded,
060 * each URL is used (in order) to attempt to load the class.
061 *<p>
062 * A Reference instance is not synchronized against concurrent access by multiple
063 * threads. Threads that need to access a single Reference concurrently should
064 * synchronize amongst themselves and provide the necessary locking.
065 *
066 * @author Rosanna Lee
067 * @author Scott Seligman
068 * @version 1.16 07/05/05
069 *
070 * @see RefAddr
071 * @see StringRefAddr
072 * @see BinaryRefAddr
073 * @since 1.3
074 */
075
076 /*<p>
077 * The serialized form of a Reference object consists of the class
078 * name of the object being referenced (a String), a Vector of the
079 * addresses (each a RefAddr), the name of the class factory (a
080 * String), and the location of the class factory (a String).
081 */
082
083 public class Reference implements Cloneable, java.io.Serializable {
084 /**
085 * Contains the fully-qualified name of the class of the object to which
086 * this Reference refers.
087 * @serial
088 * @see java.lang.Class#getName
089 */
090 protected String className;
091 /**
092 * Contains the addresses contained in this Reference.
093 * Initialized by constructor.
094 * @serial
095 */
096 protected Vector<RefAddr> addrs = null;
097
098 /**
099 * Contains the name of the factory class for creating
100 * an instance of the object to which this Reference refers.
101 * Initialized to null.
102 * @serial
103 */
104 protected String classFactory = null;
105
106 /**
107 * Contains the location of the factory class.
108 * Initialized to null.
109 * @serial
110 */
111 protected String classFactoryLocation = null;
112
113 /**
114 * Constructs a new reference for an object with class name 'className'.
115 * Class factory and class factory location are set to null.
116 * The newly created reference contains zero addresses.
117 *
118 * @param className The non-null class name of the object to which
119 * this reference refers.
120 */
121 public Reference(String className) {
122 this .className = className;
123 addrs = new Vector();
124 }
125
126 /**
127 * Constructs a new reference for an object with class name 'className' and
128 * an address.
129 * Class factory and class factory location are set to null.
130 *
131 * @param className The non-null class name of the object to
132 * which this reference refers.
133 * @param addr The non-null address of the object.
134 */
135 public Reference(String className, RefAddr addr) {
136 this .className = className;
137 addrs = new Vector();
138 addrs.addElement(addr);
139 }
140
141 /**
142 * Constructs a new reference for an object with class name 'className',
143 * and the class name and location of the object's factory.
144 *
145 * @param className The non-null class name of the object to which
146 * this reference refers.
147 * @param factory The possibly null class name of the object's factory.
148 * @param factoryLocation
149 * The possibly null location from which to load
150 * the factory (e.g. URL)
151 * @see javax.naming.spi.ObjectFactory
152 * @see javax.naming.spi.NamingManager#getObjectInstance
153 */
154 public Reference(String className, String factory,
155 String factoryLocation) {
156 this (className);
157 classFactory = factory;
158 classFactoryLocation = factoryLocation;
159 }
160
161 /**
162 * Constructs a new reference for an object with class name 'className',
163 * the class name and location of the object's factory, and the address for
164 * the object.
165 *
166 * @param className The non-null class name of the object to
167 * which this reference refers.
168 * @param factory The possibly null class name of the object's factory.
169 * @param factoryLocation The possibly null location from which
170 * to load the factory (e.g. URL)
171 * @param addr The non-null address of the object.
172 * @see javax.naming.spi.ObjectFactory
173 * @see javax.naming.spi.NamingManager#getObjectInstance
174 */
175 public Reference(String className, RefAddr addr, String factory,
176 String factoryLocation) {
177 this (className, addr);
178 classFactory = factory;
179 classFactoryLocation = factoryLocation;
180 }
181
182 /**
183 * Retrieves the class name of the object to which this reference refers.
184 *
185 * @return The non-null fully-qualified class name of the object.
186 * (e.g. "java.lang.String")
187 */
188 public String getClassName() {
189 return className;
190 }
191
192 /**
193 * Retrieves the class name of the factory of the object
194 * to which this reference refers.
195 *
196 * @return The possibly null fully-qualified class name of the factory.
197 * (e.g. "java.lang.String")
198 */
199 public String getFactoryClassName() {
200 return classFactory;
201 }
202
203 /**
204 * Retrieves the location of the factory of the object
205 * to which this reference refers.
206 * If it is a codebase, then it is an ordered list of URLs,
207 * separated by spaces, listing locations from where the factory
208 * class definition should be loaded.
209 *
210 * @return The possibly null string containing the
211 * location for loading in the factory's class.
212 */
213 public String getFactoryClassLocation() {
214 return classFactoryLocation;
215 }
216
217 /**
218 * Retrieves the first address that has the address type 'addrType'.
219 * String.compareTo() is used to test the equality of the address types.
220 *
221 * @param addrType The non-null address type for which to find the address.
222 * @return The address in this reference with address type 'addrType;
223 * null if no such address exist.
224 */
225 public RefAddr get(String addrType) {
226 int len = addrs.size();
227 RefAddr addr;
228 for (int i = 0; i < len; i++) {
229 addr = (RefAddr) addrs.elementAt(i);
230 if (addr.getType().compareTo(addrType) == 0)
231 return addr;
232 }
233 return null;
234 }
235
236 /**
237 * Retrieves the address at index posn.
238 * @param posn The index of the address to retrieve.
239 * @return The address at the 0-based index posn. It must be in the
240 * range [0,getAddressCount()).
241 * @exception ArrayIndexOutOfBoundsException If posn not in the specified
242 * range.
243 */
244 public RefAddr get(int posn) {
245 return ((RefAddr) addrs.elementAt(posn));
246 }
247
248 /**
249 * Retrieves an enumeration of the addresses in this reference.
250 * When addresses are added, changed or removed from this reference,
251 * its effects on this enumeration are undefined.
252 *
253 * @return An non-null enumeration of the addresses
254 * (<tt>RefAddr</tt>) in this reference.
255 * If this reference has zero addresses, an enumeration with
256 * zero elements is returned.
257 */
258 public Enumeration<RefAddr> getAll() {
259 return addrs.elements();
260 }
261
262 /**
263 * Retrieves the number of addresses in this reference.
264 *
265 * @return The nonnegative number of addresses in this reference.
266 */
267 public int size() {
268 return addrs.size();
269 }
270
271 /**
272 * Adds an address to the end of the list of addresses.
273 *
274 * @param addr The non-null address to add.
275 */
276 public void add(RefAddr addr) {
277 addrs.addElement(addr);
278 }
279
280 /**
281 * Adds an address to the list of addresses at index posn.
282 * All addresses at index posn or greater are shifted up
283 * the list by one (away from index 0).
284 *
285 * @param posn The 0-based index of the list to insert addr.
286 * @param addr The non-null address to add.
287 * @exception ArrayIndexOutOfBoundsException If posn not in the specified
288 * range.
289 */
290 public void add(int posn, RefAddr addr) {
291 addrs.insertElementAt(addr, posn);
292 }
293
294 /**
295 * Deletes the address at index posn from the list of addresses.
296 * All addresses at index greater than posn are shifted down
297 * the list by one (towards index 0).
298 *
299 * @param posn The 0-based index of in address to delete.
300 * @return The address removed.
301 * @exception ArrayIndexOutOfBoundsException If posn not in the specified
302 * range.
303 */
304 public Object remove(int posn) {
305 Object r = addrs.elementAt(posn);
306 addrs.removeElementAt(posn);
307 return r;
308 }
309
310 /**
311 * Deletes all addresses from this reference.
312 */
313 public void clear() {
314 addrs.setSize(0);
315 }
316
317 /**
318 * Determines whether obj is a reference with the same addresses
319 * (in same order) as this reference.
320 * The addresses are checked using RefAddr.equals().
321 * In addition to having the same addresses, the Reference also needs to
322 * have the same class name as this reference.
323 * The class factory and class factory location are not checked.
324 * If obj is null or not an instance of Reference, null is returned.
325 *
326 * @param obj The possibly null object to check.
327 * @return true if obj is equal to this reference; false otherwise.
328 */
329 public boolean equals(Object obj) {
330 if ((obj != null) && (obj instanceof Reference)) {
331 Reference target = (Reference) obj;
332 // ignore factory information
333 if (target.className.equals(this .className)
334 && target.size() == this .size()) {
335 Enumeration mycomps = getAll();
336 Enumeration comps = target.getAll();
337 while (mycomps.hasMoreElements())
338 if (!(mycomps.nextElement().equals(comps
339 .nextElement())))
340 return false;
341 return true;
342 }
343 }
344 return false;
345 }
346
347 /**
348 * Computes the hash code of this reference.
349 * The hash code is the sum of the hash code of its addresses.
350 *
351 * @return A hash code of this reference as an int.
352 */
353 public int hashCode() {
354 int hash = className.hashCode();
355 for (Enumeration e = getAll(); e.hasMoreElements();)
356 hash += e.nextElement().hashCode();
357 return hash;
358 }
359
360 /**
361 * Generates the string representation of this reference.
362 * The string consists of the class name to which this reference refers,
363 * and the string representation of each of its addresses.
364 * This representation is intended for display only and not to be parsed.
365 *
366 * @return The non-null string representation of this reference.
367 */
368 public String toString() {
369 StringBuffer buf = new StringBuffer("Reference Class Name: "
370 + className + "\n");
371 int len = addrs.size();
372 for (int i = 0; i < len; i++)
373 buf.append(get(i).toString());
374
375 return buf.toString();
376 }
377
378 /**
379 * Makes a copy of this reference using its class name
380 * list of addresses, class factory name and class factory location.
381 * Changes to the newly created copy does not affect this Reference
382 * and vice versa.
383 */
384 public Object clone() {
385 Reference r = new Reference(className, classFactory,
386 classFactoryLocation);
387 Enumeration<RefAddr> a = getAll();
388 r.addrs = new Vector();
389
390 while (a.hasMoreElements())
391 r.addrs.addElement(a.nextElement());
392 return r;
393 }
394
395 /**
396 * Use serialVersionUID from JNDI 1.1.1 for interoperability
397 */
398 private static final long serialVersionUID = -1673475790065791735L;
399 };
|