*** 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

@SASScope(value="ALL")
@SubjectToChange
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.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

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<FindServiceInterface> discoveryDelegates)
Constructs an instance of a discovery service and initializes it with discovery delegates specified in the provided collection.

DiscoveryService(java.util.Set<FindServiceInterface> discoveryDelegates, java.util.Set<RemoteServiceInterface> 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<FindServiceInterface>	getDiscoverers() Gets an iterator for a copy of the set of discovery delegates.
java.util.Iterator<RemoteServiceInterface>	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<RemoteServiceInterface>	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.entities.EntityKeyInterface

getEntityKey, sameEntity, setEntityKey

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<FindServiceInterface> 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<FindServiceInterface> discoveryDelegates,
                        java.util.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 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<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 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<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 java.util.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 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. ***