1 /*

     2  * Copyright (c) 1999, 2011, 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 

    26 package javax.naming;

    27 

    28 import java.util.Vector;

    29 import java.util.Enumeration;

    30 

    31 /**

    32   * This class represents a reference to an object that is found outside of

    33   * the naming/directory system.

    34   *<p>

    35   * Reference provides a way of recording address information about

    36   * objects which themselves are not directly bound to the naming/directory system.

    37   *<p>

    38   * A Reference consists of an ordered list of addresses and class information

    39   * about the object being referenced.

    40   * Each address in the list identifies a communications endpoint

    41   * for the same conceptual object.  The "communications endpoint"

    42   * is information that indicates how to contact the object. It could

    43   * be, for example, a network address, a location in memory on the

    44   * local machine, another process on the same machine, etc.

    45   * The order of the addresses in the list may be of significance

    46   * to object factories that interpret the reference.

    47   *<p>

    48   * Multiple addresses may arise for

    49   * various reasons, such as replication or the object offering interfaces

    50   * over more than one communication mechanism.  The addresses are indexed

    51   * starting with zero.

    52   *<p>

    53   * A Reference also contains information to assist in creating an instance

    54   * of the object to which this Reference refers.  It contains the class name

    55   * of that object, and the class name and location of the factory to be used

    56   * to create the object.

    57   * The class factory location is a space-separated list of URLs representing

    58   * the class path used to load the factory.  When the factory class (or

    59   * any class or resource upon which it depends) needs to be loaded,

    60   * each URL is used (in order) to attempt to load the class.

    61   *<p>

    62   * A Reference instance is not synchronized against concurrent access by multiple

    63   * threads. Threads that need to access a single Reference concurrently should

    64   * synchronize amongst themselves and provide the necessary locking.

    65   *

    66   * @author Rosanna Lee

    67   * @author Scott Seligman

    68   *

    69   * @see RefAddr

    70   * @see StringRefAddr

    71   * @see BinaryRefAddr

    72   * @since 1.3

    73   */

    74 

    75   /*<p>

    76   * The serialized form of a Reference object consists of the class

    77   * name of the object being referenced (a String), a Vector of the

    78   * addresses (each a RefAddr), the name of the class factory (a

    79   * String), and the location of the class factory (a String).

    80 */

    81 

    82 

    83 public class Reference implements Cloneable, java.io.Serializable {

    84     /**

    85      * Contains the fully-qualified name of the class of the object to which

    86      * this Reference refers.

    87      * @serial

    88      * @see java.lang.Class#getName

    89      */

    90     protected String className;

    91     /**

    92      * Contains the addresses contained in this Reference.

    93      * Initialized by constructor.

    94      * @serial

    95      */

    96     protected Vector<RefAddr> addrs = null;

    97 

    98     /**

    99      * 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, String factoryLocation) {

   155         this(className);

   156         classFactory = factory;

   157         classFactoryLocation = factoryLocation;

   158     }

   159 

   160     /**

   161       * Constructs a new reference for an object with class name 'className',

   162       * the class name and location of the object's factory, and the address for

   163       * the object.

   164       *

   165       * @param className The non-null class name of the object to

   166       *         which this reference refers.

   167       * @param factory  The possibly null class name of the object's factory.

   168       * @param factoryLocation  The possibly null location from which

   169       *                         to load the factory (e.g. URL)

   170       * @param addr     The non-null address of the object.

   171       * @see javax.naming.spi.ObjectFactory

   172       * @see javax.naming.spi.NamingManager#getObjectInstance

   173       */

   174     public Reference(String className, RefAddr addr,

   175                      String factory, String factoryLocation) {

   176         this(className, addr);

   177         classFactory = factory;

   178         classFactoryLocation = factoryLocation;

   179     }

   180 

   181     /**

   182       * Retrieves the class name of the object to which this reference refers.

   183       *

   184       * @return The non-null fully-qualified class name of the object.

   185       *         (e.g. "java.lang.String")

   186       */

   187     public String getClassName() {

   188         return className;

   189     }

   190 

   191     /**

   192       * Retrieves the class name of the factory of the object

   193       * to which this reference refers.

   194       *

   195       * @return The possibly null fully-qualified class name of the factory.

   196       *         (e.g. "java.lang.String")

   197       */

   198     public String getFactoryClassName() {

   199         return classFactory;

   200     }

   201 

   202     /**

   203       * Retrieves the location of the factory of the object

   204       * to which this reference refers.

   205       * If it is a codebase, then it is an ordered list of URLs,

   206       * separated by spaces, listing locations from where the factory

   207       * class definition should be loaded.

   208       *

   209       * @return The possibly null string containing the

   210       *                 location for loading in the factory's class.

   211       */

   212     public String getFactoryClassLocation() {

   213         return classFactoryLocation;

   214     }

   215 

   216     /**

   217       * Retrieves the first address that has the address type 'addrType'.

   218       * String.compareTo() is used to test the equality of the address types.

   219       *

   220       * @param addrType The non-null address type for which to find the address.

   221       * @return The address in this reference with address type 'addrType';

   222       *         null if no such address exists.

   223       */

   224     public RefAddr get(String addrType) {

   225         int len = addrs.size();

   226         RefAddr addr;

   227         for (int i = 0; i < len; i++) {

   228             addr = addrs.elementAt(i);

   229             if (addr.getType().compareTo(addrType) == 0)

   230                 return addr;

   231         }

   232         return null;

   233     }

   234 

   235     /**

   236       * Retrieves the address at index posn.

   237       * @param posn The index of the address to retrieve.

   238       * @return The address at the 0-based index posn. It must be in the

   239       *         range [0,getAddressCount()).

   240       * @exception ArrayIndexOutOfBoundsException If posn not in the specified

   241       *         range.

   242       */

   243     public RefAddr get(int posn) {

   244         return addrs.elementAt(posn);

   245     }

   246 

   247     /**

   248       * Retrieves an enumeration of the addresses in this reference.

   249       * When addresses are added, changed or removed from this reference,

   250       * its effects on this enumeration are undefined.

   251       *

   252       * @return An non-null enumeration of the addresses

   253       *         ({@code RefAddr}) in this reference.

   254       *         If this reference has zero addresses, an enumeration with

   255       *         zero elements is returned.

   256       */

   257     public Enumeration<RefAddr> getAll() {

   258         return addrs.elements();

   259     }

   260 

   261     /**

   262       * Retrieves the number of addresses in this reference.

   263       *

   264       * @return The nonnegative number of addresses in this reference.

   265       */

   266     public int size() {

   267         return addrs.size();

   268     }

   269 

   270     /**

   271       * Adds an address to the end of the list of addresses.

   272       *

   273       * @param addr The non-null address to add.

   274       */

   275     public void add(RefAddr addr) {

   276         addrs.addElement(addr);

   277     }

   278 

   279     /**

   280       * Adds an address to the list of addresses at index posn.

   281       * All addresses at index posn or greater are shifted up

   282       * the list by one (away from index 0).

   283       *

   284       * @param posn The 0-based index of the list to insert addr.

   285       * @param addr The non-null address to add.

   286       * @exception ArrayIndexOutOfBoundsException If posn not in the specified

   287       *         range.

   288       */

   289     public void add(int posn, RefAddr addr) {

   290         addrs.insertElementAt(addr, posn);

   291     }

   292 

   293     /**

   294       * Deletes the address at index posn from the list of addresses.

   295       * All addresses at index greater than posn are shifted down

   296       * the list by one (towards index 0).

   297       *

   298       * @param posn The 0-based index of in address to delete.

   299       * @return The address removed.

   300       * @exception ArrayIndexOutOfBoundsException If posn not in the specified

   301       *         range.

   302       */

   303     public Object remove(int posn) {

   304         Object r = addrs.elementAt(posn);

   305         addrs.removeElementAt(posn);

   306         return r;

   307     }

   308 

   309     /**

   310       * Deletes all addresses from this reference.

   311       */

   312     public void clear() {

   313         addrs.setSize(0);

   314     }

   315 

   316     /**

   317       * Determines whether obj is a reference with the same addresses

   318       * (in same order) as this reference.

   319       * The addresses are checked using RefAddr.equals().

   320       * In addition to having the same addresses, the Reference also needs to

   321       * have the same class name as this reference.

   322       * The class factory and class factory location are not checked.

   323       * If obj is null or not an instance of Reference, null is returned.

   324       *

   325       * @param obj The possibly null object to check.

   326       * @return true if obj is equal to this reference; false otherwise.

   327       */

   328     public boolean equals(Object obj) {

   329         if ((obj != null) && (obj instanceof Reference)) {

   330             Reference target = (Reference)obj;

   331             // ignore factory information

   332             if (target.className.equals(this.className) &&

   333                 target.size() ==  this.size()) {

   334                 Enumeration<RefAddr> mycomps = getAll();

   335                 Enumeration<RefAddr> comps = target.getAll();

   336                 while (mycomps.hasMoreElements())

   337                     if (!(mycomps.nextElement().equals(comps.nextElement())))

   338                         return false;

   339                 return true;

   340             }

   341         }

   342         return false;

   343     }

   344 

   345     /**

   346       * Computes the hash code of this reference.

   347       * The hash code is the sum of the hash code of its addresses.

   348       *

   349       * @return A hash code of this reference as an int.

   350       */

   351     public int hashCode() {

   352         int hash = className.hashCode();

   353         for (Enumeration<RefAddr> e = getAll(); e.hasMoreElements();)

   354             hash += e.nextElement().hashCode();

   355         return hash;

   356     }

   357 

   358     /**

   359       * Generates the string representation of this reference.

   360       * The string consists of the class name to which this reference refers,

   361       * and the string representation of each of its addresses.

   362       * This representation is intended for display only and not to be parsed.

   363       *

   364       * @return The non-null string representation of this reference.

   365       */

   366     public String toString() {

   367         StringBuilder sb = new StringBuilder("Reference Class Name: " +

   368                                              className + "\n");

   369         int len = addrs.size();

   370         for (int i = 0; i < len; i++)

   371             sb.append(get(i).toString());

   372 

   373         return sb.toString();

   374     }

   375 

   376     /**

   377      * Makes a copy of this reference using its class name

   378      * list of addresses, class factory name and class factory location.

   379      * Changes to the newly created copy does not affect this Reference

   380      * and vice versa.

   381      */

   382     public Object clone() {

   383         Reference r = new Reference(className, classFactory, classFactoryLocation);

   384         Enumeration<RefAddr> a = getAll();

   385         r.addrs = new Vector<>();

   386 

   387         while (a.hasMoreElements())

   388             r.addrs.addElement(a.nextElement());

   389         return r;

   390     }

   391     /**

   392      * Use serialVersionUID from JNDI 1.1.1 for interoperability

   393      */

   394     private static final long serialVersionUID = -1673475790065791735L;

   395 };