javax.naming: public class: Reference

javax.naming
public class: Reference [javadoc | source]

java.lang.Object
   javax.naming.Reference

All Implemented Interfaces:
Cloneable, java$io$Serializable

Direct Known Subclasses:
LinkRef

This class represents a reference to an object that is found outside of the naming/directory system.

Reference provides a way of recording address information about objects which themselves are not directly bound to the naming/directory system.

A Reference consists of an ordered list of addresses and class information about the object being referenced. Each address in the list identifies a communications endpoint for the same conceptual object. The "communications endpoint" is information that indicates how to contact the object. It could be, for example, a network address, a location in memory on the local machine, another process on the same machine, etc. The order of the addresses in the list may be of significance to object factories that interpret the reference.

Multiple addresses may arise for various reasons, such as replication or the object offering interfaces over more than one communication mechanism. The addresses are indexed starting with zero.

A Reference also contains information to assist in creating an instance of the object to which this Reference refers. It contains the class name of that object, and the class name and location of the factory to be used to create the object. The class factory location is a space-separated list of URLs representing the class path used to load the factory. When the factory class (or any class or resource upon which it depends) needs to be loaded, each URL is used (in order) to attempt to load the class.

A Reference instance is not synchronized against concurrent access by multiple threads. Threads that need to access a single Reference concurrently should synchronize amongst themselves and provide the necessary locking.

Also see:

RefAddr

StringRefAddr

BinaryRefAddr

author: Rosanna - Lee

author: Scott - Seligman

since: 1.3 -

Field Summary
protected String	className	Contains the fully-qualified name of the class of the object to which this Reference refers. Also see: java.lang.Class#getName serial:
protected Vector<RefAddr>	addrs	Contains the addresses contained in this Reference. Initialized by constructor. serial:
protected String	classFactory	Contains the name of the factory class for creating an instance of the object to which this Reference refers. Initialized to null. serial:
protected String	classFactoryLocation	Contains the location of the factory class. Initialized to null. serial:

Constructor:

Constructor:
public Reference(String className) { this.className = className; addrs = new Vector(); } Constructs a new reference for an object with class name 'className'. Class factory and class factory location are set to null. The newly created reference contains zero addresses. Parameters: `className` - The non-null class name of the object to which this reference refers.
public Reference(String className, RefAddr addr) { this.className = className; addrs = new Vector(); addrs.addElement(addr); } Constructs a new reference for an object with class name 'className' and an address. Class factory and class factory location are set to null. Parameters: `className` - The non-null class name of the object to which this reference refers. `addr` - The non-null address of the object.
public Reference(String className, String factory, String factoryLocation) { this(className); classFactory = factory; classFactoryLocation = factoryLocation; } Constructs a new reference for an object with class name 'className', and the class name and location of the object's factory. Parameters: `className` - The non-null class name of the object to which this reference refers. `factory` - The possibly null class name of the object's factory. `factoryLocation` - The possibly null location from which to load the factory (e.g. URL) Also see: javax.naming.spi.ObjectFactory javax.naming.spi.NamingManager#getObjectInstance
public Reference(String className, RefAddr addr, String factory, String factoryLocation) { this(className, addr); classFactory = factory; classFactoryLocation = factoryLocation; } Constructs a new reference for an object with class name 'className', the class name and location of the object's factory, and the address for the object. Parameters: `className` - The non-null class name of the object to which this reference refers. `factory` - The possibly null class name of the object's factory. `factoryLocation` - The possibly null location from which to load the factory (e.g. URL) `addr` - The non-null address of the object. Also see: javax.naming.spi.ObjectFactory javax.naming.spi.NamingManager#getObjectInstance

 public Reference(String className) {
        this.className  = className;
        addrs = new Vector();
}

Constructs a new reference for an object with class name 'className'. Class factory and class factory location are set to null. The newly created reference contains zero addresses.

Parameters:

className - The non-null class name of the object to which this reference refers.

 public Reference(String className,
    RefAddr addr) {
        this.className = className;
        addrs = new Vector();
        addrs.addElement(addr);
}

Constructs a new reference for an object with class name 'className' and an address. Class factory and class factory location are set to null.

Parameters:

className - The non-null class name of the object to which this reference refers.

