Using the Java Connection Factory

Overview of the Java Connection Factory

The Java Connection Factory interface of the Connection Service provides the following features:

IOM Bridge connections to IOM servers
scalability through pooling and server failover
support for load-balancing spawners

Configuring the Java Connection Factory and obtaining a connection are the first steps in using an IOM server. To connect to an IOM server, you can use methods in the classes that implement the ConnectionFactoryInterface interface.

Supplying Connection Information

In a Java client program, there are several ways to supply the Java Connection Factory with the information that it needs in order to connect to an IOM server:

You can place the required information directly in the client program. For details, see Connecting with Directly Supplied Server Attributes . Connections can be made one at a time on an as-needed basis, or you can set up a pool of connections (see Pooling with Directly Supplied Server Attributes ) to be shared and reused across multiple Java client applications and multiple connection requests. Connection pooling is secure, and it can dramatically reduce connection times in environments where one or more client applications make frequent but brief requests for IOM services.
Alternatively, you can obtain the required information from a managed, secure SAS Metadata Server using indirect logical names. The Java Connection Factory supports metadata access from a SAS Metadata Server. For details, see Connecting with Server Attributes Read from a SAS Metadata Server . When you use this method, the metadata server administrator decides whether to use connection pooling. (See Pooling with Server Attributes Read from a Metadata Server.)
If you configure SAS Foundation Services, then you can obtain the required information from a SAS Metadata Server by using the Information Service. For details, see Connecting with Server Attributes Read from the Information Service . When you use this method, the metadata server administrator decides whether to use connection pooling. (See Pooling with Server Attributes Read from a Metadata Server.)
In Windows environments, you can create a connection to a local server without specifying connection information. For details, see Connecting to a Zero-Configuration Workspace Server.

Using Connection Factory Configurations, Connection Factories, and Connections

To create a connection to an IOM server, perform the following steps:

Create the connection factory configuration. You must configure a connection factory to identify the location and type of IOM server to which you want to connect. For example, to create a connection to host foo.bar.abc.com at port 1234, use the following code:
```
String classID = Server.CLSID_SAS;
String host = "foo.bar.abc.com";
int port = 1234;
Server server = new BridgeServer(classID,host,port);
ConnectionFactoryConfiguration cxfConfig =
   new ManualConnectionFactoryConfiguration(server);
```
Create the connection factory. After creating a connection factory configuration, you must find or create a connection factory that matches the configuration. The connection factory manager maintains a set of connection factories, and, if one of these connection factories matches your configuration, that factory is returned. Otherwise, the connection factory manager creates a new connection factory and returns it. For example, to create a connection factory that matches the connection factory configuration in step 1, use the following code:
```
ConnectionFactoryConfiguration cxfConfig = ...
ConnectionFactoryManager cxfManager =
   new ConnectionFactoryManager();
ConnectionFactoryInterface cxf =
   cxfManager.getFactory(cxfConfig);
```
Create the connection. To obtain a connection to the IOM server, you must provide a user name and a password that are valid on the server. For example, to get a connection from the connection factory that you created in step 2, use the following code:
```
ConnectionFactoryInterface cxf= ...
String userName = "myName";
String password = "mySecret";
ConnectionInterface cx =
   cxf.getConnection(userName,password);
```
Narrow the connection. When a connection factory returns a connection, the connection is a generic interface for communicating with remote objects on the server. You can convert the generic interface to a server-specific interface through a mechanism called narrowing. Narrowing is equivalent to the casting mechanism that is used with remote object references. The connection factory contains classes that are necessary to narrow a generic interface reference to a workspace server reference. To narrow the connection that is obtained in step 3, use the following code:
```
ConnectionInterface cx = ...
org.omg.CORBA.Object obj = cx.getObject();
com.sas.iom.SAS.IWorkspace iWorkspace =
   com.sas.iom.SAS.IWorkspaceHelper.narrow(obj);
```
End the connection. After you are finished using a connection that you have obtained from the Java Connection Factory, you must return it to the factory by calling the close() method on the connection. For details, see Closing a Connection to the Java Connection Factory. This process is the same whether you are using connection pooling or making single connections. It is also the same whether you provide information about the IOM servers directly in your client program or indirectly using a metadata server.
Shut down the connection factory. When you are finished with the instance of the Java Connection Factory itself and you no longer need to request connections from it, you must shut it down by calling the shutdown() method or the destroy() method. For details, see Shutting Down the Java Connection Factory.

Connection Factory Logging

The Java Connection Factory logs diagnostic and status messages and writes them to output for use in debugging or performance monitoring. For details, see Logging Java Connection Factory Activity .