net.jini.core.discovery

Class LookupLocator

java.lang.Object

net.jini.core.discovery.LookupLocator

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ConstrainableLookupLocator

public class LookupLocator
extends Object
implements Serializable

LookupLocator supports unicast discovery, using either Discovery V1 or V2 or https. Version 1 of the unicast discovery protocol is deprecated. Discovery V2 is used by default, unless otherwise set by Constraints.

It's main purpose now is to contain a url used for unicast discovery of a ServiceRegistrar, it is now immutable, since River 2.2.1, this may break overriding classes.

"jini" Unicast Discovery may be performed using any Discovery V1 or V2 provider and depending on routing and firewall rules, may be used to contact a ServiceRegistrar. The "https" scheme based Unicast Discovery is neither Discovery V1 or V2 compliant, as firewall rules and proxy servers that allow https communications are likely to prevent the handshake required to select a "jini" Discovery provider.

LookupLocator is used as a parameter in LookupLocatorDiscovery constructors. LookupLocatorDiscovery has methods to perform Discovery using either version 1 or 2 with constraints. ConstrainableLookupLocator is a subclass which uses discovery V1 or V2 and enables the use of constraints.

Since:

1.0
see net.jini.discovery.LookupLocatorDiscovery

See Also:

ConstrainableLookupLocator, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected String	host The name of the host at which to perform discovery.
protected int	port The port number on the host at which to perform discovery.

Constructor Summary

Constructors

Constructor and Description
LookupLocator(AtomicSerial.GetArg arg)
LookupLocator(String url) Construct a new LookupLocator object, set up to perform discovery to the given URL.
LookupLocator(String host, int port) Construct a new LookupLocator object, set to perform unicast discovery to the input host and port with the default "jini" scheme.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o) Two locators are equal if they have the same host and port fields.
String	getHost() Returns the name of the host that this instance should contact.
int	getPort() Returns the number of the port to which this instance should connect.
ServiceRegistrar	getRegistrar() Perform unicast discovery and return the ServiceRegistrar object for the given lookup service.
ServiceRegistrar	getRegistrar(int timeout) Perform unicast discovery and return the ServiceRegistrar object for the given lookup service, with the given discovery timeout.
protected ServiceRegistrar	getRegistrar(InvocationConstraints constraints) Perform unicast discovery and return the ServiceRegistrar object for the given lookup service, with the given constraints.
protected ServiceRegistrar	getRegistrar(InvocationConstraints constraints, Collection context) Perform unicast discovery and return the ServiceRegistrar object for the given lookup service, with the given constraints and context.
int	hashCode() Returns a hash code value calculated from the host and port field values.
String	scheme() Returns the scheme used by this LookupLocator, either traditional "jini" or "https".
String	toString() Return the string form of this LookupLocator, as a URL of scheme "jini" or "https".

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

host

protected final String host

The name of the host at which to perform discovery.

port

protected final int port

The port number on the host at which to perform discovery.

Constructor Detail

LookupLocator

public LookupLocator(String url)
              throws MalformedURLException

Construct a new LookupLocator object, set up to perform discovery to the given URL. The host and port fields will be populated with the host and port components of the input URL. No host name resolution is attempted.

The syntax of the URL must be that of a hierarchical URI with a server-based naming authority. Requirements for the components are as follows:

• A scheme of "jini" or "https" must be present.
• A server-based naming authority must be present; user-info must not be present. The port, if present, must be between 1 and 65535 (both included). If no port is specified, a default value of 4160 is used for "jini" and a default value of 443 is used for "https".
• A path if present, must be "/"; path segments must not be present.
• There must not be any other components present.

The four allowed forms of the URL are thus:

• scheme://host
• scheme://host/
• scheme://host:port
• scheme://host:port/

Parameters:

url - the URL to use

Throws:

MalformedURLException - url could not be parsed

NullPointerException - if url is null

LookupLocator

public LookupLocator(AtomicSerial.GetArg arg)
              throws IOException

Throws:

IOException

LookupLocator

public LookupLocator(String host,
                     int port)

Construct a new LookupLocator object, set to perform unicast discovery to the input host and port with the default "jini" scheme. The host and port fields will be populated with the host and port arguments. No host name resolution is attempted.

The host argument must meet any one of the following syntactical requirements:

