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

Package com.sas.services.discovery

# Class ActivatableDiscoveryService

java.lang.Object
com.sas.services.AbstractRemoteService
com.sas.services.discovery.ActivatableDiscoveryService

All Implemented Interfaces:
  `com.sas.entities.EntityKeyInterface`, `DiscoveryAdminInterface`, `DiscoveryServiceInterface`, `FindServiceInterface`, `ServiceNotificationBroadcasterInterface`, `RemoteServiceInterface`, `Remote`

@SASScope("ALL") @SubjectToChange public final class ActivatableDiscoveryService extends AbstractRemoteService 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

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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(String runtimeServiceId)`
  Re-acquires a previously discovered service via its service discovery ID.
  `Iterator<FindServiceInterface>`
  `getDiscoverers()`
  Gets an iterator of the discovery services.
  `DiscoveryServiceInterface`
  `getDiscoveryService()`
  Gets the discovery service.
  `Iterator<RemoteServiceInterface>`
  `getLocalServices()`
  Gets an iterator of local objects that implement the `RemoteServiceInterface` interface.
  `Iterator<RemoteServiceInterface>`
  `getRemoteServices()`
  Gets an iterator of registered services.
  `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.
  `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 class java.lang.Object

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

  ### Methods inherited from interface com.sas.entities.EntityKeyInterface

  `getEntityKey, sameEntity, setEntityKey`

  ### 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 Details

  - ### ActivatableDiscoveryService

    public ActivatableDiscoveryService(ServiceConfigurationInterface serviceConfiguration, DiscoveryServiceInterface discoveryService) throws ServiceException, 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:
      `IllegalArgumentException` - if unable to configure the service.
      `ServiceException` - if unable to export this service. The service exception's cause may be a RemoteException.

- ## Method Details

  - ### configure

    public void configure(ServiceConfigurationInterface serviceConfiguration) throws InitializationException, RemoteException, ServiceException, 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.
      `RemoteException` - if a network anomaly is encountered.
      `ServiceException` - if unable to configure the service.
      `IllegalArgumentException` - if a `null`service configuration is specified.``

  - ### getServiceProxy

    public RemoteServiceInterface getServiceProxy() throws 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:
      `IllegalStateException` - if this service has been destroyed.

  - ### destroy

    public void destroy() throws ServiceException, 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:
      `RemoteException` - if a network anomaly is encountered.
      `ServiceException` - if the service is unable to prepare itself for destruction.

  - ### getDiscoveryService

    public DiscoveryServiceInterface getDiscoveryService() throws 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:
      `IllegalStateException` - if this service has been destroyed.

  - ### findServiceUsingId

    public RemoteServiceInterface findServiceUsingId(String runtimeServiceId) throws ServiceException, ServiceNotAvailableException, IllegalStateException, 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.
      `RemoteException` - if a network anomaly is encountered.
      `IllegalStateException`

  - ### findService

    public RemoteServiceInterface findService(ServiceTemplate serviceTemplate) throws ServiceException, ServiceNotAvailableException, IllegalArgumentException, 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`.
      `RemoteException` - if a network anomaly is encountered.
      `IllegalArgumentException`
    See Also:
      - `ServiceTemplate`

  - ### findServices

    public Services findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services discoveredServices) throws ServiceException, ServiceNotAvailableException, IllegalStateException, 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:
      `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.
      `IllegalStateException` - if this service has been destroyed.
    See Also:
      - `ServiceTemplate`

  - ### getRemoteServices

    public Iterator<RemoteServiceInterface> getRemoteServices() throws 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:
      `RemoteException` - if a network anomaly is encountered.

  - ### getLocalServices

    public Iterator<RemoteServiceInterface> getLocalServices() throws 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:
      `RemoteException` - if a network anomaly is encountered.

  - ### addDiscoveryDelegate

    public void addDiscoveryDelegate(FindServiceInterface serviceFinder) throws RemoteException
    Adds an delegate that is capable of discovering implementations.
    Specified by:
      `addDiscoveryDelegate` in interface `DiscoveryAdminInterface`
    Parameters:
      `serviceFinder` - Discovery service implementation.
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### removeDiscoveryDelegate

    public void removeDiscoveryDelegate(FindServiceInterface serviceFinder) throws RemoteException
    Removes an agent previously added as a discovery agent.
    Specified by:
      `removeDiscoveryDelegate` in interface `DiscoveryAdminInterface`
    Parameters:
      `serviceFinder` - Discovery service implementation to remove.
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### getDiscoverers

    public Iterator<FindServiceInterface> getDiscoverers() throws RemoteException
    Gets an iterator of the discovery services.
    Specified by:
      `getDiscoverers` in interface `DiscoveryAdminInterface`
    Returns:
      Iterator of discovery delegates.
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### addService

    public void addService(RemoteServiceInterface service) throws ServiceException, 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.
      `RemoteException` - if a network anomaly is encountered.

  - ### removeService

    public void removeService(RemoteServiceInterface service) throws RemoteException
    Removes a service from the registry.
    Specified by:
      `removeService` in interface `DiscoveryAdminInterface`
    Parameters:
      `service` - Service that is to be removed.
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### getServiceName

    public String getServiceName()
    Gets the service's name.
    Returns:
      Service's name.

  - ### toString

    public String toString()
    Gets a string representation of this instance. Intended for debugging purposes.
    Overrides:
      `toString` in class `AbstractRemoteService`
    Returns:
      Debug statement describing this instance.