Using 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 Properties. Connections can be made one at a time on an as-needed basis; or, you can set up a pool of connections (see Supplying Connection Pooling Features Directly in the Source Code) 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 Properties Read from a SAS Metadata Server. When you use this method, the decision about whether to use connection pooling is made by the metadata server administrator. (See Using Pooling and a Metadata Server.)
  
  
• You can also obtain the required information from a managed, secure LDAP metadata directory using indirect logical names. The Java Connection Factory supports metadata access from LDAP. For details, see Connecting with Server Properties Read From an LDAP Server. When you use this method, the decision about whether to use connection pooling is made by the metadata server administrator. (See Using Pooling and a Metadata Server.)
  
  
• If you configure SAS Foundation Services, then you can obtain the required information from an LDAP server or a SAS Metadata Server using the Information Service. For details, see Connecting with Server Properties Read from the Information Service. When you use this method, the decision about whether to use connection pooling is made by the metadata server administrator. (See Using Pooling and a Metadata Server.)

Using Connection Factory Configurations, Connection Factories, and Connections

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

1. 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:

   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);
   

2. 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);
   

3. 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 you created in step 2:

   ConnectionFactoryInterface cxf = ...
   String userName = "myName";
   String password = "mySecret";
   ConnectionInterface cx =
     cxf.getConnection(userName,password);
   

4. 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 used with remote object references. The connection factory contains classes necessary to narrow a generic interface reference to a workspace server reference. Narrowing to other server interfaces will require additional software packages. To narrow the connection 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);
   

5. 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 Returning a Connection to the 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.

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