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

com.sas.services.deployment
Class PlatformServices

com.sas.services.deployment.PlatformServices

public class PlatformServices

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

static void	addServicesDeploymentListener(ServicesDeploymentEventListenerInterface listener) Adds a services deployment listener which is interested in being notified of deployment state transitions.
static RemoteServiceInterface	findService(ServiceTemplate serviceTemplate) Finds a service satisfying the specified service template.
static Services	findServices(ServiceTemplate serviceTemplate, int maxNumMatches, Services services) Finds all services satisfying the specified service template up to the specified maximum.
static RemoteServiceInterface	findServiceUsingId(java.lang.String serviceId) Finds a service associated with the specified service ID.
static DiscoveryServiceInterface	getDiscoveryService() Gets the local discovery service.
static Services	getServices() Gets all available services.
static void	lookupRemoteServices() Lookup remote foundation discovery services using the deployments specified in the configuration file.
static void	removeServicesDeploymentListener(ServicesDeploymentEventListenerInterface listener) Removes a services deployment listener which is no longer interested in being notified of deployment state transitions.
static void	setEnvironment(Environment environment) Specified the environment resources to be used by this facade.
static boolean	setJAASAppConfigurationEntry(javax.security.auth.login.AppConfigurationEntry[] appConfigurationEntries) Updates this resource environment to use the specified JAAS	static 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.

Method Detail

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(javax.security.auth.login.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(java.lang.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.

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