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

Package com.sas.services.discovery

Class DiscoveryService

java.lang.Object
com.sas.services.AbstractRemoteService
com.sas.services.AbstractService
com.sas.services.discovery.AbstractDiscoveryService
com.sas.services.discovery.DiscoveryService
All Implemented Interfaces:
com.sas.entities.EntityKeyInterface, DiscoveryAdminInterface, DiscoveryServiceInterface, FindServiceInterface, LocalDiscoveryServiceInterface, ServiceNotificationBroadcasterInterface, RemoteServiceInterface, Remote
@SASScope("ALL") @SubjectToChange public class DiscoveryService extends AbstractDiscoveryService implements LocalDiscoveryServiceInterface
Discovery service used to store registered services and discovery delegates.

This service provides the mechanism to discover and obtain one or more implementations of a service satisfying a specified service template which is expressed in terms of service capabilities and optional attributes. Service capabilities are expressed in terms of what a service is, extends, or interface it implements.

JAAS Permissions

The following permission actions may be used to control authorization to execute service operations.

JAAS Permissions used by the Discovery Service
PermissionActionDescription
java.lang.RuntimePermissionshutdownHooks allows the discovery service to register a JVM shutdown hook, which when called will destroy the discovery service and all registered foundation services started within the application
com.sas.services.ServicePermissiondestroy allows one to destroy the discovery service and all registered foundation services started within the application

Example 1: The Local Discovery Service

Each application employs a discovery service to locate services deployed locally within the application. Use defaultInstance() to obtain the application's local discovery service. 
 LocalDiscoveryServiceInterface discoveryService =
    DiscoveryService.defaultInstance();

Example 2: Destroying the Local Discovery Service

When an application is terminated it must destroy the local discovery service to ensure that any locally instantiated services are destroyed and any resources they've allocated are deallocated. 
 DiscoveryService.defaultInstance().destroy;

Example 3: Find a Service satisfying a service interface

After an application has either locally deployed services using ServiceLoader.deployServices(MetadataSourceInterface metadataSource) or looked up services deployed remotely in another application using ServiceLoader.lookupRemoteDiscoveryServices(com.sas.services.deployment.MetadataSourceInterface, DiscoveryServiceInterface) one may use the local discovery service to find services.

This example will attempt to find a service satisfying the specified service template by first searching services instantiated locally within this application. If a service is not found and discovery delegates are defined, then the request will be forwarded to discovery service(s) in remote applications. 

 ...
 
 // application has already either deployed services locally
 // or looked up a remote discovery service that resides in
 // another application.

 import com.sas.services.security.AuthenticationServiceInterface;
 ...
 
 LocalDiscoveryServiceInterface discoveryService =
    DiscoveryService.defaultInstance();
 
 ServiceTemplate serviceTemplate = new ServiceTemplate(
    new Class[] {
       AuthenticationServiceInterface.class
       });
 
 AuthenticationServiceInterface authenticationService = 
    (AuthenticationServiceInterface) discoveryService.findService(serviceTemplate);

Example 4: Find a Service satisfying a service interface and specified service attributes

After an application has either locally deployed services using ServiceLoader.deployServices(MetadataSourceInterface metadataSource) or looked up services deployed remotely in another application using ServiceLoader.lookupRemoteDiscoveryServices(com.sas.services.deployment.MetadataSourceInterface, DiscoveryServiceInterface) one may use the local discovery service to find services.

This example will attempt to find a service satisfying the specified service template which designates a service interface and service attributes which are used to distinguish between multiple service implementations that satisfy the same service interfaces. 

 ...
 
 // application has already either deployed services locally
 // or looked up a remote discovery service that resides in
 // another application.

 import com.sas.metadata.remote.MetadataObjects;
 import com.sas.services.deployment.ServiceDeploymentInterface;
 import com.sas.services.security.AuthenticationServiceInterface;
 
 ...
 
 // the name of the SoftwareComponent that owns the desired
 // Authentication Service
 String softwareComponentName = "Query and Reporting";
 
 
 // desired service: Authentication Service
 Class[] serviceTypes = new Class[] {
    AuthenticationServiceInterface.class
    };
 
 // a Authentication Service that is associated with the
 // software component named "Query and Reporting"
 ServiceAttributeInterface[] serviceAttributes = new ServiceAttributeInterface[] {
    new MetadataAttribute(
       null, // a null SoftwareComponent.FQID indicates a don't care
       softwareComponentName, // SoftwareComponent.Name
       MetadataObjects.SOFTWARECOMPONENT,
       ServiceDeploymentInterface.CLASS_IDENTIFIER);
    };
 
 ServiceTemplate serviceTemplate = new ServiceTemplate(
    serviceTypes,
    serviceAttributes);
 
 // find the Authentication Service that belongs to the foundation services
 // deployment named "Query and Reporting" by using a service template
 // that designates the service interface and an optional service
 // attribute designating the service's owning SoftwareComponent.
 
 LocalDiscoveryServiceInterface discoveryService =
    DiscoveryService.defaultInstance();
 
 AuthenticationServiceInterface authenticationService = 
    (AuthenticationServiceInterface) discoveryService.findService(serviceTemplate);

