Establishing a Connection

The connect method and its parameters

The communications link between an application and an OLAP service is through a CORBA implementation, as described in Chapter 1. The method that makes the connection is the connect method in ConnectionManager, and it requires the following parameters:

• The CORBA stub that identifies the OLAP service

• A Properties object that holds connection parameters

To establish a connection, complete the three steps described in this topic.

Note that the connect method is overloaded. There is an alternative version that accepts a third argument, which is the Locale for the connection. See the Oracle9i OLAP Services OLAP API Reference for details about this version of the connect method.

Step 1: Getting the CORBA stub for the first connect method parameter

The communications link between an application and an OLAP service is through a CORBA implementation, as described in Chapter 1. The method that makes the connection is the connect method on ConnectionManager, and it requires two parameters.

The first parameter to the connect method is a CORBA stub. This is a Java object that resides on the application computer and represents the OLAP service to which the connection will be made. Your application must use a CORBA naming service to obtain the stub. Oracle provides a CORBA naming service for use on most platforms. However, on some platforms the VisiBroker naming Service called Smart Agent is used. See the read me file for your installation of OLAP Services to find out which naming service is appropriate in your environment. If you will use Smart Agent, see Appendix B for coding information.

The following sample code for getting the stub uses the Oracle CORBA naming service and the Java Naming and Directory Interface (JNDI). The code uses the following three classes, which are in the Java Development Kit supplied by Sun Microsystems:

• javax.naming.InitialContext

• javax.naming.Context

• java.util.Hashtable

In addition, the code uses a constant from the ServiceCtx class, which resides in an Oracle CORBA naming service jar file that is supplied with your Oracle installation. See Appendix A for details.

The sample code specifies the following information:

• The URL that locates the target Oracle database for the connection. The URL has the following components, which are separated by colons.

  The prefix sess_iiop

  The host name. In the sample code, it is //lab1.us.oracle.com

  The listener port number for IIOP services. In the sample code, it is 2481.

  The system identifier (SID) for the Oracle database instance. In the sample code, it is bm1212.

• The object name for the OLAP service that will accept the connection. The name includes its directory name in the namespace and the name of the published object. In the sample code, it is /BI/OLAPService.

• The user ID for the database connection. In the sample code, it is hepburn.

• The password for the database connection. In the sample code, it is tracey.

You can find out the information to specify for your own environment by talking to the OLAP Services database administrator. For detailed information about the syntax of the specifications, see the Oracle CORBA Developer's Guide and Reference.

import org.omg.CORBA.Object;
import oracle.aurora.jndi.sess_iiop.ServiceCtx;
import javax.naming.Context;
import javax.naming.InitialContext;
import java.util.Hashtable;

String serviceURL = "sess_iiop://lab1.us.oracle.com:2481:bm1212";
String objectName = "/BI/OLAPService";
String useridValue = "hepburn";
String passwordValue = "tracey";

// Make hashtable to hold environment parameters for initial context
Hashtable env = new Hashtable();
env.put(Context.URL_PKG_PREFIXES, "oracle.aurora.jndi");
env.put(Context.SECURITY_PRINCIPAL, useridValue);
env.put(Context.SECURITY_CREDENTIALS, passwordValue);
env.put(Context.SECURITY_CREDENTIALS, ServiceCtx.NON_SSL_LOGIN);

// Get the CORBA stub for the OLAP service 
javax.naming.Context ic = new InitialContext(env);
org.omg.CORBA.Object serviceStub = (org.omg.CORBA.Object)
       (ic.lookup(serviceURL + objectName));

Step 2: Creating a Properties object for the second connect method parameter

The second parameter to the connect method on ConnectionManager is a Java Properties object that holds the parameters for the connection.

The following sample code adds user ID and password parameters to a Properties object called connParams. Note that the access privileges that are granted to the user ID determine the scope of the data that will be visible in the application.

Properties connParams = new Properties();
String useridName = "UserID";
String useridValue = "hepburn";
String passwordName = "Password";
String passwordValue = "tracey";
connParams.put(useridName, useridValue);
connParams.put(passwordName, passwordValue);

If an application must prompt the user for information to be used as connection parameters, it can call the getConnectionParameterInfo method on ConnectionManager. This method returns a list of ConnectionParameterInfo objects, each of which describes one parameter. Then, the application can call methods on the ConnectionParameterInfo objects to get information about the parameters. Using this information, the application can prompt the user to specify parameter values for the connection, and the application can fill in the Properties object appropriately.

The following sample code prints the name and description for each parameter, just to illustrate how to work with a list of ConnectionParameterInfo objects.

ConnectionManager cm = ConnectionManager.init();
List cpiList = cm.getConnectionParameterInfo(serviceStub, new Properties());
Iterator conIt = cpiList.iterator();
System.out.println("Connection Parameters:");
while (conIt.hasNext()) {
    ConnectionParameterInfo cpi = (ConnectionParameterInfo) conIt.next();
    System.out.println("\tName : " + cpi.getName() + "\tDescription : " +
                       cpi.getDescription());
}

Step 3: Making the connection using the connect method

To make a connection, you initialize a ConnectionManager and call the connect method on it. When calling the connect method, you pass the following two parameters, which are described earlier in this topic:

• The CORBA stub (called serviceStub in earlier code examples)

• The Properties object that holds the connection parameters (called connParams in an earlier code example)

The following lines of code make a connection for a standalone application.

ConnectionManager cm = ConnectionManager.init();
Connection conn = cm.connect(serviceStub, connParms);