*** This class is subject to change. ***

com.sas.services.discovery
Class ActivatableDiscoveryService

com.sas.services.discovery.ActivatableDiscoveryService

All Implemented Interfaces:

com.sas.entities.EntityKeyInterface, DiscoveryAdminInterface, DiscoveryServiceInterface, FindServiceInterface, ServiceNotificationBroadcasterInterface, RemoteServiceInterface, java.rmi.Remote

public final class ActivatableDiscoveryService
implements DiscoveryServiceInterface

Remotely accessible discovery service.

This implementation of the discovery service supports a remote deployment whereby services registered with this service can be made accessible to clients running in other JVM processes.

Since:

1.0

Field Summary

Fields inherited from interface com.sas.services.discovery.FindServiceInterface

FIND_ALL_MATCHES, FIND_ONE_MATCH

Fields inherited from interface com.sas.services.RemoteServiceInterface

CLASS_IDENTIFIER, CLASS_IDENTIFIER_1_1, CLASS_IDENTIFIER_1_2, CLASS_IDENTIFIER_SERVICE_TYPE, CLASS_IDENTIFIER_SERVICE_TYPE_1_1, CLASS_IDENTIFIER_SERVICE_TYPE_1_2

Constructor Summary

ActivatableDiscoveryService(ServiceConfigurationInterface serviceConfiguration, DiscoveryServiceInterface discoveryService)
Constructs a default instance of a remote discovery service.

Method Summary

void	addDiscoveryDelegate(FindServiceInterface serviceFinder) Adds an delegate that is capable of discovering implementations.
void	addService(RemoteServiceInterface service) Adds a service to the registry.
void	configure(ServiceConfigurationInterface serviceConfiguration) Configures service.
void	destroy() Destroys the service.
RemoteServiceInterface	findService(ServiceTemplate serviceTemplate) Finds a service using a discovery mechanism.
Services	findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services discoveredServices) Finds a collection of objects via a discovery mechanism.
RemoteServiceInterface	findServiceUsingId(java.lang.String runtimeServiceId) Re-acquires a previously discovered service via its service discovery ID.
java.util.Iterator<FindServiceInterface>	getDiscoverers() Gets an iterator of the discovery services.
DiscoveryServiceInterface	getDiscoveryService() Gets the discovery service.
java.util.Iterator<RemoteServiceInterface>	getLocalServices() Gets an iterator of local objects that implement the RemoteServiceInterface interface.
java.util.Iterator<RemoteServiceInterface>	getRemoteServices() Gets an iterator of registered services.
java.lang.String	getServiceName() Gets the service's name.
RemoteServiceInterface	getServiceProxy() Gets a new proxy to this service.
void	removeDiscoveryDelegate(FindServiceInterface serviceFinder) Removes an agent previously added as a discovery agent.
void	removeService(RemoteServiceInterface service) Removes a service from the registry.
java.lang.String	toString() Gets a string representation of this instance.

Methods inherited from class com.sas.services.AbstractRemoteService

addServiceObserver, bindToDiscoveryService, getCreationTime, getDetails, getEntityKey, getEnvironment, getServiceConfiguration, getServiceConfiguration, getServiceState, handleJVMShutdown, isAccessibleToRemoteClients, isExported, isHandlingJVMShutdown, notifyServiceObservers, reconfigure, removeAllServiceObservers, removeServiceObserver, sameEntity, setDiscoveryService, setEntityKey, setRemoteableExporter, setServiceState, unbindFromDiscoveryService

Methods inherited from interface com.sas.services.RemoteServiceInterface

getCreationTime, getServiceConfiguration, getServiceConfiguration, getServiceState, isAccessibleToRemoteClients, isExported, reconfigure, setServiceState

Methods inherited from interface com.sas.services.mgmt.ServiceNotificationBroadcasterInterface

addServiceObserver, notifyServiceObservers, removeAllServiceObservers, removeServiceObserver

Constructor Detail

ActivatableDiscoveryService

public ActivatableDiscoveryService(ServiceConfigurationInterface serviceConfiguration,
                                   DiscoveryServiceInterface discoveryService)
                            throws ServiceException,
                                   java.lang.IllegalArgumentException

