xal.extension.service

Class ServiceDirectory

java.lang.Object

xal.extension.service.ServiceDirectory

public final class ServiceDirectory
extends java.lang.Object

ServiceDirectory is a local point of access for registering and looking up services on a network. It wraps the standard Bonjour mechanism to provide a simple way to register and lookup services by using a Java interface as a service name. XML-RPC is the communication protocol used for messaging. Both Bonjour and XML-RPC are accepted protocols implemented in multiple languages.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ServiceDirectory.BonjourServiceListenerInfo service listener information for Bonjour

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<ServiceListener,ServiceDirectory.BonjourServiceListenerInfo>	_listenerMap Table mapping ServiceListener to the corresponding bonjour service listener

Constructor Summary

Constructors

Constructor and Description
ServiceDirectory() ServiceDirectory constructor.

Method Summary

Modifier and Type	Method and Description
void	addServiceListener(java.lang.Class<?> protocol, ServiceListener listener) Add a listener for addition and removal of service providers.
void	addServiceListener(java.lang.String type, ServiceListener listener) Add a listener for addition and removal of service providers.
static ServiceDirectory	defaultDirectory() Get the default ServiceDirectory instance.
void	dispose() Shutdown bonjour and the RPC server and dispose of all resources.
ServiceRef[]	findServicesWithType(java.lang.Class<?> protocol, long timeout) Convenience method for making a request to find service providers of a specific service type and waiting a specified amount of time to find those services.
ServiceRef[]	findServicesWithType(java.lang.String serviceType, long timeout) Convenience method for making a request to find service providers of a specific service type and waiting a specified amount of time to find those services.
protected static xal.extension.service.ClientHandler<?>	getClientHandler(java.lang.Object proxy) Convenience method for getting the ClientHandler for the given proxy
protected static java.lang.String	getDefaultType(java.lang.Class<?> protocol) Form a valid type based on the specified protocol by replacing the protocol's name with a valid name in which "." is replaced by "_".
static java.lang.String	getHost(java.lang.Object proxy) Get the remote host for the service
static int	getPort(java.lang.Object proxy) Get the remote port at which the service is available.
static java.lang.Class<?>	getProtocol(java.lang.Object proxy) Get the protocol of the remote proxy
<T> T	getProxy(java.lang.Class<T> protocol, ServiceRef serviceRef) Get a proxy to the service with the given service reference and protocol.
static java.lang.String	getServiceName(java.lang.Object proxy) Get the service name for the remote service
java.util.List<java.lang.String>	getStandardCodingTypes() Get a list of standard data types which are supported for coding and decoding
java.util.List<java.lang.String>	getSupportedCodingTypes() Get a list of all data types which are supported for coding and decoding
boolean	isActive() Check if service support is active.
boolean	isLoopback() Determine if bonjour is running in loopback mode which would indicate that the computer is isolated from the network.
ServiceRef	lookupService(java.lang.String type, java.lang.String name) Lookup the service given the fully qualified service type and the fully qualified service name
ServiceRef	lookupService(java.lang.String type, java.lang.String name, int timeout) Lookup the service given the fully qualified service type and the fully qualified service name and block until a match is found or the specified timeout has expired.
<CustomType,RepresentationType> void	registerCodingType(java.lang.Class<CustomType> type, ConversionAdaptor<CustomType,RepresentationType> adaptor) Register the custom type and its associated adaptor to use for encoding and decoding objects of the custom type
<ProtocolType> ServiceRef	registerService(java.lang.Class<ProtocolType> protocol, java.lang.String name, ProtocolType provider) Register a local service provider.
<ProtocolType> ServiceRef	registerService(java.lang.Class<ProtocolType> protocol, java.lang.String serviceName, ProtocolType provider, java.util.Map<java.lang.String,java.lang.Object> properties) Register a local service provider.
void	removeServiceListener(ServiceListener listener) Remove a listener of service availability events.
boolean	unregisterService(ServiceRef serviceRef) Unregister a local service.

Methods inherited from class java.lang.Object

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

Field Detail

_listenerMap

protected java.util.Map<ServiceListener,ServiceDirectory.BonjourServiceListenerInfo> _listenerMap

Table mapping ServiceListener to the corresponding bonjour service listener

Constructor Detail

ServiceDirectory

public ServiceDirectory()
                 throws ServiceException

ServiceDirectory constructor.

Throws:

ServiceException

Method Detail

defaultDirectory

public static ServiceDirectory defaultDirectory()

Get the default ServiceDirectory instance.

Returns:

The default ServiceDirectory instance.

dispose

public void dispose()

Shutdown bonjour and the RPC server and dispose of all resources.

isActive

public boolean isActive()

Check if service support is active. If initialization fails, then services will not be active.

Returns:

true if services are available

isLoopback

public boolean isLoopback()

Determine if bonjour is running in loopback mode which would indicate that the computer is isolated from the network. This flag is meaninful only if the service directory is active.

Returns:

true if the service is running in loopback mode and false if it is on a network

getStandardCodingTypes

public java.util.List<java.lang.String> getStandardCodingTypes()

Get a list of standard data types which are supported for coding and decoding

getSupportedCodingTypes

public java.util.List<java.lang.String> getSupportedCodingTypes()

Get a list of all data types which are supported for coding and decoding

registerCodingType

public <CustomType,RepresentationType> void registerCodingType(java.lang.Class<CustomType> type,
                                                               ConversionAdaptor<CustomType,RepresentationType> adaptor)

Register the custom type and its associated adaptor to use for encoding and decoding objects of the custom type

Parameters:

type - type to identify and process for encoding and decoding

adaptor - translator between the custom type and representation constructs

registerService

