KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > Reference


1 /*
2  * @(#)Reference.java 1.9 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.naming;
9
10 import java.util.Vector JavaDoc;
11 import java.util.Enumeration JavaDoc;
12
13 /**
14   * This class represents a reference to an object that is found outside of
15   * the naming/directory system.
16   *<p>
17   * Reference provides a way of recording address information about
18   * objects which themselves are not directly bound to the naming/directory system.
19   *<p>
20   * A Reference consists of an ordered list of addresses and class information
21   * about the object being referenced.
22   * Each address in the list identifies a communications endpoint
23   * for the same conceptual object. The "communications endpoint"
24   * is information that indicates how to contact the object. It could
25   * be, for example, a network address, a location in memory on the
26   * local machine, another process on the same machine, etc.
27   * The order of the addresses in the list may be of significance
28   * to object factories that interpret the reference.
29   *<p>
30   * Multiple addresses may arise for
31   * various reasons, such as replication or the object offering interfaces
32   * over more than one communication mechanism. The addresses are indexed
33   * starting with zero.
34   *<p>
35   * A Reference also contains information to assist in creating an instance
36   * of the object to which this Reference refers. It contains the class name
37   * of that object, and the class name and location of the factory to be used
38   * to create the object.
39   * The class factory location is a space-separated list of URLs representing
40   * the class path used to load the factory. When the factory class (or
41   * any class or resource upon which it depends) needs to be loaded,
42   * each URL is used (in order) to attempt to load the class.
43   *<p>
44   * A Reference instance is not synchronized against concurrent access by multiple
45   * threads. Threads that need to access a single Reference concurrently should
46   * synchronize amongst themselves and provide the necessary locking.
47   *
48   * @author Rosanna Lee
49   * @author Scott Seligman
50   * @version 1.9 04/05/05
51   *
52   * @see RefAddr
53   * @see StringRefAddr
54   * @see BinaryRefAddr
55   * @since 1.3
56   */

57
58   /*<p>
59   * The serialized form of a Reference object consists of the class
60   * name of the object being referenced (a String), a Vector of the
61   * addresses (each a RefAddr), the name of the class factory (a
62   * String), and the location of the class factory (a String).
63 */

