### *** This class provides Binary Compatibility only, not Source Compatibility ***

Package com.sas.services.discovery

# Class ServiceTemplate

java.lang.Object
com.sas.services.discovery.ServiceTemplate

All Implemented Interfaces:
  `Serializable`

@SASScope("ALL") @BinaryCompatibilityOnly public class ServiceTemplate extends Object implements Serializable
A service request template that describes the type(s) of services expressed in terms of Java classes/interfaces representing the business interfaces and optional service attributes. Service attributes may be used to filter services that satisfy the same service type(s).

A service discovery passport is used to track the discovery services that process this service request template. This passport is used to ensure that a request is not processed multiple times by the same discovery service. Note that if one wishes to resubmit a service discovery request using a previously submitted service template that one must invoke the `clearPassport()` method to clear the passport for the service request's new journey.

## Examples

Examples are provided to define a service template that may be used to discover a foundation service using the service's desired service interface(s) and optionally one or more service discovery attributes. Examples are provided to show one how to find a service using its service's desired service interface(s):

- without specifying an optional service discovery attribute
- with one or more service discovery attributes which may differentiate services satisfying the same service interface(s)

## Example 1: Find a service satisfying a business interface

To find a service based upon a business interface define a service template that specifies one or more interfaces that the desired service must implement. The following example shows how to define a service template that can be used to discover an Authentication Service without specifying any optional service attributes.

    import com.sas.services.discovery.DiscoveryService;
    import com.sas.services.discovery.ServiceTemplate;
    import com.sas.services.security.AuthenticationServiceInterface;

    ...

    // define a service template that can be used to
    // lookup an Authentication Service
    Class[] desiredServiceTypes = new Class[] {
         AuthenticationServiceInterface.class};

    // create a service lookup template specifying the required
    // service interface(s)
    ServiceTemplate serviceTemplate = new ServiceTemplate(
       desiredServiceTypes);

    // discover a service satisfying the service template
    AuthenticationServiceInterface authenticationService = (AuthenticationServiceInterface)
       DiscoveryService.defaultInstance().findService(serviceTemplate);

## Example 2: Find a service satisfying a business interface and one or more service discovery attributes

An application may desire to find a service that not only satisfies a particular business interface, but also attributes which may be used to differentiate a service from other services satisfying the same interface. When a service is deployed, attributes are added to its service discovery configuration that enable one to locate it based upon the following considerations:

Service Discovery Attributes Available in API Versions
service discovery attribute | 9.1.3 | 9.2
--- | --- | ---
`ID` | yes | yes
`accessibility to remote clients` | yes | yes
`metadata` (CMetadata) | yes | yes
`service's component` (ServiceComponent) | yes | yes
`host` on which a service was deployed | no | yes
`name/value` attributes which a user may have associated to a service deployment, service deployment group, or service | no | yes
`JVM` in which a service was deployed | no | yes
`application's service deployment` (SoftwareComponent) | no | yes
`service group` (Tree) | no | yes

Note that if multiple service discovery attributes are specified that all attributes must be satisfied in order to satisfy the service request template.

