All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Foundation |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

## com.sas.services.discovery
Class DiscoveryService

    com.sas.services.discovery.DiscoveryService

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

    public class DiscoveryService

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
Permission | Action | Description
--- | --- | ---
java.lang.RuntimePermission | shutdownHooks | 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.ServicePermission | destroy | 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.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

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
`DiscoveryService()` Constructs a default instance of a discovery service.
`DiscoveryService(java.util.Set discoveryDelegates)` Constructs an instance of a discovery service and initializes it with discovery delegates specified in the provided collection.
`DiscoveryService(java.util.Set discoveryDelegates, java.util.Set services)` Constructs an instance of a discovery service and initializes it with discovery delegates specified in the provided collection.

Method Summary
`void` | `addDiscoveryDelegate(FindServiceInterface discoveryDelegate)` Adds a discovery delegate.
`void` | `addService(RemoteServiceInterface service)` Adds a service that is intended to be discovered.
`static LocalDiscoveryServiceInterface` | `defaultInstance()` Obtains a singleton instance of the local discovery service.
`void` | `destroy()` Destroy this discovery service releasing any resources that have been allocated.
`void` | `destroy(UserContextInterface userContext)` Destroy this discovery service releasing any resources that have been allocated.
`Services` | `findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services discoveredServices)` Finds a collection of objects via a discovery mechanism.
`Services` | `findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services discoveredServices, java.lang.String serviceRequestId, int attemptNumber)` Finds a collection of objects via a discovery mechanism.
`java.util.Iterator` | `getDiscoverers()` Gets an iterator for a copy of the set of discovery delegates.
`java.util.Iterator` | `getLocalServices()` Gets an iterator of non-remoteable objects that implement the `RemoteServiceInterface`.
`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.
`java.util.Iterator` | `getRemoteServices()` Gets an iterator of remoteable objects that implement the `RemoteServiceInterface`.
`java.lang.String` | `getServiceName()` Gets this service's name.
`static boolean` | `isOkToProcessRequest(java.lang.String discoveryServiceId, ServiceTemplate serviceTemplate)` Determines whether or not it is OK to for the specified discovery service to process the requested service template.
`void` | `removeDiscoveryDelegate(FindServiceInterface serviceLocator)` Removes a discovery delegate.
`void` | `removeService(RemoteServiceInterface service)` Removes a service from this discovery service.
`void` | `setLookupPolicy(LookupPolicyInterface lookupPolicy)` Specifies an implementation of policies related to service discovery.
`java.lang.String` | `toString()` Gets a string representation of this instance.

Methods inherited from class com.sas.services.discovery.AbstractDiscoveryService
`findService, findServiceUsingId`

Methods inherited from class com.sas.services.AbstractService
`configure, getEntityKey`

Methods inherited from class com.sas.services.AbstractRemoteService
`addServiceObserver, bindToDiscoveryService, getCreationTime, getDetails, getDiscoveryService, getEnvironment, getServiceConfiguration, getServiceConfiguration, getServiceProxy, getServiceState, handleJVMShutdown, isAccessibleToRemoteClients, isExported, isHandlingJVMShutdown, notifyServiceObservers, reconfigure, removeAllServiceObservers, removeServiceObserver, sameEntity, setDiscoveryService, setEntityKey, setRemoteableExporter, setServiceState, unbindFromDiscoveryService`

Methods inherited from interface com.sas.services.discovery.FindServiceInterface
`findService, findServiceUsingId`

Methods inherited from interface com.sas.services.RemoteServiceInterface
`configure, getCreationTime, getServiceConfiguration, getServiceConfiguration, getServiceProxy, getServiceState, isAccessibleToRemoteClients, isExported, reconfigure, setServiceState`

Methods inherited from interface com.sas.services.mgmt.ServiceNotificationBroadcasterInterface
`addServiceObserver, notifyServiceObservers, removeAllServiceObservers, removeServiceObserver`

Constructor Detail

### DiscoveryService

    public DiscoveryService()

  Constructs a default instance of a discovery service.

### DiscoveryService

    public DiscoveryService(java.util.Set discoveryDelegates)
                     throws java.lang.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:
    `java.lang.IllegalArgumentException` - if a `null` collection is specified or if the collection does not contain elements that implement `FindServiceInterface`.

### DiscoveryService

    public DiscoveryService(java.util.Set discoveryDelegates,
                            java.util.Set 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 Detail

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

  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.
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `ServiceNotAvailableException` - if no service satisfies the requested service template.
    `java.lang.IllegalStateException` - if this service has been destroyed and is no longer accepting requests to find services.
  See Also:
    `ServiceTemplate`

### findServices

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

  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.
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `ServiceNotAvailableException` - if no service satisfies the requested service template.
  See Also:
    `ServiceTemplate`

### getServiceName

    public java.lang.String getServiceName()

  Gets this service's name.

  Returns:
    Service's name.

### getDiscoverers

    public final java.util.Iterator 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 java.rmi.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:
    `java.rmi.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 java.util.Iterator getLocalServices()

  Gets an iterator of non-remoteable objects that implement the `RemoteServiceInterface`.

  Specified by:
    `getLocalServices` in interface `DiscoveryAdminInterface`
  Returns:
    Iterator of locally available services that implement the `ServiceInterface`.

### getRemoteServices

    public java.util.Iterator 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 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.

### isOkToProcessRequest

    public static final boolean isOkToProcessRequest(java.lang.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`

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

All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Foundation |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 SAS Institute Inc. All Rights Reserved.