*** This package contains classes that provide Binary Compatibility only, not Source Compatibility ***

Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.

Package com.sas.services.session

Session services.

See:
Description

Interface Summary

RemoteSessionContextStateChangedListener	Causes an object to be notified when its state changes within the session context.
SessionContextInterface	The SessionContextInterface provides a control structure for maintaining state within a bound session and facilitates resource management and context passing.
SessionServiceInterface	The SessionServiceInterface provides a mechanism for creating and accessing session contexts.
SummaryDataInterface	The SummaryDataInterface provides a mechanism for returning session summary information.

Class Summary

SessionContextPermission	This class is used to protect Session Context objects that are stored in the Session Service.
SessionContextStateChangedEvent	Sent to an object that implements RemoteSessionContextStateChangedListener when the object's state changes within the session context; currently, this is when the object is removed from the session context or when the session context is destroyed.
SessionPermission	This class is for various Session Service permissions.
SessionService	The Session Service provides a mechanism for creating and accessing session contexts.
SessionServiceFactory	Factory used to manufacture a session service.
SessionServiceInitializer	Utility used to parse a Session Service XML document to create a configuration.
SessionServiceInitObject	Session Service configuration which may specify the default user context to associate with the root session context and optionally a session context timeout.
SessionServiceProxy	Session Service proxy.
SummaryData	Contains session summary information.

Exception Summary

LockingException

Locking exception thrown when an attempt is made to destroy a locked session context.

Package com.sas.services.session Description

Session services. The Session Service provides a mechanism for creating and accessing session contexts.

Session Services

Overview

Model

Usage

Session Context Sharing

Examples

Overview

Session services provide a mechanism for creating and accessing session contexts. The session context actually provides a control structure for maintaining state within a bound session and facilitate resource management and context passing. It provides a convenience container for passing multiple contexts and for passing other services, such as user and logging services.

Applications can bind objects to a session context, and then use the session context as a convenience container for passing multiple contexts. Objects bound to the session context can be notified when they are removed from the session context or when the session context is destroyed. This notification allows objects to perform any necessary cleanup that may be needed.

Model

Session Service Model

The Session Service provides the services to create and locate session contexts. The session context is the actual control structure for maintaining state. It is a convenience container for passing multiple contexts, as well as other useful service resources such as the user context and the logger.

Deploying the Session Service

The Session Service is a core Foundation Service that is deployed by the Discovery Service. As the Session Service initializes, it discovers the Logging Service and it creates a unique logger for each session context that it initializes. A logger can be obtained from any session context that is created by the Session Service. If the Session Service's deployment configuration is defined with a user context name, the Session Service discovers the User Service and obtains the default user context identified by this name. It then creates a default root session context that is bound to this default user context. If no default user context name is configured, the root session context will still be created but it will not be bound to any user context. This root session context can be used to track shared resources that are global to the application. The initialized logger and default user context can be obtained from this root session context.

Creating Additional Session Contexts

After the services have been deployed and the Session Service has initialized, subsequent session contexts can be created through the Session Service. Multi-session applications can ask the Session Service for a new session context. A new logger is created for each session context that is created. The application requesting the new session context must provide the user context to bind to the session context. The Session Service does not authenticate the user identities. Instead, it is up to the calling application to authenticate the user before asking the Session Service to create the session context. This allows the calling application to authenticate the user and then based on the success or failure of the authentication, it can decide whether or not to create a session context.

Session Context Model

The Session Context is the actual control structure for maintaining state. It is a convenience container for passing multiple contexts, as well as other useful service resources such as the user context and the logger. Objects can be bound to the Session Context based on a name. This resource tracking mechanism incorporates a listener interface to enable cleanup at session destruction. The listener interface allows the object or application to be notified when the session context is destroyed so it can take the necessary action. This model does not require that the bound object terminate when the session context is destroyed, but merely notifies the object so the appropriate action can be taken; this may include cleaning up the object that was bound to the session context or it may not.

Usage

Deployment Configuration

Services are deployed by the Discovery Service based upon a deployment configuration. The "ServiceLoader" deployment utility is used to deploy services and register them with Discovery Service. The deployment configuration is specified in either a SAS Metadata Repository or in a URL accessible input source containing a deployment configuration (queried from a SAS Metadata Repository). The deployment configuration details information describing the service, its initialization data, and how it is to be used within the context of the Discovery Service.

The Foundation Services Manager plug-in of the SAS Management Console can be used to configure the initialization data used by the Session Service. The only initialization data that can be configured for the Session Service is a default user context name. When the Session Service initializes, a root Session Context is automatically created. If the Session Service is configured with a default user context name, the root session context is bound to the user context with that name. If the Session Service is not configured with any initialization data, the root session context will not be bound to any user context when it is initialized.

Using the Discovery Service

Services are deployed via the Discovery Service, based upon a deployment configuration that is specified in either a SAS Metadata Repository or in a URL accessible input source containing a deployment configuration (queried from a SAS Metadata Repository). When the Discovery Service initializes the Session Service, configuration information is parsed, and the Session Service creates the root Session Context with the specified user context. Once the Session Service is obtained, it can be used to access existing session contexts or create new session contexts. The session context is the actual control structure used for maintaining state and context information.

