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

Package com.sas.services.deployment

# Class PlatformServices

java.lang.Object
com.sas.services.deployment.PlatformServices

@SASScope("ALL") @BinaryCompatibilityOnly public class PlatformServices extends Object
This class serves as a facade to an application's deployment of foundation services providing the capability to specify a service configuration and to start and terminate services.

Metadata describing an application's foundation services deployment may be queried from either a SAS Metadata Repository or from an XML file that contains metadata exported from a SAS Metadata Repository. The Foundation Services Manager plug-in to the SAS Management Console is used to manage service deployment metadata.

## Example 1: Deploy Foundation Services queried from a SAS Metadata Repository

The best practice recommendation is to store the application's foundation services metadata in the repository and query the repository for the metadata when an application wishes to deploy foundation services. This ensures that the foundation services deployment configuration can be managed using the Foundation Services Manager plug-in and also ensures that an application is using the current configuration.

This example assumes that one has defined a foundation services deployment configuration in the SAS Metadata Repository using the Foundation Services Manager plug-in to the SAS Management Console.

     try {

        // Refer to the javadoc for com.sas.services.deployment.MetadataSourceFactory
        // for details on defining the properties describing a
        // metadata repository source.

        Properties properties = new Properties();
        properties.load("D:/xxx/services.config"));

        MetadataSourceInterface[] localServiceDeployment =
           new MetadataSourceInterface[] {
              MetadataSourceFactory.newMetadataSource(properties)
           };

        PlatformServicesConfiguration servicesConfiguration =
           new PlatformServicesConfiguration(
              localServiceDeployment,
              null); // we aren't looking up any remotely deployed services

        PlatformServices.setServicesConfiguration(servicesConfiguration);

        // Refer to Example 3 for details on how
        // to start the foundation services defined in the service configuration

     }
     catch (IllegalArgumentException e) {
        // handle the exception
     }
     catch (IOException e) {
        // handle the exception
     }

## Example 2: Deploy Foundation Services using metadata queried from an XML file

An alternative approach is to export an application's foundation services deployment metadata from a SAS Metadata Repository to a UTF-8 encoded XML file. This file can be used to deploy services by creating a URLMetadataSource. This approach is only suggested if an application has a generic configuration which is intended to be customized at runtime after the services have been deployed. If service configurations are likely to change, then one should follow the best practice of persisting the metadata in the repository and querying it from the repository when one needs to deploy services.

This example assumes that one has defined a foundation services deployment configuration in the SAS Metadata Repository and exported it to an XML file using the Foundation Services Manager plug-in to the SAS Management Console.

     try {

        // create a URL to the XML file containing an application's
        // foundation services deployment metadata that has been
        // exported from a SAS Metadata Repository using the
        // Foundation Services Manager plug-in to the SAS Management Console

        URL serviceDeploymentURL = new URL(
           "file:///D:/xxx/foundation_services_config.xml");
        MetadataSourceInterface[] localServiceDeployment =
           new MetadataSourceInterface[] {
              new URLMetadataSource(serviceDeploymentURL)
           };

        PlatformServicesConfiguration servicesConfiguration =
           new PlatformServicesConfiguration(
              localServiceDeployment,
              null); // we aren't looking up any remotely deployed services

        PlatformServices.setServicesConfiguration(servicesConfiguration);

        // Refer to Example 3 for information on
        // how to optionally define a resource environment which will be
        // used to configure the services when they are started.

     }
     catch (IllegalArgumentException e) {
        // handle the exception
     }
     catch (IOException e) {
        // handle the exception
     }

## Example 3: Optionally Define a Resource Environment

A resource `environment` may be passed to the services when they are started. The environment may be used to define the JAAS application login configuration that the services should use.

        import com.sas.services.deployment.Environment;

        Environment environment = new Environment();
        // optionally configure the environment resources
        ...

        // Any services started in this JVM will use this environment
        PlatformServices.setEnvironment(environment);

        // Refer to Example 4 for details on how
        // to start the foundation services defined in the service configuration

## Example 4: Start Services

Foundation services can be started using the method `startServices` which first invokes `startLocalServices` which is used to instantiate services and then `lookupRemoteServices` which attempts to lookup foundation services that were remotely instantiated in another application. Note that services should be terminated when the application is terminated or when they are no longer needed.

## Example 5: Terminate Services

