APIdia Launch Partner
Top Description Fields Constructors Methods
javax.naming

public Class Reference

extends Object
implements Cloneable, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.lang.Cloneable
Known Direct Subclasses
javax.naming.LinkRef
Imports
java.util.Vector, .Enumeration
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.

Authors
Rosanna Lee, Scott Seligman
Since
1.3
See Also
RefAddr, StringRefAddr, BinaryRefAddr

Field Summary

Modifier and TypeField and Description
protected Vector<RefAddr>
addrs

Contains the addresses contained in this Reference.

protected String
classFactory

Contains the name of the factory class for creating an instance of the object to which this Reference refers.

protected String
classFactoryLocation

Contains the location of the factory class.

protected String
className

Contains the fully-qualified name of the class of the object to which this Reference refers.

private static final long
serialVersionUID

Use serialVersionUID from JNDI 1.1.1 for interoperability

Constructor Summary

AccessConstructor and Description
public
Reference(String
The non-null class name of the object to which this reference refers.
className)

Constructs a new reference for an object with class name 'className'.

public
Reference(String
The non-null class name of the object to which this reference refers.
className, RefAddr
The non-null address of the object.
addr)

Constructs a new reference for an object with class name 'className' and an address.

public
Reference(String
The non-null class name of the object to which this reference refers.
className, String
The possibly null class name of the object's factory.
factory, String
The possibly null location from which to load the factory (e.g. URL)
factoryLocation)

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

public
Reference(String
The non-null class name of the object to which this reference refers.
className, RefAddr
The non-null address of the object.
addr, String
The possibly null class name of the object's factory.
factory, String
The possibly null location from which to load the factory (e.g. URL)
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.

Method Summary

Modifier and TypeMethod and Description
public void
add(RefAddr
The non-null address to add.
addr)

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

public void
add(int
The 0-based index of the list to insert addr.
posn, RefAddr
The non-null address to add.
addr)

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

public void
clear()

Deletes all addresses from this reference.

public Object
clone()

Overrides java.lang.Object.clone.

Makes a copy of this reference using its class name list of addresses, class factory name and class factory location.

public boolean

Returns:

true if obj is equal to this reference; false otherwise.
equals(Object
The possibly null object to check.
obj)

Overrides java.lang.Object.equals.

Determines whether obj is a reference with the same addresses (in same order) as this reference.

public RefAddr

Returns:

The address in this reference with address type 'addrType'; null if no such address exists.
get(String
The non-null address type for which to find the address.
addrType)

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

public RefAddr

Returns:

The address at the 0-based index posn. It must be in the range [0,getAddressCount()).
get(int
The index of the address to retrieve.
posn)

Retrieves the address at index posn.

public Enumeration<RefAddr>

Returns:

An non-null enumeration of the addresses (RefAddr) in this reference. If this reference has zero addresses, an enumeration with zero elements is returned.
getAll()

Retrieves an enumeration of the addresses in this reference.

public String

Returns:

The non-null fully-qualified class name of the object. (e.g. "java.lang.String")
getClassName()

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

public String

Returns:

The possibly null string containing the location for loading in the factory's class.
getFactoryClassLocation()

Retrieves the location of the factory of the object to which this reference refers.

public String

Returns:

The possibly null fully-qualified class name of the factory. (e.g. "java.lang.String")
getFactoryClassName()

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

public int

Returns:

A hash code of this reference as an int.
hashCode()

Overrides java.lang.Object.hashCode.

Computes the hash code of this reference.

public Object

Returns:

The address removed.
remove(int
The 0-based index of in address to delete.
posn)

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

public int

Returns:

The nonnegative number of addresses in this reference.
size()

Retrieves the number of addresses in this reference.

public String

Returns:

The non-null string representation of this reference.
toString()

Overrides java.lang.Object.toString.

Generates the string representation of this reference.

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

addrsback to summary
protected Vector<RefAddr> addrs

Contains the addresses contained in this Reference. Initialized by constructor.

classFactoryback to summary
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.

classFactoryLocationback to summary
protected String classFactoryLocation

Contains the location of the factory class. Initialized to null.

classNameback to summary
protected String className

Contains the fully-qualified name of the class of the object to which this Reference refers.

See Also
java.lang.Class#getName
serialVersionUIDback to summary
private static final long serialVersionUID

Use serialVersionUID from JNDI 1.1.1 for interoperability

Constructor Detail

Referenceback to summary
public Reference(String className)

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:String

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

Referenceback to summary
public Reference(String className, RefAddr 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:String

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

addr:RefAddr

The non-null address of the object.

Referenceback to summary
public Reference(String className, String factory, String 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:String

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

factory:String

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

factoryLocation:String

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

See Also
javax.naming.spi.ObjectFactory, javax.naming.spi.NamingManager#getObjectInstance
Referenceback to summary
public Reference(String className, RefAddr addr, String factory, String 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:String

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

addr:RefAddr

The non-null address of the object.

factory:String

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

factoryLocation:String

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

See Also
javax.naming.spi.ObjectFactory, javax.naming.spi.NamingManager#getObjectInstance

Method Detail

addback to summary
public void add(RefAddr addr)

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

Parameters
addr:RefAddr

The non-null address to add.

addback to summary
public void add(int posn, RefAddr addr)

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).

Parameters
posn:int

The 0-based index of the list to insert addr.

addr:RefAddr

The non-null address to add.

Exceptions
ArrayIndexOutOfBoundsException:
If posn not in the specified range.
clearback to summary
public void clear()

Deletes all addresses from this reference.

cloneback to summary
public Object clone()

Overrides java.lang.Object.clone.

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.

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

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.

Parameters
obj:Object

The possibly null object to check.

Returns:boolean

true if obj is equal to this reference; false otherwise.

getback to summary
public RefAddr get(String addrType)

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

Parameters
addrType:String

The non-null address type for which to find the address.

Returns:RefAddr

The address in this reference with address type 'addrType'; null if no such address exists.

getback to summary
public RefAddr get(int posn)

Retrieves the address at index posn.

Parameters
posn:int

The index of the address to retrieve.

Returns:RefAddr

The address at the 0-based index posn. It must be in the range [0,getAddressCount()).

Exceptions
ArrayIndexOutOfBoundsException:
If posn not in the specified range.
getAllback to summary
public Enumeration<RefAddr> getAll()

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.

Returns:Enumeration<RefAddr>

An non-null enumeration of the addresses (RefAddr) in this reference. If this reference has zero addresses, an enumeration with zero elements is returned.

getClassNameback to summary
public String getClassName()

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

Returns:String

The non-null fully-qualified class name of the object. (e.g. "java.lang.String")

getFactoryClassLocationback to summary
public String getFactoryClassLocation()

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.

Returns:String

The possibly null string containing the location for loading in the factory's class.

getFactoryClassNameback to summary
public String getFactoryClassName()

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

Returns:String

The possibly null fully-qualified class name of the factory. (e.g. "java.lang.String")

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

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

Returns:int

A hash code of this reference as an int.

removeback to summary
public Object remove(int posn)

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).

Parameters
posn:int

The 0-based index of in address to delete.

Returns:Object

The address removed.

Exceptions
ArrayIndexOutOfBoundsException:
If posn not in the specified range.
sizeback to summary
public int size()

Retrieves the number of addresses in this reference.

Returns:int

The nonnegative number of addresses in this reference.

toStringback to summary
public String toString()

Overrides java.lang.Object.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.

Returns:String

The non-null string representation of this reference.