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

com.sas.services.deployment
Class PlatformServices

java.lang.Object
  |
  +--com.sas.services.deployment.PlatformServices

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 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 3: 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 4: 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(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	setDeploymentConfiguration(URL deploymentConfigurationURL) Deprecated. This operation is no longer supported.
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.

Methods inherited from class java.lang.Object

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

Method Detail

setDeploymentConfiguration

public static final void setDeploymentConfiguration(URL deploymentConfigurationURL)
                                             throws ServiceException

Deprecated. This operation is no longer supported.

Constructs an instance using the specified foundation service deployment configuration file.

Parameters:

deploymentConfigurationURL - URL to a file specifying 1..* foundation service deployments.

Throws:

ServiceException - if an invalid file is specified.

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.

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.

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.

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.

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