Example 5: Lookup Attempt Policy

By default this local discovery service implementation does not try to re-attempt to find services if a lookup fails to find a service satisfying requested lookup parameters. Support is provided to optionally specify a lookup policy that will be consulted to determine whether a lookup should be re-attempted in the event that service(s) are not found. This may be useful in cases such as web applications where it is difficult to control application startup sequences.

One policy is to to specify a maximum timeout in msec. Lookups will be re-attempted until the timeout expires. The following code snippet shows how to specify a timeout lookup policy. 

    LocalDiscoveryServiceInterface discoveryService =
       DiscoveryService.defaultInstance();
    final long timeoutInMsec = 750;
    final LookupPolicyInterface lookupPolicyIf =
       new LookupPolicyTimeout(timeoutInMsec);
    System.out.println(lookupPolicyIf);
    discoveryService.setLookupPolicy(lookupPolicyIf);

Alternatively one can employ a policy of re-attempting lookups for a specified number of times at designated intervals specified in units of msec. The following code example shows how to specify an maximum attempts lookup policy. 

    LocalDiscoveryServiceInterface discoveryService =
       DiscoveryService.defaultInstance();
    final long attemptIntervalInMsec = 5000;
    final int  maxNumAttempts = 2;
    final LookupPolicyInterface lookupPolicyIf =
       new LookupPolicyAttempts(
       maxNumAttempts,
       attemptIntervalInMsec);
    System.out.println(lookupPolicyIf);
    discoveryService.setLookupPolicy(lookupPolicyIf);

If service lookup re-attempt policy is only needed during your application's initialization, then one should clear the policy to enable the lookup to return to its default behavior of not re-attempting lookups after your initialization completes. The following code example shows how to clear the lookup policy. 

    LocalDiscoveryServiceInterface discoveryService =
       DiscoveryService.defaultInstance();
    discoveryService.setLookupPolicy(null);

If an alternative lookup policy is desired, then one can implement their own lookup policy that implements the LookupPolicyInterface interface.

