com.artima.place
Class UnicastDiscoveryLink

java.lang.Object
  |
  +--com.artima.place.UnicastDiscoveryLink

All Implemented Interfaces:

Link, ProgressEventGenerator, java.io.Serializable

public final class UnicastDiscoveryLink

extends java.lang.Object

implements Link, ProgressEventGenerator

Represents a unicast discovery-based link to a Jini service on the network. Clients may specify one to many host and port locations at which this link will attempt unicast discovery.

If multiple server addresses are specified when constructing the UnicastDiscoveryLink, the UnicastDiscoveryLink may when activated attempt unicast discovery of multiple lookup services. If the specified approach is either ORDERED_SEQUENTIAL or RANDOM_SEQUENTIAL, then multiple attempts will occur sequentially, via LookupLocator objects. If the specified approach is ORDERED_SEQUENTIAL, this object will attempt to contact lookup services in the order they appear in the passed ServerAddress array. If the specified approach is RANDOM_SEQUENTIAL, this object will attempt to contact lookup services in a random order selected each time the link is activated. When an attempt at unicast discovery fails or times out, the activation will attempt to contact the next server address on the list. The first successful discovery that, upon lookup with the specified ServiceTemplate, yields a match causes the link activation to successfully terminate. By randomizing the list of server addresses at which to attempt unicast discovery, this link can help achieve a kind of load balancing.

If multiple server addresses are specified with an approach of CONCURRENTLY, then when this link is activated it will use a LookupLocatorDiscovery object to concurrently attempt to contact via unicast discovery all the specified server addresses. The first successful discovery that, upon lookup with the specified ServiceTemplate, yields a match causes the link activation to successfully terminate.

See Also:

Serialized Form

Field Summary

static int	CONCURRENTLY Constant that when passed to certain constructors indicates that a LookupLocatorDiscovery object will be used to concurrently attempt to contact all ServerAddresses in the passed list.
static int	ORDERED_SEQUENTIAL Constant that when passed to certain constructors indicates that LookupLocators for a list of ServerAddresses will be tried sequentially in the order they appear in the list.
static int	RANDOM_SEQUENTIAL Constant that when passed to certain constructors indicates that LookupLocators for a list of ServerAddresses will be tried sequentially in a random order chosen each time the link is activated.

Constructor Summary

UnicastDiscoveryLink(ServerAddress[] serverAddresses, net.jini.core.lookup.ServiceTemplate template, int approach)
Construct a UnicastDiscoveryLink with an array of ServerAddress objects and a ServiceTemplate.

UnicastDiscoveryLink(ServerAddress serverAddress, net.jini.core.lookup.ServiceTemplate template)
Construct a UnicastDiscoveryLink with a ServerAddress and ServiceTemplate.

UnicastDiscoveryLink(java.lang.String host, net.jini.core.lookup.ServiceTemplate template)
Construct a UnicastDiscoveryLink with a host String and ServiceTemplate.

UnicastDiscoveryLink(URLString[] urls, net.jini.core.lookup.ServiceTemplate template, int approach)
Construct a UnicastDiscoveryLink with an array of URLStrings and a ServiceTemplate.

UnicastDiscoveryLink(URLString url, net.jini.core.lookup.ServiceTemplate template)
Construct a UnicastDiscoveryLink with a URLString and ServiceTemplate.

Method Summary

void	addProgressListener(ProgressListener listener) Adds the specified ProgressListener to receive progress events from this object.
int	getApproach() Returns the approach used by this UnicastDiscoveryLink, which will be one of ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY.
ServerAddress[]	getServerAddresses() Returns the array of ServerAddress objects which determine the hosts and ports at which unicast discovery will be attempted by this link's activate method.
net.jini.core.lookup.ServiceTemplate	getServiceTemplate() Returns the ServiceTemplate with which lookups will be performed by this UnicastDiscoveryLink.
void	removeProgressListener(ProgressListener listener) Removes the specified ProgressListener so that it no longer receives progress events from this object.
net.jini.core.lookup.ServiceItem	retrieveService() Activate this link by attempting unicast discovery of lookup services identified in the ServerAddresses array using the specified approach, ultimately performing lookups at discovered lookup services with the specified ServiceTemplate.
void	stopRetrieval() Requests a retrieval to stop.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ORDERED_SEQUENTIAL

