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  ;
11  import java.util.Enumeration  ;
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  , java.io.Serializable   {
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   className;
74      /**
75       * Contains the addresses contained in this Reference.
76       * Initialized by constructor.
77       * @serial
78       */
79      protected Vector  <RefAddr  > 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   classFactory = null;
88  
89      /**
90       * Contains the location of the factory class.
91       * Initialized to null.
92       * @serial
93       */
94      protected String   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   className) {
105     this.className  = className;
106     addrs = new Vector  ();
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   className, RefAddr   addr) {
119     this.className = className;
120     addrs = new Vector  ();
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   className, String   factory, String   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   className, RefAddr   addr, 
158              String   factory, String   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   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   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   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   get(String   addrType) {
208     int len = addrs.size();
209     RefAddr   addr;
210     for (int i = 0; i < len; i++) {
211         addr = (RefAddr  ) 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   get(int posn) {
227     return ((RefAddr  ) 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  <RefAddr  > 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   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   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   remove(int posn) {
287     Object   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   obj) {
312     if ((obj != null) && (obj instanceof Reference  )) {
313         Reference   target = (Reference  )obj;
314         // ignore factory information
315         if (target.className.equals(this.className) &&
316         target.size() ==  this.size()) {
317         Enumeration   mycomps = getAll();
318         Enumeration   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   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   toString() {
350     StringBuffer   buf = new StringBuffer  ("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   clone() {
366     Reference   r = new Reference  (className, classFactory, classFactoryLocation);
367     Enumeration  <RefAddr  > a = getAll();
368     r.addrs = new Vector  ();
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags