org.talend.esb.servicelocator.client

Interface ServiceLocator

All Known Implementing Classes:

ServiceLocatorImpl

public interface ServiceLocator

This is the entry point for clients of the Service Locator. To access the Service Locator clients have to first connect to the Service Locator to get a session assigned at the server. Once the connection is established the client will periodically send heart beats to the server to keep the session alive. The session gets invalidated if the client is destroyed, disconnected, or fails to successfully send the heart beat for a period of time defined by the session timeout parameter.

The Service Locator provides the following operations.

• Register an endpoint for a specific service. If registered as non persistent an endpoint is marked live as long as the session of this client is alive or it is explicitly unregistered. If registered as persistent the endpoint is marked live until the endpoint is explicitly unregistered.
• Unregister an endpoint for a specific service. The endpoint is marked as non live, but still in the list of all endpoints for a service.
• Remove an endpoint for a specific service. The endpoint is removed from the list of endpoints for the given service.
• Look up all live endpoints for a specific service that were registered before by other clients.
• All services for which an endpoint was ever registered can be retrieved.
• For a specific service all endpoints that were ever registered can be retrieved whether they are currently live or not.

To ensure that all available endpoints are re-registered when the client reconnects after a session expired a ServiceLocator.PostConnectAction should be set that registers all endpoints again and so marks them as live.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ServiceLocator.PostConnectAction Callback interface to define actions that must be executed after a successful connect or reconnect.

Method Summary

Methods

Modifier and Type	Method and Description
void	connect() Establish a connection to the Service Locator.
void	disconnect() Disconnects from a Service Locator server.
SLEndpoint	getEndpoint(QName serviceName, String endpoint) Return the complete endpoint information for the given endpoint registered for the given service.
List<String>	getEndpointNames(QName serviceName) For the given service return all endpoints that currently registered at the Service Locator Service.
List<SLEndpoint>	getEndpoints(QName serviceName) Return the complete endpoint informations for all endpoints registered for the given service.
List<QName>	getServices() Return all services for which endpoints are registered at the Service Locator Service.
List<String>	lookup(QName serviceName) For the given service return all endpoints that are currently registered at the Service Locator.
List<String>	lookup(QName serviceName, SLPropertiesMatcher matcher) For the given service return all endpoints that are currently registered at the Service Locator and where the custom properties match the given matcher.
void	register(Endpoint eprProvider) For a given service register the endpoint as defined in the given EndpointProvider.
void	register(Endpoint eprProvider, boolean persistent) For a given service register the endpoint as defined in the given EndpointProvider.
void	register(QName serviceName, String endpoint) For a given service register the endpoint of a concrete provider of this service.
void	register(QName serviceName, String endpoint, boolean persistent)
void	register(QName serviceName, String endpoint, SLProperties properties) For a given service register the endpoint of a concrete provider of this service.
void	register(QName serviceName, String endpoint, SLProperties properties, boolean persistent)
void	removeEndpoint(QName serviceName, String endpoint) Remove the given endpoint from the list of endpoints of the given service.
void	setPostConnectAction(ServiceLocator.PostConnectAction postConnectAction) Specify the action to be be executed after the Service Locator has connected to the server.
void	unregister(Endpoint epProvider) For a given service unregister a previously registered endpoint.
void	unregister(QName serviceName, String endpoint) For a given service unregister a previously registered endpoint.
void	updateTimetolive(QName serviceName, String endpoint, int timetolive) Updates the time-to-live (ttl) for specified endpoint.

Method Detail

connect

void connect()
             throws InterruptedException,
                    ServiceLocatorException

Establish a connection to the Service Locator. After successful connection the specified ServiceLocator.PostConnectAction is run. If the session to the server expires because the server could not be reached within the specified time, a reconnect is automatically executed as soon as the server can be reached again. Because after a session time out all registered endpoints are removed it is important to specify a ServiceLocator.PostConnectAction that re-registers all endpoints.

Throws:

InterruptedException - the current Thread was interrupted when waiting for a successful connection to the ServiceLocator

ServiceLocatorException - the connect operation failed

disconnect

void disconnect()
                throws InterruptedException,
                       ServiceLocatorException

Disconnects from a Service Locator server. All endpoints that were registered before are removed from the server. To be able to communicate with a Service Locator server again the client has to connect again.

Throws:

InterruptedException - the current Thread was interrupted when waiting for the disconnect to happen

ServiceLocatorException

register

void register(QName serviceName,
            String endpoint)
              throws ServiceLocatorException,
                     InterruptedException

For a given service register the endpoint of a concrete provider of this service. The endpoint is marked as live as long as this client is connected and the session on the server is valid.

The endpoint is categorized as being a SOAP / HTTP endpoint.

Parameters:

serviceName - the name of the service the endpoint is registered for, must not be null

endpoint - the endpoint to register, must not be null

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

register

void register(QName serviceName,
            String endpoint,
            boolean persistent)
              throws ServiceLocatorException,
                     InterruptedException

Parameters:

serviceName -

endpoint -

presistent -

Throws:

ServiceLocatorException

InterruptedException

register

void register(QName serviceName,
            String endpoint,
            SLProperties properties)
              throws ServiceLocatorException,
                     InterruptedException

For a given service register the endpoint of a concrete provider of this service. The endpoint is marked as live as long as this client is connected and the session on the server is valid. In addition a set of custom properties is defined for the endpoint. They may be used as additional selection criteria during the lookup.

Parameters:

serviceName - the name of the service the endpoint is registered for, must not be null