public static final int ORDERED_SEQUENTIAL

Constant that when passed to certain constructors indicates that LookupLocators for a list of ServerAddresses will be tried sequentially in the order they appear in the list.

RANDOM_SEQUENTIAL

public static final int RANDOM_SEQUENTIAL

Constant that when passed to certain constructors indicates that LookupLocators for a list of ServerAddresses will be tried sequentially in a random order chosen each time the link is activated.

CONCURRENTLY

public static final int CONCURRENTLY

Constant that when passed to certain constructors indicates that a LookupLocatorDiscovery object will be used to concurrently attempt to contact all ServerAddresses in the passed list.

Constructor Detail

UnicastDiscoveryLink

public UnicastDiscoveryLink(URLString url,
                            net.jini.core.lookup.ServiceTemplate template)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException

Construct a UnicastDiscoveryLink with a URLString and ServiceTemplate. The URL must be a jini: URL that identifies a Jini lookup service, with the form jini://host/ or jini://host:port/.

Parameters:

url - the URL at which this link will perform unicast discovery when activated

template - the ServiceTemplate with which to peform lookups when this link is activated

Throws:

NullPointerException - if either of passed url or template references are null

java.lang.IllegalArgumentException - if the passed url is not a valid jini: URL

java.io.IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

java.lang.ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

UnicastDiscoveryLink

public UnicastDiscoveryLink(URLString[] urls,
                            net.jini.core.lookup.ServiceTemplate template,
                            int approach)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException

Construct a UnicastDiscoveryLink with an array of URLStrings and a ServiceTemplate. Each URL must be a jini: URL that identifies a Jini lookup service, with the form jini://host/ or jini://host:port/.

Parameters:

urls - the URLs at which this link will perform unicast discovery when activated

template - the ServiceTemplate with which to peform lookups when this link is activated

approach - the approach (either ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY) to use when contacting lookup services when this link is activated.

Throws:

NullPointerException - if either of passed urls or template references are null

java.lang.IllegalArgumentException - if the passed urls is a zero length array or contains any URLs that aren't valid jini: URL, or if the int passed as approach isn't one of ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY.

java.io.IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

java.lang.ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

UnicastDiscoveryLink

public UnicastDiscoveryLink(java.lang.String host,
                            net.jini.core.lookup.ServiceTemplate template)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException

Construct a UnicastDiscoveryLink with a host String and ServiceTemplate. This object's activate method will perform unicast discovery at the default port (4160) of the passed host, and perform a query on the resulting lookup service using the passed ServiceTemplate.

Parameters:

host - the host at which to perform unicast discovery at the default port when this link is activated.

template - the ServiceTemplate with which to peform lookups when this link is activated

Throws:

NullPointerException - if either of passed host or template references are null

java.lang.IllegalArgumentException - if the passed host is not a valid host name, as determined by the isValidHost method of class ServerAddress

java.io.IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

java.lang.ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

UnicastDiscoveryLink

public UnicastDiscoveryLink(ServerAddress serverAddress,
                            net.jini.core.lookup.ServiceTemplate template)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException

Construct a UnicastDiscoveryLink with a ServerAddress and ServiceTemplate. This object's activate method will perform unicast discovery at the host and port specified by the passed ServerAddress, and perform a query on the resulting lookup service using the passed ServiceTemplate.

Parameters:

serverAddress - the server address (host and port) at which to perform unicast discovery when this link is activated.

template - the ServiceTemplate with which to peform lookups when this link is activated

Throws:

NullPointerException - if either of passed serverAddress ortemplate references are null

java.lang.IllegalArgumentException - if the passed host is not a valid host name, as determined by the isValidHost method of class ServerAddress