public <ProtocolType> ServiceRef registerService(java.lang.Class<ProtocolType> protocol,
                                                 java.lang.String name,
                                                 ProtocolType provider)
                                          throws ServiceException

Register a local service provider.

Parameters:

protocol - The protocol identifying the service type.

name - The unique name of the service provider.

provider - The provider which handles the service requests.

Returns:

a new service reference for successful registration and null otherwise.

Throws:

ServiceException

registerService

public <ProtocolType> ServiceRef registerService(java.lang.Class<ProtocolType> protocol,
                                                 java.lang.String serviceName,
                                                 ProtocolType provider,
                                                 java.util.Map<java.lang.String,java.lang.Object> properties)

Register a local service provider.

Parameters:

protocol - The protocol identifying the service type.

serviceName - The unique name of the service provider.

provider - The provider which handles the service requests.

properties - Properties.

Returns:

a new service reference for successful registration and null otherwise.

unregisterService

public boolean unregisterService(ServiceRef serviceRef)
                          throws ServiceException

Unregister a local service.

Parameters:

serviceRef - The service reference whose service should be shutdown.

Returns:

true if the service has been unregistered and false otherwise.

Throws:

ServiceException

getProxy

public <T> T getProxy(java.lang.Class<T> protocol,
                      ServiceRef serviceRef)

Get a proxy to the service with the given service reference and protocol.

Parameters:

protocol - The protocol implemented by the service.

serviceRef - The service reference.

Returns:

A proxy implementing the specified protocol for the specified service reference

lookupService

public ServiceRef lookupService(java.lang.String type,
                                java.lang.String name)

Lookup the service given the fully qualified service type and the fully qualified service name

Parameters:

type - The fully qualified service type

name - The fully qualified service name

Returns:

the matching service reference or null if no match is found

lookupService

public ServiceRef lookupService(java.lang.String type,
                                java.lang.String name,
                                int timeout)
                         throws ServiceException

Lookup the service given the fully qualified service type and the fully qualified service name and block until a match is found or the specified timeout has expired.

Parameters:

type - The fully qualified service type

name - The fully qualified service name

timeout - The timeout in milliseconds to block until a match is found

Returns:

the matching service reference or null if no match is found

Throws:

ServiceException

findServicesWithType

public ServiceRef[] findServicesWithType(java.lang.Class<?> protocol,
                                         long timeout)
                                  throws ServiceException

Convenience method for making a request to find service providers of a specific service type and waiting a specified amount of time to find those services. It is more preferable, however, to use the "addServiceListener()" method instead so as to monitor the availability of services. Convenience method used when the type is derived from the protocol's name.

Parameters:

protocol - The protocol identifying the service type for which to find providers.

timeout - Time to block in milliseconds while waiting for services to be discovered.

Returns:

An array of services which were found within the specified timeout

Throws:

ServiceException

See Also:

addServiceListener(java.lang.Class<?>, xal.extension.service.ServiceListener)

findServicesWithType

public ServiceRef[] findServicesWithType(java.lang.String serviceType,
                                         long timeout)
                                  throws ServiceException

Convenience method for making a request to find service providers of a specific service type and waiting a specified amount of time to find those services. It is more preferable, however, to use the "addServiceListener()" method instead so as to monitor the availability of services.

Parameters:

serviceType - The type of service to find.

timeout - Time to block in milliseconds while waiting for services to be discovered.

Returns:

An array of services which were found within the specified timeout

Throws:

ServiceException

See Also:

addServiceListener(java.lang.Class<?>, xal.extension.service.ServiceListener)

addServiceListener

public void addServiceListener(java.lang.Class<?> protocol,
                               ServiceListener listener)
                        throws ServiceException

Add a listener for addition and removal of service providers. Convenience method used when the type is derived from the protocol's name.

Parameters:

protocol - The protocol identifying the service type.

listener - The receiver of service availability events.

Throws:

ServiceException

addServiceListener

public void addServiceListener(java.lang.String type,
                               ServiceListener listener)
                        throws ServiceException

Add a listener for addition and removal of service providers.

Parameters:

type - The type of service provided.

listener - The receiver of service availability events.

Throws:

ServiceException

removeServiceListener

public void removeServiceListener(ServiceListener listener)

Remove a listener of service availability events.

Parameters:

listener - The listener of service availability events.

getDefaultType

protected static java.lang.String getDefaultType(java.lang.Class<?> protocol)

Form a valid type based on the specified protocol by replacing the protocol's name with a valid name in which "." is replaced by "_".

Parameters:

protocol - The protocol for which to get a valid type

Returns:

A valid type to represent the given protocol.

getHost

public static java.lang.String getHost(java.lang.Object proxy)

Get the remote host for the service

Parameters:

proxy - the proxy to the service at the remote host

Returns:

a string representation of the remote host

getPort

public static int getPort(java.lang.Object proxy)

Get the remote port at which the service is available.

Parameters:

proxy - the proxy to the service at the remote host

Returns:

the remote port at which the service is available

getServiceName

public static java.lang.String getServiceName(java.lang.Object proxy)

Get the service name for the remote service

Parameters:

proxy - the proxy to the remote service

Returns:

The name of the remote service

getProtocol

public static java.lang.Class<?> getProtocol(java.lang.Object proxy)

Get the protocol of the remote proxy

Parameters:

proxy - the proxy to the remote service

Returns:

the interface implemented by the proxy

getClientHandler

protected static xal.extension.service.ClientHandler<?> getClientHandler(java.lang.Object proxy)

Convenience method for getting the ClientHandler for the given proxy

Parameters:

proxy - the proxy for which we seek its client handler

Returns:

the client handler for the proxy