SAS 9.1.3 Integration Technologies » Developer's Guide

Using the Java Workspace Factory
Connecting with Directly Supplied Server Attributes
Connecting with Server Attributes Read from an LDAP Server
Language Service Example
Returning a Workspace to the Java Workspace Factory
Java Clients

Connecting with Server Properties Read from an LDAP Server

It is not necessary to place the information needed to connect to an IOM server directly in the client program. As an alternative, the Java Workspace Factory allows you to obtain the needed information from a managed, secure LDAP directory using indirect logical names. The main advantage of this method is that you can maintain and update the IOM server and connection information without changing your client programs. This method also provides additional security features if you are using connection pooling.

To use this method, you must provide the client program with instructions for connecting to the LDAP directory, the logical name of the information you want to search for, and the context within the directory for performing the search. To provide this information, you can create an instance of java.util.Hashtable containing the appropriate properties. For a complete list of the properties you can provide, refer to the documentation for the class javax.naming.Context. Note that the property names are string constants on the javax.naming.Context interface instead of literal strings.

The following five properties are required:

javax.naming.Context.INITIAL_CONTEXT_FACTORY
specifies the name of the main class implementing LDAP. If you are using the LDAP implementation from JavaSoft, this value should be com.sun.jndi.ldap.LdapCtxFactory.
javax.naming.Context.PROVIDER_URL
specifies the URL for the LDAP directory server. This value takes the form ldap://host:port.
javax.naming.Context.SECURITY_AUTHENTICATION
specifies the type of authentication to use when connecting to the LDAP directory server. This value is either none, simple, or strong.
javax.naming.Context.SECURITY_PRINCIPAL
specifies the name, such as the distinguished name of a person object in the directory, under which the connection to the LDAP directory server should be made. This property is not required if the value for javax.naming.Context.SECURITY_AUTHENTICATION is none.
javax.naming.Context.SECURITY_CREDENTIALS
specifies the credentials, such as a password, corresponding to the principal given as the value of javax.naming.Context.SECURITY_PRINCIPAL. This property is not required if the value for javax.naming.Context.SECURITY_AUTHENTICATION is none.

Example

The following example code shows how to initialize and use the Java Workspace Factory using information from an LDAP directory. For information about how to use the workspace object reference, see Language Service Example.

The last two statements in the example show how to dispose of a workspace object reference. For details about this procedure, see Returning a Workspace to the Java Workspace Factory.

import java.io.PrintWriter;
import java.util.Hashtable;
import javax.naming.Context;
import com.sas.iom.WorkspaceConnector;
import com.sas.iom.WorkspaceFactory;
import com.sas.iom.SAS.IWorkspace;

Hashtable ldapProperties = new Hashtable();
ldapProperties.put(Context.INITIAL_CONTEXT_FACTORY,
   "com.sun.jndi.ldap.LdapCtxFactory");
ldapProperties.put(Context.PROVIDER_URL,"ldap://host:port");
ldapProperties.put(Context.SECURITY_AUTHENTICATION,"simple");
ldapProperties.put(Context.SECURITY_PRINCIPAL,distinguished name);
ldapProperties.put(Context.SECURITY_CREDENTIALS,password);

PrintWriter logWriter = new PrintWriter(System.out);
WorkspaceFactory wFactory = new WorkspaceFactory(ldapProperties,
  ldap search context,logical name,false,false,logWriter);
WorkspaceConnector connector = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace = connector.getWorkspace();

< insert workspace usage code here >

wFactory.shutdown();
connector.close();
In the preceding example, exception handling statements have been removed for the sake of clarity. The example will not compile as shown.

Using an Existing Connection to an LDAP Server

If a Java client application is already accessing an LDAP directory server for purposes other than connecting to an IOM server, the Java Workspace Factory can use an existing connection. This mode of operation can reduce the overall number of connections to the LDAP directory server that your Java client application needs to make.

Example

Here is an example showing how to initialize and use the Java Workspace Factory using an existing instance of javax.naming.directory.DirContext. 
import java.io.PrintWriter;
import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.directory.DirContext;
import javax.naming.directory.InitialDirContext;
import com.sas.iom.WorkspaceConnector;
import com.sas.iom.WorkspaceFactory;
import com.sas.iom.SAS.IWorkspace;

Hashtable ldapProperties = new Hashtable();
ldapProperties.put(Context.INITIAL_CONTEXT_FACTORY,
   "com.sun.jndi.ldap.LdapCtxFactory");
ldapProperties.put(Context.PROVIDER_URL,"ldap://host:port");
ldapProperties.put(Context.SECURITY_AUTHENTICATION,"simple");
ldapProperties.put(Context.SECURITY_PRINCIPAL,distinguished name);
ldapProperties.put(Context.SECURITY_CREDENTIALS,password);
DirContext ldapDirectory = new InitialDirContext(ldapProperties);

