org.tm4j.net
Interface Locator

All Known Subinterfaces:

FPILocator, URILocator

All Known Implementing Classes:

LocatorAdapter, LocatorBase

public interface Locator

The interface to be supported by all classes implementing resolvable addresses in TM4J. A locator may be absolute or relative, and it may be resolved relative to another locator.Each locator consists of the following components:

• A notation, defined by a String. It is accessible via the getNotation() method.
• An address, also defined by a String. It is accessible via the getAddress() method.

Classes implementing Locator are usually not instantiated directly — you should resort to using LocatorFactory.createLocator(java.lang.String, java.lang.String) instead. Classes implementing Locator should ensure that they provide a constructor of the signature (LocatorFactory, String, String) to allow for proper locator creation on the factory's part. LocatorBase provides such a constructor, so it's generally a good idea to extend that class rather than implement Locator directly.

Since:

0.6.0

Author:

Kal Ahmed

See Also:

LocatorBase.LocatorBase(LocatorFactory, String, String)

Method Summary

Locator	copy() Returns a copy of this object.
boolean	equals(Locator loc) Determines the equality of this Locator to loc:
java.lang.String	getAddress() Gets the address associated with the locator
LocatorFactory	getFactory() Returns the locator factory associated with this locator.
java.lang.String	getNotation() Gets the string defining the notation type of this locator
int	hashCode() Returns the Locator's object hashcode.
void	initialise(java.lang.String notation, java.lang.String address) Initializes the locator with the specified notation and address.
Locator	resolveRelative(Locator rel) Returns a new Locator whose address is the result of resolving the specified Locator relative to this Locator.
Locator	resolveRelative(java.lang.String rel) Returns a new Locator whose address is the result of resolvng the specified relative address string relative to this Locator.
void	setFactory(LocatorFactory factory) Associates the locator with the given factory.

Method Detail

initialise

public void initialise(java.lang.String notation,
                       java.lang.String address)
                throws MalformedLocatorException,
                       InvalidNotationException

Initializes the locator with the specified notation and address. This method is commonly called by constructors.

Parameters:

notation - the notation to be used for this locator.

address - the address to be defined by this locator.

Throws:

MalformedLocatorException - if the implementation failed to parse the given address.

InvalidNotationException - if the implementation does not support the specified notation type.

getFactory

public LocatorFactory getFactory()

Returns the locator factory associated with this locator.

Returns:

The locator factory that created this locator.

setFactory

public void setFactory(LocatorFactory factory)

Associates the locator with the given factory. Applications should ensure that this method is not invoked directly, except by factory classes implementing LocatorFactory.

Parameters:

factory - the factory to be associated with the locator.

getAddress

public java.lang.String getAddress()

Gets the address associated with the locator

Returns:

The address associated with the locator.

getNotation

public java.lang.String getNotation()

Gets the string defining the notation type of this locator

Returns:

The notation type of the locator.

resolveRelative

public Locator resolveRelative(Locator rel)
                        throws LocatorResolutionException

Returns a new Locator whose address is the result of resolving the specified Locator relative to this Locator.

Parameters:

rel - The Locator to be resolved relative to this locator.

Throws:

LocatorResolutionException - if the locator could not be resolved.

resolveRelative

public Locator resolveRelative(java.lang.String rel)
                        throws LocatorResolutionException

Returns a new Locator whose address is the result of resolvng the specified relative address string relative to this Locator.

Parameters:

rel - The address string to be resolve relative to this locator.

Throws:

LocatorResolutionException - if the locator could not be resolved.

equals

public boolean equals(Locator loc)

Determines the equality of this Locator to loc:

Returns:

true if the inplementation determines the two locators to be equal, false otherwise.

hashCode

public int hashCode()

Returns the Locator's object hashcode.

Returns:

The object hash code.

copy

public Locator copy()
             throws LocatorFactoryException

Returns a copy of this object.

Returns:

A copy of this Locator, i.e. one that is identical, in address and notation, to the original locator.

Throws:

LocatorFactoryException - if the associated locator factory failed to create the copy.