Session Context Sharing

The session context is a convenience container that can be used for passing multiple contexts among applications. If multiple applications are sharing the same session context, the session context lifecycle needs to be managed so that it is not destroyed before all the applications are done with it. To aid in lifecycle management, the session context supports multiple locks. Each application that is using the session context should invoke the lock(String applicationName) method to obtain a lock on the session context. When the session context is locked, it cannot be destroyed. When each application is done with the session context, it should invoke the destroy() method to free any resources. If there are no locks on the session context, the destroy will succeed and all the resources will be freed. If any other application still has a lock, the destroy will fail with a com.sas.services.session.LockException. The destroy will only succeed if all locks have been removed from the session context. If each application follows these suggestions, the session context should be cleaned up when the last application invokes destroy. A code example follows:

 import com.sas.services.session.LockException;
 import com.sas.services.session.SessionContextInterface;
 SessionContextInterface sessionContext;
 // This example assumes that the session context
 // has already been initialized by the application.
 // After the application is initialized, it should
 // lock the session context so that it cannot be destroyed
 // by another application
 lockObject = sessionContext.lock("com.sas.services.publish");
 ....
 .... // other processing
 ....
 // When the application is terminating, it should
 // unlock the session context and attempt to destroy it.
 // It should catch the LockException which will occur
 // if the session context is still locked by other applications.
 sessionContext.unlock(lockObject);
 try
 {
    sessionContext.destroy();
 }
 catch (com.sas.services.session.LockingException e)
 {
    // log the exception
 }
 

The lock(String applicationName) method takes an application name as a parameter. This will be used by the session context for logging and monitoring purposes. To ensure that the application name is unique, it is suggested that SAS applications use a name with the following form, com.sas.componentName.applicationName.

Examples

The following code example uses a metadata source that will obtain an OMA compliant service deployment configuration from a URL accessible file. The "ServiceLoader" deployment utility is used to deploy the Session service and register it with the Discovery Service. Once the services have been deployed, the local discovery service is ready to service requests to find services. The Session Service is discovered, and then used to dynamically create a session context.

 import com.sas.services.InitializationException;
 import com.sas.services.discovery.DiscoveryService;
 import com.sas.services.discovery.MetadataSourceInterface;
 import com.sas.services.discovery.ServiceLoader;
 import com.sas.services.discovery.ServiceNotAvailableException;
 import com.sas.services.discovery.URLMetadataSource;
 import com.sas.services.session.SessionServiceInterface;
 import com.sas.services.session.SessionContextInterface;
 import java.rmi.RemoteException;
 ...
 // obtain the local discovery service
 final DiscoveryServiceInterface discoveryService =
    DiscoveryService.defaultInstance();
 //
 // create a metadata source for a URL accessible file
 //
 final String fileUrl  = "file:/C:/dept/bip/sas_metadata_services_core.xml";
 final URL metadataUrl = new URL(fileUrl);
 final MetadataSourceInterface metadataSource = new URLMetadataSource(
    metadataUrl,
    softwareComponentName,
    deploymentGroupName);
 // use the ServiceLoader deployment utility to deploy the services
 // and register them with the Discovery Service.
 ServiceLoader.deployServices(
    metadataSource,
    discoveryService);
 final Class[] desiredServiceTypes = new Class[] {
          com.sas.services.session.SessionServiceInterface.class
  SessionServiceInterface sessionService = null;
  SessionContextInterface sessionContext = null;
  UserContextInterface    userContext    = null;
  try
  {
     _sessionService =   (SessionServiceInterface)discoveryService.findService(
        new ServiceTemplate(desiredServiceTypes, null));
  }
  catch (ServiceNotAvailableException e)
  {
     // do something with exception
  }
  try
  {
     // This example assumes that by this point, the application
     // has already created the user context that it wants to bind
     // with this session context. For more details on how to create
     // a user context, see the User Services documentation.
     // use the Session Service to create a new session context
     sessionContext = sessionService.newSessionContext(userContext);
  }
  catch (InitializationException initException)
  {
     // Do something with this exception.
  }
  catch (RemoteException remoteException)
  {
     // Do something with this exception.
  }
 

This example demonstrates how to obtain the logger from the session context. The logger obtained from the session context has a logging context of "com.sas.services.session.SessionContext". When this logger is used to send messages to the log, this default logging context will be associated with the message. The logging context can be overridden by explicitly providing a logging context on any of the logger methods.

     LoggerInterface logger;
     SessionContextInterface sessionContext;
     try
     {
         // this example assumes that the Session Service was already discovered
         // and that it was used to create or obtain the session context.
         logger = sessionContext.getLogger();
     }
     catch (RemoteException e)
     {
         // do something with this exception.
     }
     // do not provide any logging context, so that the
     // default logging context of "com.sas.services.session.SessionContext"
     // will be associated with the message.
     logger.info("Logging with the default logger.");
     // override the logging context by explicitly providing
     // a logging context that is the fully-qualified name of the class
     logger.info(MyApplication.class.getName(), "Overriding the logging context.");
 

*** This package contains classes that provide Binary Compatibility only, not Source Compatibility ***

Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.