Connecting with Directly Supplied Server Properties

In order to make a connection to an IOM server, you must give the Java Workspace Factory specific information about the server and about the desired connection. The quickest and simplest method of providing this information is to place it directly into the client program using name/value pairs in a java.util.Properties object. The following properties can be provided:

host

the IP address of the machine hosting the IOM server or object spawner. This property is required.

port

the TCP port that the IOM server or object spawner is listening to for connections. This property is required.

userName

a valid user name on the host machine. This property is required unless the connection is being made to an object spawner that is running with the -nosecurity option.

password

the password corresponding to userName on the host machine. This property is required unless the connection is being made to an object spawner that is running with the -nosecurity option.

encryptionPolicy

an indicator specifying whether or not IOM Bridge for Java should attempt to negotiate with the server over which encryption algorithm to use and what to do if the negotiations fail. This property is optional. Possible values:

none: do not use encryption. This is the default.
optional: attempt to use encryption but, if algorithm negotiation fails, continue with an unencrypted connection.
required: attempt to use encryption but, if algorithm negotiation fails, fail the connection.

encryptionAlgorithms

the list of algorithms you are willing to use in order of preference. Values in the list should be separated by commas and chosen from sasproprietary, rc2, rc4, des, or tripledes. This property is optional. If no value is specified, then one of the server's preferred algorithms will be used. It is ignored entirely if the value for encryptionPolicy is none.

encryptionContent

specifies which messages should be encrypted if encryption is used. This property is optional, and it is ignored entirely if the value for encryptionPolicy is none. Possible values:

all: encrypt all messages. This is the default.
authentication: encrypt only messages that contain user name and password information.

Example

The Java code in this example demonstrates how to use name/value pairs in a java.util.Properties object to provide information to the Java Workspace Factory and obtain a workspace object reference. 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 when you are done with it. For details on this procedure, see Returning a Workspace to the Workspace Factory.

import com.sas.iom.WorkspaceConnector;
import com.sas.iom.WorkspaceFactory;
import com.sas.iom.SAS.IWorkspace;
import java.util.Properties;

Properties iomServerProperties = new Properties();
iomServerProperties.put("host",host);
iomServerProperties.put("port",port);
iomServerProperties.put("userName",user name);
iomServerProperties.put("password",password);
Properties[] serverList = {iomServerProperties};

WorkspaceFactory wFactory = new WorkspaceFactory(serverList,null,null);
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.

Adding Connection Pooling Features

With just a few changes to the example program above, you can use the Java Workspace Factory to manage a pool of connections to an IOM server rather than a single connection. When set up for connection pooling, the Java Workspace Factory tries to fulfill each client's requests for workspace objects by opening a new workspace object on an existing connection to an IOM server. This is less time consuming than creating a new connection. Behind the scenes, the Java Workspace Factory keeps a configurable number of connections alive at all times. For connection pooling to work properly, you must notify the Java Workspace Factory when you are done using a workspace object by calling com.sas.iom.WorkspaceConnector.close(). For more details, Returning a Workspace to the Workspace Factory.

When a client uses a workspace object, it has exclusive access to the connection serving that workspace object. When the client is finished using the workspace object, the workspace object is closed before the connection is returned to the pool. These actions help preserve the performance and security of the single connection case.

You can also maintain performance standards by spreading a pool of connections over more than one server and then setting an upper limit on the number of connections that each server can contribute to the pool. To specify multiple servers, simply provide a separate java.util.Properties object for each server that is to participate in the pool.

To implement connection pooling, you can specify the following properties for each server in addition to the other server properties described earlier.

sasMaxPerWorkspacePool: the maximum number of connections that the pool will be allowed to make to the server at one time. Factors you should consider when determining a value for this field include the number and type of processors on the machine, the amount of memory present, the type of clients that will be requesting workspaces, and the number of different pools the server participates in. This property is optional. The default value is 10.
sas-RecycleActivationLimit: the number of times a connection to the server will be reused in a pool before it is disconnected ("recycled"). If the value is 0, then there will be no limit on the number of times a connection to the server can be reused. This property is optional. The default value is 0.
sas-ServerRunForever: must be either true or false. If the value is false, then unallocated live connections will be disconnected after a period of time (determined by the value of sas-ServerShutdownAfter) unless they are allocated to a user before that period of time passes. Otherwise, unallocated live connections will remain alive indefinitely. This property is optional. The default value is true.
sas-ServerShutdownAfter: the period of time, in minutes, that an unallocated live connection will wait to be allocated to a user before shutting down. This property is optional and it is ignored if the value of sas-ServerRunForever is true. The value must not be less than 0, and it must not be greater than 1440 (the number of minutes in a day). The default value is 3. If the value is 0, then a connection returned to a pool by a user will be disconnected immediately unless another user is waiting for a connection from the pool.

