Connection Classes in the OLAP API

Overview of the connection classes

The OLAP API connection classes are in the oracle.express.connection package. This topic focuses on the three important classes in the package: ConnectionManager, Connection, and ConnectionParameterInfo. One of the remaining classes, Database, is discussed briefly in Chapter 4.

ConnectionManager class

A ConnectionManager establishes a connection when you call its connect method. However, before you make this call, you must initialize the ConnectionManager.

To initialize a ConnectionManager, you use the init method in ConnectionManager. Because the method is overloaded, you can use either of its two forms. One form is appropriate for standalone Java applications. The other form is appropriate for Java applets.

• init(), which initializes the singleton ConnectionManager that is appropriate for use by all standalone Java applications. This ConnectionManager uses the singleton default ORB.

• init(java.applet.Applet applet), which creates a new ConnectionManager that is appropriate for use by the specified applet. This ConnectionManager uses the ORB that was initialized with the applet.

For simplicity, the OLAP API documentation uses the term "application" to refer to both standalone applications and applets.

Once you have initialized the ConnectionManager, use the connect method in ConnectionManager to establish the connection. One of the parameters to the connect method is a java Properties object that holds the connection parameters (such as user name and password) for the connection.

A ConnectionManager can also provide information about the appropriate connection parameters through its getConnectionParameterInfo method. The reason that this method can be useful is because the parameters that are appropriate for connecting to one OLAP service might be different from the parameters that are appropriate for connecting to another OLAP service. If there is any reason to believe that more than the usual user ID and password parameters are required, then you can use the getConnectionParameterInfo method to find out what is needed.

The following table presents an overview of the methods in ConnectionManager.

Method	Return Value
init()	The singleton ConnectionManager for Java applications.
init(java.applet.Applet applet)	A new ConnectionManager for the specified Java applet.
getConnectionParameterInfo	A List of ConnectionParameterInfo objects, each of which represents a parameter that is relevant for making a connection to a particular OLAP service.
connect	A Connection object that represents a connection between an application and an OLAP service.
getOpenConnections	The Set of Connection objects that were created through this ConnectionManager and that are currently active.

For sample code that uses the ConnectionManager class, see "Step 2: Creating a Properties object for the second connect method parameter" and "Step 3: Making the connection using the connect method".

Connection class

A Connection object represents a connection between an application and an OLAP service, which is a child process of an Oracle database instance. You create a Connection object when you call the connect method on a ConnectionManager.

Most of the methods on Connection merely provide information about the OLAP service. For example, one method returns the name of the host computer, and another method returns the name of the OLAP service.

The following table presents the most important methods in the Connection class.

Method	Return Value
close	Closes the connection.
isOpen	A boolean value that indicates whether the connection is currently active.
getDefaultDatabase	A Database object that represents the Oracle database instance that is the parent of the OLAP service for the connection. Use this method when creating an MdmMetadataProvider, as described in Chapter 4.

For sample code that uses the Connection class, see "Step 3: Making the connection using the connect method".

ConnectionParameterInfo

A ConnectionParameterInfo object holds information about a single parameter that can be used for making a connection.

Before making a connection, you can call the getParameterInfo method on the ConnectionManager in order to discover the connection parameters that are appropriate to the configuration of a particular OLAP service. The getParameterInfo method interrogates the OLAP service and returns a List of ConnectionParameterInfo objects, one for each appropriate parameter. You can then call the methods on each ConnectionParameterInfo object to find out the name of the parameter, whether it is required or optional, and the possible choices for the values of the parameter.

With this information, you can present choices to an end user through a graphical user interface, and collect the connection parameter information that is appropriate for that user. Having assembled the information to be specified, you can use the put method on a Properties object to store all the parameter names and values in the Properties object. Finally, you can pass the Properties object to the connect method on the ConnectionManager.

Discovering appropriate parameters for making a connection can be an iterative process. For example, you might call the getConnectionParameterInfo method once specifying an empty Properties object, but after you discover the properties that are relevant, you might make another call. This time you specify the Properties object populated with the parameters and values that were identified by the first call. Depending on the parameters and values specified, the second call to the getConnectionParameterInfo method might return a longer list of appropriate parameters that you can specify when making the connection.

The following table presents an overview of the methods on a ConnectionParameterInfo object. Each ConnectionParameterInfo object provides information about a single parameter.

Method	Return Value
getName	The name of the parameter.
getDescription	The description of the parameter.
getChoices	An array of String values that includes every valid value that an application can specify for the parameter.
getValue	The default value for the parameter.
isRequired	A boolean value that indicates whether the parameter is required.

For sample code that uses the ConnectionParameterInfo class, see "Step 2: Creating a Properties object for the second connect method parameter".