Constructs a default instance of a remote discovery service.

Parameters:

serviceConfiguration - Service's configuration.

discoveryService - A discovery service which may be used to locate other services and to which a service must bind in order to be located by other services.

Throws:

java.lang.IllegalArgumentException - if unable to configure the service.

ServiceException - if unable to export this service. The service exception's cause may be a RemoteException.

Method Detail

configure

public void configure(ServiceConfigurationInterface serviceConfiguration)
               throws InitializationException,
                      java.rmi.RemoteException,
                      ServiceException,
                      java.lang.IllegalArgumentException

Configures service. Note that this method may used to initialize a service or to re-configure a previously initialized service.

Specified by:

configure in interface RemoteServiceInterface

Overrides:

configure in class AbstractRemoteService

Parameters:

serviceConfiguration - An object containing configuration data necessary to initialize or re-configure a service. Note that the service provider must verify that the object type is supported. An InitializationException should be thrown if the initialization was not completed successfully to indicate that the instance should not be used.

Throws:

InitializationException - if unable to configure the service.

java.rmi.RemoteException - if a network anomaly is encountered.

ServiceException - if unable to configure the service.

java.lang.IllegalArgumentException - if a null service configuration is specified.

getServiceProxy

public RemoteServiceInterface getServiceProxy()
                                       throws java.lang.IllegalStateException

Gets a new proxy to this service.

Specified by:

getServiceProxy in interface RemoteServiceInterface

Overrides:

getServiceProxy in class AbstractRemoteService

Returns:

A proxy to this service or null if a proxy is not available.

Throws:

java.lang.IllegalStateException - if this service has been destroyed.

destroy

public void destroy()
             throws ServiceException,
                    java.rmi.RemoteException

Destroys the service. The service should release any resources it holds in preparation for termination of use of this service.

Specified by:

destroy in interface RemoteServiceInterface

Overrides:

destroy in class AbstractRemoteService

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

ServiceException - if the service is unable to prepare itself for destruction.

getDiscoveryService

public DiscoveryServiceInterface getDiscoveryService()
                                              throws java.lang.IllegalStateException

Gets the discovery service. A default service will be created if one is not currently specified.

Overrides:

getDiscoveryService in class AbstractRemoteService

Returns:

A discovery service.

Throws:

java.lang.IllegalStateException - if this service has been destroyed.

findServiceUsingId

public RemoteServiceInterface findServiceUsingId(java.lang.String runtimeServiceId)
                                          throws ServiceException,
                                                 ServiceNotAvailableException,
                                                 java.lang.IllegalStateException,
                                                 java.rmi.RemoteException

Re-acquires a previously discovered service via its service discovery ID. The service discovery ID is runtime ID that is unique across JVMs and only used in the context of discovering a service.

Specified by:

findServiceUsingId in interface FindServiceInterface

Parameters:

runtimeServiceId - Service's discovery ID.

Returns:

RemoteServiceInterface implementation that satisfies the discovery parameters. Note that RemoteServiceInterface is the base interface implemented by all services.

Throws:

ServiceException - if an unanticipated exception occurs while processing the discovery. Note that ServiceNotAvailableException extends ServiceException.

ServiceNotAvailableException - if no service satisfies the requested service template.

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException

findService

public RemoteServiceInterface findService(ServiceTemplate serviceTemplate)
                                   throws ServiceException,
                                          ServiceNotAvailableException,
                                          java.lang.IllegalArgumentException,
                                          java.rmi.RemoteException

Finds a service using a discovery mechanism.

To be considered a successful match, the service must satisfy the requested service template which may be used to specify:

• class(es) the service is, extends, or implements
• additional filtering criteria expressed in terms of ServiceAttributeInterface

Specified by:

findService in interface FindServiceInterface

Parameters:

serviceTemplate - Service capability template that specifies the desired class(es) that define a service. The template may also specify criteria to provide additional filtering.

Returns:

RemoteServiceInterface implementation that satisfies the requested service template. Note that RemoteServiceInterface is the base interface implemented by all services.