Since:
1.0

  • Constructor Details

    • DiscoveryService

      public DiscoveryService()
      Constructs a default instance of a discovery service.

    • DiscoveryService

      public DiscoveryService(Set<FindServiceInterface> discoveryDelegates) throws IllegalArgumentException
      Constructs an instance of a discovery service and initializes it with discovery delegates specified in the provided collection.
      Parameters:
      discoveryDelegates - Collection containing service locators which implement the FindServiceInterface interface.
      Throws:
      IllegalArgumentException - if a null collection is specified or if the collection does not contain elements that implement FindServiceInterface.

    • DiscoveryService

      public DiscoveryService(Set<FindServiceInterface> discoveryDelegates, Set<RemoteServiceInterface> services) throws ServiceException
      Constructs an instance of a discovery service and initializes it with discovery delegates specified in the provided collection.
      Parameters:
      discoveryDelegates - Collection containing service locators which implement the FindServiceInterface interface or null if there are no services to add.
      services - Collection of services which implement RemoteServiceInterface or null if there are no services to add.
      Throws:
      ServiceException - if a null collection is specified or if the collection does not contain elements that implement FindServiceInterface.

  • Method Details

    • defaultInstance

      public static final LocalDiscoveryServiceInterface defaultInstance()
      Obtains a singleton instance of the local discovery service.

      This instance should be destroyed by the application when the application is terminated to enable destruction of all locally instantiated services. Locally instantiated services will be destroyed in order from most to least recently instantiated. When the application is ready to terminate it must destroy the local discovery service by invoking DiscoveryService.defaultInstance().destroy()

      Returns:
      Singleton instance of the local discovery service or null if unable to configure the local discovery service.

    • findServices

      public final 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

      Note that all of the find service methods funnel their processing to this method.

      Specified by:
      findServices in interface FindServiceInterface
      Specified by:
      findServices in class AbstractDiscoveryService
      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:
      ServiceException - if an unanticipated exception occurs while processing the discovery.
      RemoteException - if a network anomaly is encountered.
      ServiceNotAvailableException - if no service satisfies the requested service template.
      IllegalStateException - if this service has been destroyed and is no longer accepting requests to find services.
      See Also:

    • findServices

      public final Services findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services discoveredServices, String serviceRequestId, int attemptNumber) throws ServiceException, ServiceNotAvailableException, 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

      Note that all of the find service methods funnel their processing to this method.

      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.
      serviceRequestId - An ID uniquely associated with this service lookup request.
      attemptNumber - The number of attempts that have been made to find services so far.
      Returns:
      A collection containing search results. Each collection element will either be, implement, or extend the requested classes.
      Throws:
      ServiceException - if an unanticipated exception occurs while processing the discovery.
      RemoteException - if a network anomaly is encountered.
      ServiceNotAvailableException - if no service satisfies the requested service template.
      See Also:

    • getServiceName

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

    • getDiscoverers

      public final Iterator<FindServiceInterface> getDiscoverers()
      Gets an iterator for a copy of the set of discovery delegates.
      Specified by:
      getDiscoverers in interface DiscoveryAdminInterface
      Returns:
      Iterator of a copy of the collection of discovery delegates that implement FindServiceInterface.

    • addDiscoveryDelegate

      public final void addDiscoveryDelegate(FindServiceInterface discoveryDelegate) throws RemoteException
      Adds a discovery delegate.
      Specified by:
      addDiscoveryDelegate in interface DiscoveryAdminInterface
      Parameters:
      discoveryDelegate - The discovery delegate to add. A warning will be logged if one attempts to add a delegate which implements EntityKeyInterface that has already been registered.
      Throws:
      RemoteException - if a network anomaly is encountered

    • removeDiscoveryDelegate

      public final void removeDiscoveryDelegate(FindServiceInterface serviceLocator)
      Removes a discovery delegate.
      Specified by:
      removeDiscoveryDelegate in interface DiscoveryAdminInterface
      Parameters:
      serviceLocator - Discovery delegate to remove.

    • addService

      public final void addService(RemoteServiceInterface service) throws ServiceException
      Adds a service that is intended to be discovered.
      Specified by:
      addService in interface DiscoveryAdminInterface
      Parameters:
      service - A service to register with this discovery service.
      Throws:
      ServiceException - if unable to add the service.

    • removeService

      public final void removeService(RemoteServiceInterface service)
      Removes a service from this discovery service.
      Specified by:
      removeService in interface DiscoveryAdminInterface
      Parameters:
      service - Service that is to be removed.

    • getLocalServices

      public Iterator<RemoteServiceInterface> getLocalServices()
      Gets an iterator of non-remoteable objects that implement the RemoteServiceInterface.
      Specified by:
      getLocalServices in interface DiscoveryAdminInterface
      Returns:
      Iterator of locally available services.

    • getRemoteServices

      public Iterator<RemoteServiceInterface> getRemoteServices()
      Gets an iterator of remoteable objects that implement the RemoteServiceInterface.
      Specified by:
      getRemoteServices in interface DiscoveryAdminInterface
      Returns:
      Iterator of remotely available services that implement the RemoteServiceInterface interface.

    • toString

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

    • isOkToProcessRequest

      public static final boolean isOkToProcessRequest(String discoveryServiceId, ServiceTemplate serviceTemplate)
      Determines whether or not it is OK to for the specified discovery service to process the requested service template.
      Parameters:
      discoveryServiceId - A discovery service's entity key.
      serviceTemplate - Service template containing a passport of discovery services that have previously processed the requested template.
      Returns:
      true if it is OK to process the request or false if it isn't.

    • destroy

      public void destroy()
      Destroy this discovery service releasing any resources that have been allocated. All locally instantiated foundation services registered with this discovery service will be destroyed in reverse order from which they were instantiated (most recently instantiated service is destroyed first). All references to remote services will be null'ed and all discovery delegates will be removed.

      The destruction call is then passed on to the superclass where resources common to all foundation services will be released.

      Specified by:
      destroy in interface RemoteServiceInterface
      Overrides:
      destroy in class AbstractService

    • destroy

      public void destroy(UserContextInterface userContext)
      Destroy this discovery service releasing any resources that have been allocated. All locally instantiated foundation services registered with this discovery service will be destroyed in reverse order from which they were instantiated (most recently instantiated service is destroyed first). All references to remote services will be null'ed and all discovery delegates will be removed.

      The destruction call is then passed on to the super class where resources common to all foundation services will be released.

      Parameters:
      userContext - A User context which is used in a check to ensure that the caller is authorized for the following permission: com.sas.services.ServicePermission "destroy"

    • getLookupPolicy

      public final LookupPolicyInterface getLookupPolicy()
      Gets the lookup policy that controls whether or not an attempt is made to re-lookup a service in the event that it was not available.
      Specified by:
      getLookupPolicy in interface LocalDiscoveryServiceInterface
      Returns:
      Lookup policy or null if a lookup should not be re-attempted.

    • setLookupPolicy

      public final void setLookupPolicy(LookupPolicyInterface lookupPolicy)
      Specifies an implementation of policies related to service discovery. This is an optional control that can be specified if one is interested in controlling whether or not a service lookup should be re-attempted in the event that no services are found satisfying the requested parameters.

      Refer to LookupPolicyInterface to determine lookup policy implementations.

      Specified by:
      setLookupPolicy in interface LocalDiscoveryServiceInterface
      Parameters:
      lookupPolicy - Policy implementations related to service discovery. Refer to LookupPolicyInterface