001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming;
019:
020: import java.io.Serializable;
021: import java.util.Enumeration;
022: import java.util.Vector;
023:
024: import org.apache.harmony.jndi.internal.nls.Messages;
025:
026: /**
027: * A <code>Reference</code> contains the class of the object which is
028: * referenced together with a list of all the addresses at which this object may
029: * be found. Additionally the <code>Reference</code> has the location of a
030: * factory which can create this object together with the classname used to
031: * create the object.
032: * <p>
033: * The <code>Reference</code> class relates to objects which are not bound in
034: * a naming service but which need to be accessed via javax.naming.
035: * <code>Reference</code>, <code>RefAddr</code> and their subclasses
036: * provide a way to access objects other than those in naming and directory
037: * systems.
038: * </p>
039: */
040: public class Reference implements Cloneable, Serializable {
041:
042: private static final long serialVersionUID = -1673475790065791735L;
043:
044: /**
045: * The class of the object which is referenced.
046: *
047: * @serial
048: */
049: protected String className;
050:
051: /**
052: * A list of the addresses provided for this object. The default is null.
053: *
054: * @serial
055: */
056: protected Vector<RefAddr> addrs;
057:
058: /**
059: * The class in a factory which is used to create an object of the type
060: * which is referenced. The default is null.
061: *
062: * @serial
063: */
064: protected String classFactory;
065:
066: /**
067: * The location of class <code>classFactory</code>. To find class files
068: * the URL of the classfile is given. If there is more than one URL for the
069: * class then a list of URLs appears in the string using a space as a
070: * separator. The default is null.
071: *
072: * @serial
073: */
074: protected String classFactoryLocation;
075:
076: /**
077: * Constructs a <code>Reference</code> instance with an empty list of
078: * addresses using the supplied class name.
079: *
080: * @param className
081: * the class of the object which is referenced. It cannot be
082: * null.
083: */
084: public Reference(String className) {
085: this (className, null, null);
086: }
087:
088: /**
089: * Constructs a <code>Reference</code> instance with one entry of address.
090: *
091: * @param className
092: * the class of the object which is referenced. It cannot be
093: * null.
094: * @param addr
095: * the object's address. It cannot be null.
096: */
097: public Reference(String className, RefAddr addr) {
098: this (className, addr, null, null);
099: }
100:
101: /**
102: * Constructs a <code>Reference</code> instance with an empty list of
103: * addresses using the supplied class name, factory class and factory
104: * location.
105: *
106: * @param className
107: * the class of the object which is referenced. It cannot be
108: * null.
109: * @param classFactory
110: * the class in a factory which is used to create an object of
111: * the type which is referenced. It may be null.
112: * @param classFactoryLocation
113: * the location of the class file. It may be null.
114: */
115: public Reference(String className, String classFactory,
116: String classFactoryLocation) {
117: super ();
118: this .className = className;
119: this .classFactory = classFactory;
120: this .classFactoryLocation = classFactoryLocation;
121: this .addrs = new Vector<RefAddr>();
122: }
123:
124: /**
125: * Constructs a <code>Reference</code> instance with one entry of address
126: * using the supplied class name, factory class and factory location.
127: *
128: * @param className
129: * the class of the object which is referenced. It cannot be
130: * null.
131: * @param addr
132: * the object's address. It cannot be null.
133: * @param classFactory
134: * the class in a factory which is used to create an object of
135: * the type which is referenced. It may be null.
136: * @param classFactoryLocation
137: * the location of the class file. It may be null.
138: */
139: public Reference(String className, RefAddr addr,
140: String classFactory, String classFactoryLocation) {
141: this (className, classFactory, classFactoryLocation);
142: this .addrs.add(addr);
143: }
144:
145: /**
146: * Gets the class of the object which is referenced. The result cannot be
147: * null.
148: *
149: * @return the class of the object which is referenced
150: */
151: public String getClassName() {
152: return this .className;
153: }
154:
155: /**
156: * Gets the class in a factory which is used to create an object of the type
157: * which is referenced. The result may be null.
158: *
159: * @return the class in a factory which is used to create the referenced
160: * object
161: */
162: public String getFactoryClassName() {
163: return this .classFactory;
164: }
165:
166: /**
167: * Gets the location of the factory class. The result may be null.
168: *
169: * @return the location of the factory class
170: */
171: public String getFactoryClassLocation() {
172: return this .classFactoryLocation;
173: }
174:
175: /**
176: * Gets all the addresses.
177: *
178: * @return an enumeration of all the addresses
179: */
180: public Enumeration<RefAddr> getAll() {
181: return addrs.elements();
182: }
183:
184: /**
185: * Gets an address where the address type matches the specified string.
186: * There may be more than one entry in the list with the same address type
187: * but this method returns the first one found in the list.
188: *
189: * @param type
190: * the address type to look for
191: * @return the first address whose type matches the string
192: */
193: public RefAddr get(String type) {
194: Enumeration<RefAddr> elements = addrs.elements();
195: RefAddr refAddr = null;
196:
197: while (elements.hasMoreElements()) {
198: refAddr = elements.nextElement();
199: if (type.equals(refAddr.getType())) {
200: return refAddr;
201: }
202: }
203: return null;
204: }
205:
206: /**
207: * Gets the address held at the specified index in the address list.
208: *
209: * @param index
210: * the index of the required address. It must be greater than or
211: * equal to 0 and less than the number of entries in the list.
212: * @return the address held at the specified index
213: * @throws ArrayIndexOutOfBoundsException
214: * If the index is invalid.
215: */
216: public RefAddr get(int index) {
217: return addrs.get(index);
218: }
219:
220: /**
221: * Appends an address to the list.
222: *
223: * @param addr
224: * the address to append. It cannot be null.
225: */
226: public void add(RefAddr addr) {
227: addrs.add(addr);
228: }
229:
230: /**
231: * Inserts an address within the list at the specified index.
232: *
233: * @param addr
234: * the address to insert into the list. It cannot be null.
235: * @param index
236: * the index where to insert the address. It must be greater than
237: * or equal to 0 and less than or equal to the number of entries
238: * in the list(size()).
239: * @throws ArrayIndexOutOfBoundsException
240: * If the index is invalid.
241: */
242: public void add(int index, RefAddr addr) {
243: addrs.add(index, addr);
244: }
245:
246: /**
247: * Removes an address from the address list.
248: *
249: * @param index
250: * the index of the address to remove. It must be greater than or
251: * equal to 0 and less than size().
252: * @return the removed address
253: * @throws ArrayIndexOutOfBoundsException
254: * If the index is invalid.
255: */
256: public Object remove(int index) {
257: return addrs.remove(index);
258: }
259:
260: /**
261: * Gets the number of addresses in the address list.
262: *
263: * @return the size of the list
264: */
265: public int size() {
266: return addrs.size();
267: }
268:
269: /**
270: * Deletes all the addresses from the address list.
271: */
272: public void clear() {
273: addrs.clear();
274: }
275:
276: /**
277: * Returns a deep clone of this <code>Reference</code> instance.
278: *
279: * @return a deep clone of this object
280: */
281: @SuppressWarnings("unchecked")
282: @Override
283: public Object clone() {
284: try {
285: Reference r = (Reference) super .clone();
286: r.addrs = (Vector<RefAddr>) this .addrs.clone();
287: return r;
288: } catch (CloneNotSupportedException e) {
289: // jndi.03=Failed to clone object of Reference class.
290: throw new AssertionError(Messages.getString("jndi.03")); //$NON-NLS-1$
291: }
292: }
293:
294: /**
295: * Returns true if this <code>Reference</code> instance is equal to the
296: * supplied object <code>o</code>. They are considered equal if their
297: * class name and list of addresses are equivalent (including the order of
298: * the addresses in the list). The factory class and location are ignored
299: * for the purposes of this comparison.
300: *
301: * @param o
302: * the object to compare with
303: * @return true if this object is equal to <code>o</code>, otherwise
304: * false
305: */
306: @Override
307: public boolean equals(Object o) {
308: if (o instanceof Reference) {
309: Reference r = (Reference) o;
310: return r.className.equals(this .className)
311: && r.addrs.equals(this .addrs);
312: }
313: return false;
314: }
315:
316: /**
317: * Returns the hashcode for this <code>Reference</code> instance. The
318: * result is calculated by summing the hashcode of the class name and the
319: * hash codes of each of the addresses in the address list.
320: *
321: * @return the hashcode of this <code>Reference</code> instance
322: */
323: @Override
324: public int hashCode() {
325: int i = this .className.hashCode();
326: Enumeration<RefAddr> e = this .addrs.elements();
327:
328: while (e.hasMoreElements()) {
329: i += e.nextElement().hashCode();
330: }
331: return i;
332: }
333:
334: /**
335: * Returns the string representation of the class name together with the
336: * list of addresses.
337: *
338: * @return the string representation of this object
339: */
340: @Override
341: public String toString() {
342: String s = "Reference class name: " + this .className; //$NON-NLS-1$
343: Enumeration<RefAddr> e = this .addrs.elements();
344:
345: s += "\nReference addresses:"; //$NON-NLS-1$
346: while (e.hasMoreElements()) {
347: s += "\n\t" + e.nextElement(); //$NON-NLS-1$
348: }
349: return s + "\n"; //$NON-NLS-1$
350: }
351:
352: }
|