endpoint - the endpoint to register, must not be null

properties - custom properties of the endpoint that can be used as additional selection criteria when doing a lookup.

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

register

void register(QName serviceName,
            String endpoint,
            SLProperties properties,
            boolean persistent)
              throws ServiceLocatorException,
                     InterruptedException

Parameters:

serviceName -

endpoint -

properties -

persistent -

Throws:

ServiceLocatorException

InterruptedException

register

void register(Endpoint eprProvider)
              throws ServiceLocatorException,
                     InterruptedException

For a given service register the endpoint as defined in the given EndpointProvider. The endpoint is marked as live as long as this client is connected and the session on the server is valid.

Parameters:

eprProvider - provides all the necessary information to register an endpoint like name of the service for which to register the endpoint, the endpoint URL, must not be null.

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

register

void register(Endpoint eprProvider,
            boolean persistent)
              throws ServiceLocatorException,
                     InterruptedException

For a given service register the endpoint as defined in the given EndpointProvider. If the given persistent flag is not set the endpoint is marked as live as long as this client is connected and the session on the server is valid. Otherwise it is marked live independent of the sesion state.

Parameters:

eprProvider - provides all the necessary information to register an endpoint like name of the service for which to register the endpoint, the endpoint URL, must not be null.

persistent - iff true the endpoint is marked live until it is explicitly unregistered.

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

unregister

void unregister(QName serviceName,
              String endpoint)
                throws ServiceLocatorException,
                       InterruptedException

For a given service unregister a previously registered endpoint.

Parameters:

serviceName - the name of the service the endpoint is unregistered for, must not be null

endpoint - the endpoint to unregister, must not be null

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

unregister

void unregister(Endpoint epProvider)
                throws ServiceLocatorException,
                       InterruptedException

For a given service unregister a previously registered endpoint.

Parameters:

eprProvider - provides all the necessary information to unregister an endpoint like name of the service for which to register the endpoint and the endpoint URL, must not be null.

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

updateTimetolive

void updateTimetolive(QName serviceName,
                    String endpoint,
                    int timetolive)
                      throws ServiceLocatorException,
                             InterruptedException

Updates the time-to-live (ttl) for specified endpoint. If the endpoint did not have ttl before then this method sets it up.

Parameters:

serviceName - name of the service the endpoint belongs to

endpoint - name of the endpoint

timetolive - period of time (in seconds) when this endpoint is considered "alive"

Throws:

ServiceLocatorException - thrown if a problem happened. For example if the endpoint does not exist, if given time-to-live is negative or zero, etc.

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

removeEndpoint

void removeEndpoint(QName serviceName,
                  String endpoint)
                    throws ServiceLocatorException,
                           InterruptedException

Remove the given endpoint from the list of endpoints of the given service. When calling getEndpoint(serviceName) the given endpoint will not be contained in the returned list. In case no service with the given name exists or the given endpoint is not registered with the service the state of the Service Locator remians unchanged.

Parameters:

serviceName - the name of the service the endpoint is removed from, must not be null

endpoint - the endpoint to remove, must not be null

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

getServices

List<QName> getServices()
                        throws InterruptedException,
                               ServiceLocatorException

Return all services for which endpoints are registered at the Service Locator Service.

Returns:

a possibly empty list of services

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

getEndpoint

SLEndpoint getEndpoint(QName serviceName,
                     String endpoint)
                       throws ServiceLocatorException,
                              InterruptedException

Return the complete endpoint information for the given endpoint registered for the given service.

Parameters:

serviceName - the name of the service for which the endpoint is registered, must not be null

endpoint - the endpoint for which to return the information, must not be null

Returns:

the end point information, may be null if the endpoint was not registered before

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

getEndpoints

List<SLEndpoint> getEndpoints(QName serviceName)
                              throws ServiceLocatorException,
                                     InterruptedException

Return the complete endpoint informations for all endpoints registered for the given service.

Parameters:

serviceName - the name of the service for which the endpoints ares registered, must not be null

Returns:

the list of end point informations, may be empty if no the endpoints are registered for the service.

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

getEndpointNames

List<String> getEndpointNames(QName serviceName)
                              throws ServiceLocatorException,
                                     InterruptedException

For the given service return all endpoints that currently registered at the Service Locator Service.

Parameters:

serviceName - the name of the service for which to get the endpoints, must not be null

Returns:

a possibly empty list of endpoints

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

lookup

List<String> lookup(QName serviceName)
                    throws ServiceLocatorException,
                           InterruptedException

For the given service return all endpoints that are currently registered at the Service Locator.

Parameters:

serviceName - the name of the service for which to get the endpoints, must not be null

Returns:

a possibly empty list of endpoints

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

lookup

List<String> lookup(QName serviceName,
                  SLPropertiesMatcher matcher)
                    throws ServiceLocatorException,
                           InterruptedException

For the given service return all endpoints that are currently registered at the Service Locator and where the custom properties match the given matcher.

Parameters:

serviceName - the name of the service for which to get the endpoints, must not be null

matcher - custom properties of the endpoints returned match the criterias specified by this matcher

Returns:

a possibly empty list of endpoints

Throws:

ServiceLocatorException - the server returned an error

InterruptedException - the current Thread was interrupted when waiting for a response of the ServiceLocator

setPostConnectAction

void setPostConnectAction(ServiceLocator.PostConnectAction postConnectAction)

Specify the action to be be executed after the Service Locator has connected to the server.

Parameters:

postConnectAction - the action to be executed, must not be null.