Throws:

ServiceException - if an unanticipated exception occurs while processing the discovery.

ServiceNotAvailableException - if no service satisfies the requested service template. Note that ServiceNotAvailableException extends ServiceException.

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalArgumentException

See Also:

ServiceTemplate

findServices

public Services findServices(ServiceTemplate serviceTemplate,
                             int maxNumMatches,
                             Services discoveredServices)
                      throws ServiceException,
                             ServiceNotAvailableException,
                             java.lang.IllegalStateException,
                             java.rmi.RemoteException

Finds a collection of objects via a discovery mechanism.

To be considered a successful match, the service must satisfy the requested service template which may be used to specify:

• a service ID
• classes the service is, extends, or implements
• additional filtering criteria

Specified by:

findServices in interface FindServiceInterface

Parameters:

serviceTemplate - Service capability template that specifies either

1. a service ID to retrieve a particular service
2. the desired classes that define a service. One may also specify additional criteria to provide additional filtering.

maxNumMatches - Maximum number of services.

discoveredServices - A collection containing services that have already been found. Set this parameter to null if no services have been found yet.

Returns:

A collection containing search results. Each collection element will either be, implement, or extend the requested classes.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

ServiceException - if an unanticipated exception occurs while processing the discovery.

ServiceNotAvailableException - if no service satisfies the requested service template.

java.lang.IllegalStateException - if this service has been destroyed.

See Also:

ServiceTemplate

getRemoteServices

public java.util.Iterator<RemoteServiceInterface> getRemoteServices()
                                                             throws java.rmi.RemoteException

Gets an iterator of registered services.

Specified by:

getRemoteServices in interface DiscoveryAdminInterface

Returns:

Iterator of remotely available services that implement the RemoteServiceInterface interface.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

getLocalServices

public java.util.Iterator<RemoteServiceInterface> getLocalServices()
                                                            throws java.rmi.RemoteException

Gets an iterator of local objects that implement the RemoteServiceInterface interface.

Specified by:

getLocalServices in interface DiscoveryAdminInterface

Returns:

Iterator of locally available services that implement the RemoteServiceInterface interface.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

addDiscoveryDelegate

public void addDiscoveryDelegate(FindServiceInterface serviceFinder)
                          throws java.rmi.RemoteException

Adds an delegate that is capable of discovering implementations.

Specified by:

addDiscoveryDelegate in interface DiscoveryAdminInterface

Parameters:

serviceFinder - Discovery service implementation.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

removeDiscoveryDelegate

public void removeDiscoveryDelegate(FindServiceInterface serviceFinder)
                             throws java.rmi.RemoteException

Removes an agent previously added as a discovery agent.

Specified by:

removeDiscoveryDelegate in interface DiscoveryAdminInterface

Parameters:

serviceFinder - Discovery service implementation to remove.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

getDiscoverers

public java.util.Iterator<FindServiceInterface> getDiscoverers()
                                                        throws java.rmi.RemoteException

Gets an iterator of the discovery services.

Specified by:

getDiscoverers in interface DiscoveryAdminInterface

Returns:

Iterator of discovery delegates.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

addService

public void addService(RemoteServiceInterface service)
                throws ServiceException,
                       java.rmi.RemoteException

Adds a service to the registry.

Specified by:

addService in interface DiscoveryAdminInterface

Parameters:

service - Service that can be discovered via its service capabilities.

Throws:

ServiceException - if unable to cache the service.

java.rmi.RemoteException - if a network anomaly is encountered.

removeService

public void removeService(RemoteServiceInterface service)
                   throws java.rmi.RemoteException

Removes a service from the registry.

Specified by:

removeService in interface DiscoveryAdminInterface

Parameters:

service - Service that is to be removed.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

getServiceName

public java.lang.String getServiceName()

Gets the service's name.

Returns:

Service's name.

toString

public java.lang.String toString()

Gets a string representation of this instance. Intended for debugging purposes.

Overrides:

toString in class AbstractRemoteService

Returns:

Debug statement describing this instance.

*** This class is subject to change. ***