addr - The non-null address of the object.

 public Reference(String className,
    String factory,
    String factoryLocation) {
        this(className);
        classFactory = factory;
        classFactoryLocation = factoryLocation;
}

Constructs a new reference for an object with class name 'className', and the class name and location of the object's factory.

Parameters:

className - The non-null class name of the object to which this reference refers.

factory - The possibly null class name of the object's factory.

factoryLocation - The possibly null location from which to load the factory (e.g. URL)

Also see:

javax.naming.spi.ObjectFactory

javax.naming.spi.NamingManager#getObjectInstance

 public Reference(String className,
    RefAddr addr,
    String factory,
    String factoryLocation) {
        this(className, addr);
        classFactory = factory;
        classFactoryLocation = factoryLocation;
}

Constructs a new reference for an object with class name 'className', the class name and location of the object's factory, and the address for the object.

Parameters:

className - The non-null class name of the object to which this reference refers.

factory - The possibly null class name of the object's factory.

factoryLocation - The possibly null location from which to load the factory (e.g. URL)

addr - The non-null address of the object.

Also see:

javax.naming.spi.ObjectFactory

javax.naming.spi.NamingManager#getObjectInstance

Method from javax.naming.Reference Summary:
add, add, clear, clone, equals, get, get, getAll, getClassName, getFactoryClassLocation, getFactoryClassName, hashCode, remove, size, toString

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from javax.naming.Reference Detail:
public void add(RefAddr addr) { addrs.addElement(addr); } Adds an address to the end of the list of addresses.
public void add(int posn, RefAddr addr) { addrs.insertElementAt(addr, posn); } Adds an address to the list of addresses at index posn. All addresses at index posn or greater are shifted up the list by one (away from index 0).
public void clear() { addrs.setSize(0); } Deletes all addresses from this reference.
public Object clone() { Reference r = new Reference(className, classFactory, classFactoryLocation); Enumeration< RefAddr > a = getAll(); r.addrs = new Vector(); while (a.hasMoreElements()) r.addrs.addElement(a.nextElement()); return r; } Makes a copy of this reference using its class name list of addresses, class factory name and class factory location. Changes to the newly created copy does not affect this Reference and vice versa.
public boolean equals(Object obj) { if ((obj != null) && (obj instanceof Reference)) { Reference target = (Reference)obj; // ignore factory information if (target.className.equals(this.className) && target.size() == this.size()) { Enumeration mycomps = getAll(); Enumeration comps = target.getAll(); while (mycomps.hasMoreElements()) if (!(mycomps.nextElement().equals(comps.nextElement()))) return false; return true; } } return false; } Determines whether obj is a reference with the same addresses (in same order) as this reference. The addresses are checked using RefAddr.equals(). In addition to having the same addresses, the Reference also needs to have the same class name as this reference. The class factory and class factory location are not checked. If obj is null or not an instance of Reference, null is returned.
public RefAddr get(String addrType) { int len = addrs.size(); RefAddr addr; for (int i = 0; i < len; i++) { addr = (RefAddr) addrs.elementAt(i); if (addr.getType().compareTo(addrType) == 0) return addr; } return null; } Retrieves the first address that has the address type 'addrType'. String.compareTo() is used to test the equality of the address types.
public RefAddr get(int posn) { return ((RefAddr) addrs.elementAt(posn)); } Retrieves the address at index posn.
public Enumeration<RefAddr> getAll() { return addrs.elements(); } Retrieves an enumeration of the addresses in this reference. When addresses are added, changed or removed from this reference, its effects on this enumeration are undefined.
public String getClassName() { return className; } Retrieves the class name of the object to which this reference refers.
public String getFactoryClassLocation() { return classFactoryLocation; } Retrieves the location of the factory of the object to which this reference refers. If it is a codebase, then it is an ordered list of URLs, separated by spaces, listing locations from where the factory class definition should be loaded.
public String getFactoryClassName() { return classFactory; } Retrieves the class name of the factory of the object to which this reference refers.
public int hashCode() { int hash = className.hashCode(); for (Enumeration e = getAll(); e.hasMoreElements();) hash += e.nextElement().hashCode(); return hash; } Computes the hash code of this reference. The hash code is the sum of the hash code of its addresses.
public Object remove(int posn) { Object r = addrs.elementAt(posn); addrs.removeElementAt(posn); return r; } Deletes the address at index posn from the list of addresses. All addresses at index greater than posn are shifted down the list by one (towards index 0).
public int size() { return addrs.size(); } Retrieves the number of addresses in this reference.
public String toString() { StringBuffer buf = new StringBuffer("Reference Class Name: " + className + "\n"); int len = addrs.size(); for (int i = 0; i < len; i++) buf.append(get(i).toString()); return buf.toString(); } Generates the string representation of this reference. The string consists of the class name to which this reference refers, and the string representation of each of its addresses. This representation is intended for display only and not to be parsed.

Method from javax.naming.Reference Detail:

 public  void add(RefAddr addr) {
        addrs.addElement(addr);
}

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

 public  void add(int posn,
    RefAddr addr) {
        addrs.insertElementAt(addr, posn);
}

Adds an address to the list of addresses at index posn. All addresses at index posn or greater are shifted up the list by one (away from index 0).

 public  void clear() {
        addrs.setSize(0);
}

Deletes all addresses from this reference.

 public Object clone() {
        Reference r = new Reference(className, classFactory, classFactoryLocation);
        Enumeration< RefAddr > a = getAll();
        r.addrs = new Vector();
        while (a.hasMoreElements())
            r.addrs.addElement(a.nextElement());
        return r;
}

Makes a copy of this reference using its class name list of addresses, class factory name and class factory location. Changes to the newly created copy does not affect this Reference and vice versa.

 public boolean equals(Object obj) {
        if ((obj != null) && (obj instanceof Reference)) {
            Reference target = (Reference)obj;
            // ignore factory information
            if (target.className.equals(this.className) &&
                target.size() ==  this.size()) {
                Enumeration mycomps = getAll();
                Enumeration comps = target.getAll();
                while (mycomps.hasMoreElements())
                    if (!(mycomps.nextElement().equals(comps.nextElement())))
                        return false;
                return true;
            }
        }
        return false;
}

Determines whether obj is a reference with the same addresses (in same order) as this reference. The addresses are checked using RefAddr.equals(). In addition to having the same addresses, the Reference also needs to have the same class name as this reference. The class factory and class factory location are not checked. If obj is null or not an instance of Reference, null is returned.

 public RefAddr get(String addrType) {
        int len = addrs.size();
        RefAddr addr;
        for (int i = 0; i <  len; i++) {
            addr = (RefAddr) addrs.elementAt(i);
            if (addr.getType().compareTo(addrType) == 0)
                return addr;
        }
        return null;
}

Retrieves the first address that has the address type 'addrType'. String.compareTo() is used to test the equality of the address types.

 public RefAddr get(int posn) {
        return ((RefAddr) addrs.elementAt(posn));
}

Retrieves the address at index posn.

 public Enumeration<RefAddr> getAll() {
        return addrs.elements();
}

Retrieves an enumeration of the addresses in this reference. When addresses are added, changed or removed from this reference, its effects on this enumeration are undefined.

 public String getClassName() {
        return className;
}

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

 public String getFactoryClassLocation() {
        return classFactoryLocation;
}

Retrieves the location of the factory of the object to which this reference refers. If it is a codebase, then it is an ordered list of URLs, separated by spaces, listing locations from where the factory class definition should be loaded.

 public String getFactoryClassName() {
        return classFactory;
}

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

 public int hashCode() {
        int hash = className.hashCode();
        for (Enumeration e = getAll(); e.hasMoreElements();)
            hash += e.nextElement().hashCode();
        return hash;
}

Computes the hash code of this reference. The hash code is the sum of the hash code of its addresses.

 public Object remove(int posn) {
        Object r = addrs.elementAt(posn);
        addrs.removeElementAt(posn);
        return r;
}

Deletes the address at index posn from the list of addresses. All addresses at index greater than posn are shifted down the list by one (towards index 0).

 public int size() {
        return addrs.size();
}

Retrieves the number of addresses in this reference.

 public String toString() {
        StringBuffer buf = new StringBuffer("Reference Class Name: " +
                                            className + "\n");
        int len = addrs.size();
        for (int i = 0; i <  len; i++)
            buf.append(get(i).toString());
        return buf.toString();
}

Generates the string representation of this reference. The string consists of the class name to which this reference refers, and the string representation of each of its addresses. This representation is intended for display only and not to be parsed.