Since:
  1.0
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ServiceTemplate()`
  Constructs a default instance.
  `ServiceTemplate(Class[] serviceTypeClasses)`
  Constructs an instance of a service template which defines the type of service that's desired an optional attributes that may be used to distinguish among services that satisfy the same service type.
  `ServiceTemplate(Class[] serviceTypeClasses, ServiceAttributeInterface[] serviceAttributes)`
  Constructs an instance of a service template which defines the type of service that's desired an optional attributes that may be used to distinguish among services that satisfy the same service type.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `clearPassport()`
  Clears the discovery service IDs from the passport.
  `final void`
  `defineServiceTemplate(Class[] serviceTypeClasses, ServiceAttributeInterface[] serviceAttributes)`
  Specifies the service type(s) and optional service attribute(s) that define this service request template.
  `final ServiceAttributeInterface[]`
  `getServiceAttributes()`
  Gets service attributes that are used to distinguish among services that satisfy the same service type(s).
  `final ServiceTypes`
  `getServiceTypes()`
  Gets service capabilities.
  `final boolean`
  `isOkToProcess(String discoveryServiceId, boolean stampPassport)`
  Stamps the discovery passport with the ID of a discovery service which has processed this service request template.
  `final boolean`
  `isSatisfiedBy(RemoteServiceInterface service)`
  Determines whether or not the service satisfies this service template.
  `final String`
  `toString()`
  Gets a string representation of this instance.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### ServiceTemplate

    public ServiceTemplate() throws InitializationException
    Constructs a default instance.
    Throws:
      `InitializationException` - if unable to construct the instance.

  - ### ServiceTemplate

    public ServiceTemplate(Class[] serviceTypeClasses) throws InitializationException
    Constructs an instance of a service template which defines the type of service that's desired an optional attributes that may be used to distinguish among services that satisfy the same service type.
    Parameters:
      `serviceTypeClasses` - Java classes that the service should be, extend, or implement.
    Throws:
      `InitializationException` - if unable to construct the instance.

  - ### ServiceTemplate

    public ServiceTemplate(Class[] serviceTypeClasses, ServiceAttributeInterface[] serviceAttributes) throws InitializationException
    Constructs an instance of a service template which defines the type of service that's desired an optional attributes that may be used to distinguish among services that satisfy the same service type.
    Parameters:
      `serviceTypeClasses` - Java class(es) that the service should be, extend, or implement.
      `serviceAttributes` - Filter criteria that may be used to qualify matches. This parameter should be set to `null` if no additional filter criteria is required to refine requested service types.
    Throws:
      `InitializationException` - if unable to construct the instance.

- ## Method Details

  - ### defineServiceTemplate

    public final void defineServiceTemplate(Class[] serviceTypeClasses, ServiceAttributeInterface[] serviceAttributes) throws InitializationException
    Specifies the service type(s) and optional service attribute(s) that define this service request template. This method may be invoked to clear any previous settings, enabling this service template instance to be re-used.
    Parameters:
      `serviceTypeClasses` - Java class(es) that the service should be, extend, or implement.
      `serviceAttributes` - Filter criteria that may be used to qualify matches. This parameter should be set to `null` if no additional filter criteria is required to refine requested service types.
    Throws:
      `InitializationException` - if unable to construct the instance.

  - ### getServiceTypes

    public final ServiceTypes getServiceTypes()
    Gets service capabilities.
    Returns:
      Service capabilities are expressed in terms of Java classes. representing the type of class a service is, extends, or implements.

  - ### getServiceAttributes

    public final ServiceAttributeInterface[] getServiceAttributes()
    Gets service attributes that are used to distinguish among services that satisfy the same service type(s).
    Returns:
      Service attributes.

  - ### isSatisfiedBy

    public final boolean isSatisfiedBy(RemoteServiceInterface service)
    Determines whether or not the service satisfies this service template.
    Parameters:
      `service` - A candidate service which will be checked to determine if it satisfies all required service types and optional attributes.
    Returns:
      `true` if the service satisfies the requested service template, `false` if it doesn't.

  - ### isOkToProcess

    public final boolean isOkToProcess(String discoveryServiceId, boolean stampPassport)
    Stamps the discovery passport with the ID of a discovery service which has processed this service request template.
    Parameters:
      `discoveryServiceId` - Discovery service ID which has processed a service request using this template.
      `stampPassport` - `true` if the passport should be stamped with the ID if its not currently in in the passport.
    Returns:
      `true` if the discovery service has already processed this request.

  - ### clearPassport

    public final void clearPassport()
    Clears the discovery service IDs from the passport. The passport must be cleared if a request is submitted to the Discovery service that employs a previously submitted service template.

    The passport maintains a set of IDs for each discovery service which processes the service request.

  - ### toString

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