64
65
66 public class Reference implements Cloneable JavaDoc, java.io.Serializable JavaDoc {
67     /**
68      * Contains the fully-qualified name of the class of the object to which
69      * this Reference refers.
70      * @serial
71      * @see java.lang.Class#getName
72      */

73     protected String JavaDoc className;
74     /**
75      * Contains the addresses contained in this Reference.
76      * Initialized by constructor.
77      * @serial
78      */

79     protected Vector JavaDoc<RefAddr JavaDoc> addrs = null;
80
81     /**
82      * Contains the name of the factory class for creating
83      * an instance of the object to which this Reference refers.
84      * Initialized to null.
85      * @serial
86      */

87     protected String JavaDoc classFactory = null;
88
89     /**
90      * Contains the location of the factory class.
91      * Initialized to null.
92      * @serial
93      */

94     protected String JavaDoc classFactoryLocation = null;
95
96     /**
97       * Constructs a new reference for an object with class name 'className'.
98       * Class factory and class factory location are set to null.
99       * The newly created reference contains zero addresses.
100       *
101       * @param className The non-null class name of the object to which
102       * this reference refers.
103       */

104     public Reference(String JavaDoc className) {
105     this.className = className;
106     addrs = new Vector JavaDoc();
107     }
108
109     /**
110       * Constructs a new reference for an object with class name 'className' and
111       * an address.
112       * Class factory and class factory location are set to null.
113       *
114       * @param className The non-null class name of the object to
115       * which this reference refers.
116       * @param addr The non-null address of the object.
117       */

118     public Reference(String JavaDoc className, RefAddr JavaDoc addr) {
119     this.className = className;
120     addrs = new Vector JavaDoc();
121     addrs.addElement(addr);
122     }
123
124     /**
125       * Constructs a new reference for an object with class name 'className',
126       * and the class name and location of the object's factory.
127       *
128       * @param className The non-null class name of the object to which
129       * this reference refers.
130       * @param factory The possibly null class name of the object's factory.
131       * @param factoryLocation
132       * The possibly null location from which to load
133       * the factory (e.g. URL)
134       * @see javax.naming.spi.ObjectFactory
135       * @see javax.naming.spi.NamingManager#getObjectInstance
136       */

137     public Reference(String JavaDoc className, String JavaDoc factory, String JavaDoc factoryLocation) {
138     this(className);
139     classFactory = factory;
140     classFactoryLocation = factoryLocation;
141     }
142
143     /**
144       * Constructs a new reference for an object with class name 'className',
145       * the class name and location of the object's factory, and the address for
146       * the object.
147       *
148       * @param className The non-null class name of the object to
149       * which this reference refers.
150       * @param factory The possibly null class name of the object's factory.
151       * @param factoryLocation The possibly null location from which
152       * to load the factory (e.g. URL)
153       * @param addr The non-null address of the object.
154       * @see javax.naming.spi.ObjectFactory
155       * @see javax.naming.spi.NamingManager#getObjectInstance
156       */

157     public Reference(String JavaDoc className, RefAddr JavaDoc addr,
158              String JavaDoc factory, String JavaDoc factoryLocation) {
159     this(className, addr);
160     classFactory = factory;
161     classFactoryLocation = factoryLocation;
162     }
163
164     /**
165       * Retrieves the class name of the object to which this reference refers.
166       *
167       * @return The non-null fully-qualified class name of the object.
168       * (e.g. "java.lang.String")
169       */

170     public String JavaDoc getClassName() {
171     return className;
172     }
173
174     /**
175       * Retrieves the class name of the factory of the object
176       * to which this reference refers.
177       *
178       * @return The possibly null fully-qualified class name of the factory.
179       * (e.g. "java.lang.String")
180       */

181     public String JavaDoc getFactoryClassName() {
182     return classFactory;
183     }
184
185     /**
186       * Retrieves the location of the factory of the object
187       * to which this reference refers.
188       * If it is a codebase, then it is an ordered list of URLs,
189       * separated by spaces, listing locations from where the factory
190       * class definition should be loaded.
191       *
192       * @return The possibly null string containing the
193       * location for loading in the factory's class.
194       */

195     public String JavaDoc getFactoryClassLocation() {
196     return classFactoryLocation;
197     }
198
199     /**
200       * Retrieves the first address that has the address type 'addrType'.
201       * String.compareTo() is used to test the equality of the address types.
202       *
203       * @param addrType The non-null address type for which to find the address.
204       * @return The address in this reference with address type 'addrType;
205       * null if no such address exist.
206       */

207     public RefAddr JavaDoc get(String JavaDoc addrType) {
208     int len = addrs.size();
209     RefAddr JavaDoc addr;
210     for (int i = 0; i < len; i++) {
211         addr = (RefAddr JavaDoc) addrs.elementAt(i);
212         if (addr.getType().compareTo(addrType) == 0)
213         return addr;
214     }
215     return null;
216     }
217
218     /**
219       * Retrieves the address at index posn.
220       * @param posn The index of the address to retrieve.
221       * @return The address at the 0-based index posn. It must be in the
222       * range [0,getAddressCount()).
223       * @exception ArrayIndexOutOfBoundsException If posn not in the specified
224       * range.
225       */

226     public RefAddr JavaDoc get(int posn) {
227     return ((RefAddr JavaDoc) addrs.elementAt(posn));
228     }
229
230     /**
231       * Retrieves an enumeration of the addresses in this reference.
232       * When addresses are added, changed or removed from this reference,
233       * its effects on this enumeration are undefined.
234       *
235       * @return An non-null enumeration of the addresses
236       * (<tt>RefAddr</tt>) in this reference.
237       * If this reference has zero addresses, an enumeration with
238       * zero elements is returned.
239       */

240     public Enumeration JavaDoc<RefAddr JavaDoc> getAll() {
241     return addrs.elements();
242     }
243
244     /**
245       * Retrieves the number of addresses in this reference.
246       *
247       * @return The nonnegative number of addresses in this reference.
248       */

249     public int size() {
250     return addrs.size();
251     }
252
253     /**
254       * Adds an address to the end of the list of addresses.
255       *
256       * @param addr The non-null address to add.
257       */

258     public void add(RefAddr JavaDoc addr) {
259     addrs.addElement(addr);
260     }
261
262     /**
263       * Adds an address to the list of addresses at index posn.
264       * All addresses at index posn or greater are shifted up
265       * the list by one (away from index 0).
266       *
267       * @param posn The 0-based index of the list to insert addr.
268       * @param addr The non-null address to add.
269       * @exception ArrayIndexOutOfBoundsException If posn not in the specified
270       * range.
271       */

272     public void add(int posn, RefAddr JavaDoc addr) {
273     addrs.insertElementAt(addr, posn);
274     }
275
276     /**
277       * Deletes the address at index posn from the list of addresses.
278       * All addresses at index greater than posn are shifted down
279       * the list by one (towards index 0).
280       *
281       * @param posn The 0-based index of in address to delete.
282       * @return The address removed.
283       * @exception ArrayIndexOutOfBoundsException If posn not in the specified
284       * range.
285       */

286     public Object JavaDoc remove(int posn) {
287     Object JavaDoc r = addrs.elementAt(posn);
288     addrs.removeElementAt(posn);
289     return r;
290     }
291
292     /**
293       * Deletes all addresses from this reference.
294       */

295     public void clear() {
296     addrs.setSize(0);
297     }
298
299     /**
300       * Determines whether obj is a reference with the same addresses
301       * (in same order) as this reference.
302       * The addresses are checked using RefAddr.equals().
303       * In addition to having the same addresses, the Reference also needs to
304       * have the same class name as this reference.
305       * The class factory and class factory location are not checked.
306       * If obj is null or not an instance of Reference, null is returned.
307       *
308       * @param obj The possibly null object to check.
309       * @return true if obj is equal to this reference; false otherwise.
310       */

311     public boolean equals(Object JavaDoc obj) {
312     if ((obj != null) && (obj instanceof Reference JavaDoc)) {
313         Reference JavaDoc target = (Reference JavaDoc)obj;
314         // ignore factory information
315
if (target.className.equals(this.className) &&
316         target.size() == this.size()) {
317         Enumeration JavaDoc mycomps = getAll();
318         Enumeration JavaDoc comps = target.getAll();
319         while (mycomps.hasMoreElements())
320             if (!(mycomps.nextElement().equals(comps.nextElement())))
321             return false;
322         return true;
323         }
324     }
325     return false;
326     }
327
328     /**
329       * Computes the hash code of this reference.
330       * The hash code is the sum of the hash code of its addresses.
331       *
332       * @return A hash code of this reference as an int.
333       */

334     public int hashCode() {
335     int hash = className.hashCode();
336     for (Enumeration JavaDoc e = getAll(); e.hasMoreElements();)
337         hash += e.nextElement().hashCode();
338     return hash;
339     }
340
341     /**
342       * Generates the string representation of this reference.
343       * The string consists of the class name to which this reference refers,
344       * and the string representation of each of its addresses.
345       * This representation is intended for display only and not to be parsed.
346       *
347       * @return The non-null string representation of this reference.
348       */

349     public String JavaDoc toString() {
350     StringBuffer JavaDoc buf = new StringBuffer JavaDoc("Reference Class Name: " +
351                         className + "\n");
352     int len = addrs.size();
353     for (int i = 0; i < len; i++)
354         buf.append(get(i).toString());
355     
356     return buf.toString();
357     }
358
359     /**
360      * Makes a copy of this reference using its class name
361      * list of addresses, class factory name and class factory location.
362      * Changes to the newly created copy does not affect this Reference
363      * and vice versa.
364      */

365     public Object JavaDoc clone() {
366     Reference JavaDoc r = new Reference JavaDoc(className, classFactory, classFactoryLocation);
367     Enumeration JavaDoc<RefAddr JavaDoc> a = getAll();
368     r.addrs = new Vector JavaDoc();
369
370     while (a.hasMoreElements())
371         r.addrs.addElement(a.nextElement());
372     return r;
373     }
374     /**
375      * Use serialVersionUID from JNDI 1.1.1 for interoperability
376      */

377     private static final long serialVersionUID = -1673475790065791735L;
378 };
379
Popular Tags