java.io.IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

java.lang.ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

UnicastDiscoveryLink

public UnicastDiscoveryLink(ServerAddress[] serverAddresses,
                            net.jini.core.lookup.ServiceTemplate template,
                            int approach)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException

Construct a UnicastDiscoveryLink with an array of ServerAddress objects and a ServiceTemplate.

This object's activate method will attempt to perform unicast discovery at each host and port specified in the passed ServerAddress array, in order of appearance in the array. The activate method will perform a query on the each resulting lookup service using the passed ServiceTemplate. The first match that is found will be passed to the ActivationClient. If multiple matches are found, a random match will be returned. If a lookup service is not able to be contacted within a timeout determined by this class, the next ServerAddress on the list will be tried. Only after all ServerAddresses have either yielded no match when the query was performed, or were not contactable within the timeout, will the activate method notify the ActivationClient that the activation failed.

Parameters:

serverAddress - the server addresses (hosts and ports) at which to perform unicast discovery when this link is activated.

template - the ServiceTemplate with which to peform lookups when this link is activated

approach - the approach (either ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY) to use when contacting lookup services when this link is activated.

Throws:

NullPointerException - if either of passed serverAddresses or template references are null

java.lang.IllegalArgumentException - if the passed serverAddresses array is empty, or if the int passed as approach isn't one of ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY.

java.io.IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

java.lang.ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

Method Detail

retrieveService

public net.jini.core.lookup.ServiceItem retrieveService()
                                                 throws java.rmi.RemoteException,
                                                        StoppedException

Activate this link by attempting unicast discovery of lookup services identified in the ServerAddresses array using the specified approach, ultimately performing lookups at discovered lookup services with the specified ServiceTemplate. The activate method will return promptly, returning a LinkActivation object that enables the client to abort the activation. Invoking activate again while an activation is currently in progress just starts a new activation independent of the already running one.

Specified by:

retrieveService in interface Link

Returns:

the ServiceItem the retrieved service item

Throws:

RemoteException - to indicate a failure in retrieving the service

StoppedException - to indicate that the request was stopped

stopRetrieval

public void stopRetrieval()

Description copied from interface: Link

Requests a retrieval to stop. If the retrieval is still progressing, and has not previously succeeded, failed, or been stopped, then the retrieval will stop. Otherwise, invoking stopRetrival() has no effect. The stopRetrieval() method does not throw an exception to indicate the activation has already succeeded, failed, or been aborted, but returns normally in these cases.

Specified by:

stopRetrieval in interface Link

getServerAddresses

public ServerAddress[] getServerAddresses()

Returns the array of ServerAddress objects which determine the hosts and ports at which unicast discovery will be attempted by this link's activate method.

Returns:

the ServerAddress objects that define the hosts and port at which unicast unicast discovery will be attempted by this link when it is activated.

getServiceTemplate

public net.jini.core.lookup.ServiceTemplate getServiceTemplate()
                                                        throws java.io.IOException,
                                                               java.lang.ClassNotFoundException

Returns the ServiceTemplate with which lookups will be performed by this UnicastDiscoveryLink.

Returns:

a duplicate of the ServiceTemplate used by this link when activated

Throws:

java.io.IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

java.lang.ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

getApproach

public int getApproach()

Returns the approach used by this UnicastDiscoveryLink, which will be one of ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY.

Returns:

the approach used by this link when activated.

addProgressListener

public void addProgressListener(ProgressListener listener)

Adds the specified ProgressListener to receive progress events from this object. If listener is null, no exception is thrown and no action is performed.

Specified by:

addProgressListener in interface ProgressEventGenerator

Parameters:

listener - the ProgressListener to add

removeProgressListener

public void removeProgressListener(ProgressListener listener)

Removes the specified ProgressListener so that it no longer receives progress events from this object. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to this object. If listener is null, no exception is thrown and no action is performed.

Specified by:

removeProgressListener in interface ProgressEventGenerator

Parameters:

listener - the ProgressListener to remove