In addition to the information about the servers that participate in a connection pool, you can also specify information about the pool itself. Again, the information can be provided to the Java Workspace Factory as name/value pairs in a java.util.Properties object. Here is a list of the properties that may be specified.

sasMinSize: the minimum number of connections that the Java Workspace Factory can maintain for a pool (after the initial startup period). This number includes both the connections that are in use and the connections that are idle. This property is optional. The default value is 0.
sasMinAvail: the minimum number of idle connections that the Java Workspace Factory can maintain for a pool. This number includes only the connections that are idle. This property is optional. The default value is 0.

Example

The following example demonstrates how to specify server properties to the Java Workspace Factory and obtain four workspace object references using only two connections to IOM servers. For information about how to use the workspace object reference, see Language Service Example.

The last part of this example shows how to dispose of a workspace object reference when you are done with it. For details on this procedure, see Returning a Workspace to the Workspace Factory.

import com.sas.iom.WorkspaceConnector;
import com.sas.iom.WorkspaceFactory;
import com.sas.iom.SAS.IWorkspace;
import java.util.Properties;

Properties serverProperties0 = new Properties();
serverProperties0.put("host",host 0);
serverProperties0.put("port",port 0);
serverProperties0.put("userName",user name 0);
serverProperties0.put("password",password 0);
serverProperties0.put("sasMaxPerWorkspacePool","1");
serverProperties0.put("sas-RecycleActivationLimit","2");

Properties serverProperties1 = new Properties();
serverProperties1.put("host",host 1);
serverProperties1.put("port",port 1);
serverProperties1.put("userName",user name 1);
serverProperties1.put("password",password 1);
serverProperties1.put("sasMaxPerWorkspacePool","1");
serverProperties1.put("sas-RecycleActivationLimit","2");

Properties[] serverList = {serverProperties0,serverProperties1};

Properties poolProperties = new Properties();
poolProperties.put("sasMinSize","2");

WorkspaceFactory wFactory = new WorkspaceFactory(serverList,poolProperties,null);
WorkspaceConnector connector0 = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace0 = connector0.getWorkspace();
WorkspaceConnector connector1 = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace1 = connector1.getWorkspace();

< insert workspace0 and workspace1 usage code here >

connector0.close();
connector1.close();
WorkspaceConnector connector2 = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace2 = connector2.getWorkspace();
WorkspaceConnector connector3 = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace3 = connector3.getWorkspace();

< insert workspace2 and workspace3 usage code here >

wFactory.shutdown();
connector2.close();
connector3.close();

In the preceding example, exception handling statements have been removed for the sake of clarity.

Waiting for Connections to Become Available

At the time of a client's request for a workspace object, it is possible that all of the available connections in a connection pool will be already allocated to other clients. For example, the Java Workspace Factory may not be able to make an additional connection to a server because it would violate the sasMaxPerWorkspacePool value that has been set for the server. In such cases, the client's request cannot be fulfilled until one of the other clients is done with its workspace object.

To indicate what action you want the Java Workspace Factory to take when a request cannot be fulfilled immediately, you can use a long parameter with the getWorkspaceConnector() method in the client program. The following table shows how the value of the long parameter indicates which action to take:

If the `long` parameter is:	The Java Workspace Factory will:
A number greater than zero	Try to fulfill the request for up to that number of milliseconds. After that number of milliseconds has passed, if no other client has returned its connection to the pool, then the Java Workspace Factory will throw an exception to the caller.
Equal to zero	Try to fulfill the request for an unlimited amount of time.
A number less than zero	Not try to fulfill the request, and throw an exception to the caller immediately.

Logging Java Workspace Factory Activity

The Java Workspace Factory will write diagnostic and status messages to an instance of java.util.PrintWriter if you provide one. The information that the Java Workspace Factory writes to this object will be useful for debugging or performance monitoring.

Example

The following example shows how to make the Java Workspace Factory write messages to standard output:

import com.sas.iom.WorkspaceConnector;
import com.sas.iom.WorkspaceFactory;
import com.sas.iom.SAS.IWorkspace;
import java.io.PrintWriter;
import java.util.Properties;

PrintWriter logWriter = new PrintWriter(System.out);
Properties iomServerProperties = new Properties();
iomServerProperties.put("host",host);
iomServerProperties.put("port",port);
iomServerProperties.put("userName",user name);
iomServerProperties.put("password",password);
Properties[] serverList = {iomServerProperties};

WorkspaceFactory wFactory = new WorkspaceFactory(serverList,null,logWriter);
WorkspaceConnector connector = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace = connector.getWorkspace();

< insert workspace usage code here >

wFactory.shutdown();
connector.close();