< insert LDAP directory usage code here >

PrintWriter logWriter = new PrintWriter(System.out);
WorkspaceFactory wFactory = new WorkspaceFactory(ldapDirectory,
   ldap search context,logical name,false,false,logWriter);
WorkspaceConnector connector = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace = connector.getWorkspace();

< insert workspace usage code here >

wFactory.shutdown();
connector.close();
ldapDirectory.close();
In the preceding example, exception handling statements have been removed for the sake of clarity. The example will not compile as shown.

Using Connection Pooling and an LDAP Server

When you connect to an IOM server using information from an LDAP directory, all of the information about the IOM server and how to connect to it is created and maintained by the LDAP directory server administrator. The person developing the Java client application does not need to make a decision about whether to use connection pooling, because that decision is made by the LDAP server administrator.

Using Puddles

The LDAP server administrator can choose to partition a pool of connections into "puddles." Each puddle is a fully functioning connection pool that uses a specific user name and password when connecting to an IOM server. From the perspective of the Java Workspace Factory user, it is not important to distinguish between pools made up of several puddles and pools made up of only one; the Java Workspace Factory automatically routes requests for workspace objects to the most appropriate puddle.

There are two reasons that an LDAP server administrator might choose to partition a connection pool into more than one puddle:

  • To enable connections over multiple domains. For example, the LDAP administrator might place connections to UNIX servers in one puddle and connections to Windows NT servers in another puddle, because the two server types require different login information.

  • To tailor server permissions to particular classes of users. For example, the LDAP administrator might give one puddle read and write access to a table on an IOM server, while giving another puddle only read access. In such a case, the Java Workspace Factory will automatically route a user's request for a workspace object to a puddle that the user is authorized to use (subject to the access control features described in the next section).

Controlling Access to the Java Workspace Factory

The Java Workspace Factory can be configured to control access to the workspace objects it creates. In addition, the Java Workspace Factory can be configured to control access to its administrative functions, such as shutdown(). These access control features are available only when the Java Workspace Factory is using an LDAP server.

When the Java Workspace Factory is constructed, the access control features can be either enabled or disabled. If they are enabled, then all further calls to Java Workspace Factory methods must contain the valid distinguished name and password of a person object that is present on the LDAP directory. The Java Workspace Factory authenticates the distinguished name and password by using them to bind to the LDAP directory that it used to construct the factory.

In performing the authentication, the Java Workspace Factory follows one of two procedures, depending on whether the call is a request for a workspace object or an attempt to shut down the factory.

  • If the call is a request for a workspace object, then the Java Workspace Factory authorizes the caller by comparing the provided distinguished name with the values of the sasAllowedClientDN attributes for all sasLogin objects that have the appropriate logical name.

    The caller is authorized to use a puddle only if one of the following is true:

    • the caller's distinguished name matches a value of the puddle's sasAllowedClientDN attribute

    • the caller's distinguished name is a member of a group whose distinguished name matches a value of the puddle's sasAllowedClientDN attribute.

  • If the call is a request to shutdown() or destroy (), then the Java Workspace Factory authorizes the caller by binding to the LDAP directory server under the provided credentials and searching for all the sasLogin objects that have the appropriate logical name. If the search returns the same set of sasLogin objects that was returned when the factory was constructed, then the call is authorized.

Example

The following example shows how to enable access control for users and administrators and how users and administrators should provide their credentials.

import java.io.PrintWriter;
import java.util.Hashtable;
import javax.naming.Context;
import com.sas.iom.WorkspaceConnector;
import com.sas.iom.WorkspaceFactory;
import com.sas.iom.SAS.IWorkspace;

Hashtable ldapProperties = new Hashtable();
ldapProperties.put(Context.INITIAL_CONTEXT_FACTORY,
   "com.sun.jndi.ldap.LdapCtxFactory");
ldapProperties.put(Context.PROVIDER_URL,"ldap://host:port");
ldapProperties.put(Context.SECURITY_AUTHENTICATION,"simple");
ldapProperties.put(Context.SECURITY_PRINCIPAL,
   administrator 1 distinguished name);
ldapProperties.put(Context.SECURITY_CREDENTIALS,
   administrator 1 password);

WorkspaceFactory wFactory = new WorkspaceFactory(ldapProperties,
   ldap search context,logical name,true,true,null);
WorkspaceConnector connector = wFactory.getWorkspaceConnector(
   user distinguished name,user password,0L);
IWorkspace workspace = connector.getWorkspace();

< insert workspace usage code here >

wFactory.shutdown(administrator 2 distinguished name,
   administrator 2 password);
connector.close();
In the preceding example, exception handling statements have been removed for the sake of clarity. The example will not compile as shown.