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

      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:

    • 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:

    • 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:

    • 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.