• A host as required by a server-based naming authority in section 3.2.2 of RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax
• A literal IPv6 address as defined by RFC 2732: Format for Literal IPv6 Addresses in URL's
• A literal IPv6 address as defined by RFC 3513: Internet Protocol Version 6 (IPv6) Addressing Architecture

Parameters:

host - the name of the host to contact

port - the number of the port to connect to

Throws:

IllegalArgumentException - if port is not between 1 and 65535 (both included) or if host cannot be parsed.

NullPointerException - if host is null

Method Detail

scheme

public String scheme()

Returns the scheme used by this LookupLocator, either traditional "jini" or "https".

Returns:

scheme string.

getHost

public String getHost()

Returns the name of the host that this instance should contact. LookupLocator implements this method to return the host field.

Returns:

a String representing the host value

getPort

public int getPort()

Returns the number of the port to which this instance should connect. LookupLocator implements this method to return the port field.

Returns:

an int representing the port value

getRegistrar

public ServiceRegistrar getRegistrar()
                              throws IOException,
                                     ClassNotFoundException

Perform unicast discovery and return the ServiceRegistrar object for the given lookup service. Unicast discovery is performed anew each time this method is called. LookupLocator implements this method to simply invoke getRegistrar(int) with a timeout value, which is determined by the value of the net.jini.discovery.timeout system property. If the property is set, is not negative, and can be parsed as an Integer, the value of the property is used as the timeout value. Otherwise, a default value of 60 seconds is assumed.

Returns:

the ServiceRegistrar for the lookup service denoted by this LookupLocator object

Throws:

IOException - an error occurred during discovery

ClassNotFoundException - if a class required to unmarshal the ServiceRegistrar proxy cannot be found

getRegistrar

public ServiceRegistrar getRegistrar(int timeout)
                              throws IOException,
                                     ClassNotFoundException

Perform unicast discovery and return the ServiceRegistrar object for the given lookup service, with the given discovery timeout. Unicast discovery is performed anew each time this method is called. LookupLocator implements this method to use the values of the host and port field in determining the host and port to connect to.

If a connection can be established to start unicast discovery but the remote end fails to respond within the given time limit, an exception is thrown.

Parameters:

timeout - the maximum time to wait for a response, in milliseconds. A value of 0 specifies an infinite timeout.

Returns:

the ServiceRegistrar for the lookup service denoted by this LookupLocator object

Throws:

IOException - an error occurred during discovery

ClassNotFoundException - if a class required to unmarshal the ServiceRegistrar proxy cannot be found

IllegalArgumentException - if timeout is negative

getRegistrar

protected final ServiceRegistrar getRegistrar(InvocationConstraints constraints)
                                       throws IOException,
                                              ClassNotFoundException

Perform unicast discovery and return the ServiceRegistrar object for the given lookup service, with the given constraints. Unicast discovery is performed anew each time this method is called. LookupLocator implements this method to use the values of the host and port field in determining the host and port to connect to.

Parameters:

constraints - discovery constraints

Returns:

lookup service proxy

Throws:

IOException - an error occurred during discovery

UnsupportedConstraintException - if the discovery-related constraints contain conflicts, or otherwise cannot be processed

ClassNotFoundException - if a class required to unmarshal the ServiceRegistrar proxy cannot be found

getRegistrar

protected final ServiceRegistrar getRegistrar(InvocationConstraints constraints,
                                              Collection context)
                                       throws IOException,
                                              ClassNotFoundException

Perform unicast discovery and return the ServiceRegistrar object for the given lookup service, with the given constraints and context. Note the context may include MethodConstraints for ProxyCodebaseSpi. Unicast discovery is performed anew each time this method is called. LookupLocator implements this method to use the values of the host and port field in determining the host and port to connect to.

Parameters:

constraints - discovery constraints

context - the stream context ObjectStreamContext.getObjectStreamContext()

Returns:

lookup service proxy

Throws:

IOException - an error occurred during discovery

UnsupportedConstraintException - if the discovery-related constraints contain conflicts, or otherwise cannot be processed

ClassNotFoundException - if a class required to unmarshal the ServiceRegistrar proxy cannot be found

toString

public String toString()

Return the string form of this LookupLocator, as a URL of scheme "jini" or "https".

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Two locators are equal if they have the same host and port fields. The case of the host is ignored. Alternative forms of the same IPv6 addresses for the host value are treated as being unequal.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value calculated from the host and port field values.

Overrides:

hashCode in class Object