Invoke `terminateServices` to terminate all locally instantiated services and eliminate references to any remotely discovered services. Services should be terminated when they are no longer needed or at the time the application is terminated.

Since:
  1.1

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static final void`
  `addServicesDeploymentListener(ServicesDeploymentEventListenerInterface listener)`
  Adds a services deployment listener which is interested in being notified of deployment state transitions.
  `static final RemoteServiceInterface`
  `findService(ServiceTemplate serviceTemplate)`
  Finds a service satisfying the specified service template.
  `static final Services`
  `findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services services)`
  Finds all services satisfying the specified service template up to the specified maximum.
  `static final RemoteServiceInterface`
  `findServiceUsingId(String serviceId)`
  Finds a service associated with the specified service ID.
  `static final DiscoveryServiceInterface`
  `getDiscoveryService()`
  Gets the local discovery service.
  `static final Services`
  `getServices()`
  Gets all available services.
  `static void`
  `lookupRemoteServices()`
  Lookup remote foundation discovery services using the deployments specified in the configuration file.
  `static final void`
  `removeServicesDeploymentListener(ServicesDeploymentEventListenerInterface listener)`
  Removes a services deployment listener which is no longer interested in being notified of deployment state transitions.
  `static final void`
  `setEnvironment(Environment environment)`
  Specified the environment resources to be used by this facade.
  `static final boolean`
  `setJAASAppConfigurationEntry(AppConfigurationEntry[] appConfigurationEntries)`
  Updates this resource environment to use the specified JAAS `entries`.
  `static final void`
  `setServicesConfiguration(PlatformServicesConfiguration servicesConfiguration)`
  Specifies the services configuration that is to be used by this facade.
  `static void`
  `startLocalServices()`
  Starts foundation services using the deployments specified in the configuration file.
  `static void`
  `startServices()`
  Starts foundation services using the deployments specified in the configuration file.
  `static void`
  `terminateServices()`
  Terminates foundation services that have been locally instantiated and eliminates references to any foundation services that were looked up remotely.

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

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

- ## Method Details

  - ### setServicesConfiguration

    public static final void setServicesConfiguration(PlatformServicesConfiguration servicesConfiguration) throws ServiceException
    Specifies the services configuration that is to be used by this facade.
    Parameters:
      `servicesConfiguration` - The service configuration that is to be deployed. This configuration details the metadata source(s) describing service deployment(s).
    Throws:
      `ServiceException` - if an invalid configuration is specified.

  - ### setEnvironment

    public static final void setEnvironment(Environment environment)
    Specified the environment resources to be used by this facade.
    Parameters:
      `environment` - The environment resources that are to be used by the deployed services.
    See Also:
      - `setJAASAppConfigurationEntry(AppConfigurationEntry[])`

  - ### setJAASAppConfigurationEntry

    public static final boolean setJAASAppConfigurationEntry(AppConfigurationEntry[] appConfigurationEntries) throws ServiceException
    Updates this resource environment to use the specified JAAS `entries`.

    The following code provides a sample that show how one might define an AppConfigurationEntry for a `com.sas.services.security.login.OMILoginModule`.

              import java.util.Map;
              import javax.security.auth.login.AppConfigurationEntry;
              import javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag;

              import com.sas.services.security.login.LoginPropertyConstants;
              import com.sas.services.security.login.OMILoginModule;
              import com.sas.services.Deployment.PlatformServices;

              Map optionsMap = new HashMap(5);
              optionsMap.put(
                LoginPropertyConstants.PROPERTYNAME_HOST,
                "xxx.yyy.com");
              optionsMap.put(
                LoginPropertyConstants.PROPERTYNAME_PORT,
                "8561");
              optionsMap.put(
                "repository",
                "Foundation");
              optionsMap.put(
                LoginPropertyConstants.PROPERTYNAME_DOMAIN,
                "DefaultAuth");

              optionsMap.put(
                LoginPropertyConstants.PROPERTYNAME_DEBUG,
                LoginPropertyConstants.PROPERTYVALUE_FALSE);

              AppConfigurationEntry[] appConfigurationEntries = new AppConfigurationEntry[] {
                 new AppConfigurationEntry(
                    OMILoginModule.class.getName(),
                    LoginModuleControlFlag.OPTIONAL,
                    optionsMap)
                 };

    If a resource environment is not defined, then no action is taken.

    The `Environment` must be set by calling `setEnvironment(Environment)` prior to calling this method or the method to start services.

    Parameters:
      `appConfigurationEntries` - Array of JAAS application configuration `entries` which the should be set in the resource environment.
    Returns:
      `true` if the resource `environment` was updated or `false` if a resource environment is not defined.
    Throws:
      `ServiceException` - if an exception is encountered.
    See Also:
      - `setEnvironment(Environment)`

  - ### addServicesDeploymentListener

    public static final void addServicesDeploymentListener(ServicesDeploymentEventListenerInterface listener) throws ServiceException
    Adds a services deployment listener which is interested in being notified of deployment state transitions.
    Parameters:
      `listener` - Services deployment listener interested in being notified of deployment state changes.
    Throws:
      `ServiceException` - if unable to add a listener.

  - ### removeServicesDeploymentListener

    public static final void removeServicesDeploymentListener(ServicesDeploymentEventListenerInterface listener)
    Removes a services deployment listener which is no longer interested in being notified of deployment state transitions.
    Parameters:
      `listener` - Services deployment listener to be removed.

  - ### startServices

    public static void startServices() throws ServiceException, ServiceLookupFailedException
    Starts foundation services using the deployments specified in the configuration file. Invoking this method will attempt to first instantiate local services using `startLocalServices` after which remote services will be looked up using `lookupRemoteServices`. These methods may be invoked directly instead of this method if one desires.

    Throws:
      `ServiceException` - if unable to cleanly start all services.
      `ServiceLookupFailedException` - if unable to lookup one or more remote discovery services.
    See Also:
      - `setEnvironment(Environment)`

  - ### startLocalServices

    public static void startLocalServices() throws ServiceException
    Starts foundation services using the deployments specified in the configuration file.
    Throws:
      `ServiceException` - if unable to cleanly start all services.
    See Also:
      - `setEnvironment(Environment)`

  - ### lookupRemoteServices

    public static void lookupRemoteServices() throws ServiceException, ServiceLookupFailedException
    Lookup remote foundation discovery services using the deployments specified in the configuration file.
    Throws:
      `ServiceException` - in unable to process the lookup
      `ServiceLookupFailedException` - if unable to lookup one or more remote discovery services.

  - ### terminateServices

    public static void terminateServices() throws ServiceException
    Terminates foundation services that have been locally instantiated and eliminates references to any foundation services that were looked up remotely.
    Throws:
      `ServiceException` - if unable to cleanly terminate all services.

  - ### findServiceUsingId

    public static final RemoteServiceInterface findServiceUsingId(String serviceId) throws ServiceException, ServiceNotAvailableException
    Finds a service associated with the specified service ID.
    Parameters:
      `serviceId` - ID of the desired service.
    Returns:
      Discovered service whose ID matches the specified ID.
    Throws:
      `ServiceException` - is unable to process the request.
      `ServiceNotAvailableException` - if no services were found satisfying the desired service template.

  - ### findService

    public static final RemoteServiceInterface findService(ServiceTemplate serviceTemplate) throws ServiceException, ServiceNotAvailableException
    Finds a service satisfying the specified service template.
    Parameters:
      `serviceTemplate` - Desired service template.
    Returns:
      Discovered service satisfying the specified service template.
    Throws:
      `ServiceException` - is unable to process the request.
      `ServiceNotAvailableException` - if no services were found satisfying the desired service template.

  - ### findServices

    public static final Services findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services services) throws ServiceException, ServiceNotAvailableException
    Finds all services satisfying the specified service template up to the specified maximum. The Services object passed into this method will be updated with any discovered services.
    Parameters:
      `serviceTemplate` - Desired service template.
      `maxNumMatches` - Maximum number of matches desired.
      `services` - Collection to which discovered services will be added.
    Returns:
      Services collection passed into this method.
    Throws:
      `ServiceException` - is unable to process the request.
      `ServiceNotAvailableException` - if no services were found satisfying the desired service template.

  - ### getDiscoveryService

    public static final DiscoveryServiceInterface getDiscoveryService()
    Gets the local discovery service.
    Returns:
      Local Discovery Service or `null`.

  - ### getServices

    public static final Services getServices() throws ServiceException
    Gets all available services.
    Returns:
      Foundation services that are available to this facade.
    Throws:
      `ServiceException` - if unable to determine available services.