*** 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.connection.platform

Provides a connection factory configuation for use with SAS Foundation Services.

See:
Description

Interface Summary

PlatformConnectionFactoryInterface

A specialization of the user interface for connection factories.

Class Summary

PlatformConnectionFactoryConfiguration	A connection factory configuration that describes a server or a pool of servers to connect to using meta data in the BIP Information Service.
PlatformConnectionFactoryManager	A factory of connection factories.

Exception Summary

MissingIdentityException

This exception is thrown during a connection request if the UserContextInterface presented by the caller does not contain a UserIdentityInteface for one of the authentication domains supported by the connection factory.

Package com.sas.services.connection.platform Description

Provides a connection factory configuation for use with SAS Foundation Services.

Connection Factory Configuation using SAS Foundation Services

Classes in the com.sas.services.connection.platform package allow the connection service to integrate with SAS Foundation Services. In particular, you can use the information service to configure a connection factory, and you can use the user service to provide user identities when you request connections from the factory.

The discussion contained in this document assumes you are already familiar with basics of connection service usage.

The class from the information service that can be used to configure a connection factory is com.sas.services.information.metadata.LogicalServerInterface . Objects of this class are abstract representations of IOM servers, load-balancing clusters, or connection pools defined in a metadata repository supported by the information service. The connection service can use these objects to determine how to connect to IOM servers.

The class from the user service that can be used to establish the identity when requesting a connection from a connection factory is com.sas.services.user.UserContextInterface . Objects of this class encapsulate all identities (e.g. user name/password pairs) associated with a user. A connection factory can search through the list of identities until it finds one that can be used with the connection factory.

Here is a simple example showing how these classes can be used with the connection service. Exception handling and code structuring elements have been omitted for brevity.

 LogicalServerInterface logicalServer = ...
 ConnectionFactoryConfiguration cxfConfig = new PlatformConnectionFactoryConfiguration(logicalServer);
 PlatformConnectionFactoryManager cxfManager = new PlatformConnectionFactoryManager();
 PlatformConnectionFactoryInterface cxf = cxfManager.getPlatformFactory(cxfConfig);
 UserContextInterface cxfUser = ...
 ConnectionInterface cx = cxf.getConnection(cxfUser);
 ...
 cx.close();
 cxf.getAdminInterface().destroy();
 

Connection Factory Lifecycle Issues

A connection factory configured as shown above will automatically destroy itself when the connection to the repository containing the logical server is closed. This feature ensures that all resources associated with a user (including the user's connections to repositories and to IOM servers) are released when the user terminates his session with the session service.

You must be sure you are getting your logical server through a connection to the metadata repository that was established by a user that will remain "logged in" for at least until you are done with your connection factory. The connection service has a feature that allows you to reassociate a logical server from a user with a short (or unknown) lifespan to a user with a long lifespan. In the example below, assume logicalServer is associated with a user with an unknown lifespan, and also assume immortalUser has a lifespan longer than the desired lifespan of the connection factory.

 LogicalServerInterface logicalServer = ...
 UserContextInterface immortalUser = ...
 ConnectionFactoryConfiguration cxfConfig = new PlatformConnectionFactoryConfiguration(logicalServer,immortalUser);
 PlatformConnectionFactoryManager cxfManager = new PlatformConnectionFactoryManager();
 PlatformConnectionFactoryInterface cxf = cxfManager.getPlatformFactory(cxfConfig);
 UserContextInterface cxfUser = ...
 ConnectionInterface cx = cxf.getConnection(cxfUser);
 ...
 cx.close();
 cxf.getAdminInterface().destroy();
 

Metadata Repository Security Issues

A connection factory can read configuration information from a metadata repository. The connection to the metadata repository is associated with a user, and that user must have sufficient permission to read all the necessary information. This information may include logins needed for connection pooling. The connection service has a feature that allows you to reassociate a logical server from a user with a low (or unknown) level of privilege for reading metadata to a user with a high level of privilege. Such a user is called a privileged user or pool administrator. In the example below, assume logicalServer is associated with a user with an unknown level of privilege, and also assume privilegedUser has a high level of privilege.

Note that the lifecycle issues discussed above still apply. The privileged user must also have a lifespan at least equal to the desired lifespan of the connection factory.

 LogicalServerInterface logicalServer = ...
 UserContextInterface privilegedUser = ...
 String privilegedUserName = privilegedUser.getName();
 ConnectionFactoryConfiguration cxfConfig = new PlatformConnectionFactoryConfiguration(logicalServer,privilegedUserName);
 PlatformConnectionFactoryManager cxfManager = new PlatformConnectionFactoryManager();
 PlatformConnectionFactoryInterface cxf = cxfManager.getPlatformFactory(cxfConfig);
 UserContextInterface cxfUser = ...
 ConnectionInterface cx = cxf.getConnection(cxfUser);
 ...
 cx.close();
 cxf.getAdminInterface().destroy();
 

If a connection factory reads configuration information with a metadata server connection that is associated with a user that does not have sufficient permission to read all the metadata objects, the connection factory will attempt to configure itself based only on the metadata objects it can read. This feature allows two applications to configure connection factories using the same LogicalServer object and get different connection factory behavior. For example, a desktop application could configure a connection factory without providing a privileged user name, and that application would get a standard connection factory. A web application could then configure a connection factory, providing a privileged user name, and that application would get a pooling connection factory.

Applications should not use a connection to a metadata server associated with an unrestricted user to read connection factory configuration information. Unrestricted users have permission to read all login objects in metadata, but the metadata server obscures the password attributes on the login objects before sending them over the connection. A pooling connection factory must be able to read the password to make connections to servers. A pooling connection factory configured by an unrestricted user will not be able to connect to servers.

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