SAP BI Java SDK

Package com.sap.ip.bi.sdk.dac.connector

Provides interfaces and implementation for a client to access data from connectors such as the BI Java Connectors.

See:
          Description

Interface Summary
IBIConnection Creates the connection to an OLAP or relational data source.
IBIOlap Serves as an entry point to interfaces that support access to multidimensional metadata and queries.
IBIOlapObjectFinder The OLAP object finder supports the search for OLAP schema objects.
IBIRelational Serves as an entry point to interfaces that support access to relational metadata and queries.
IBIRelationalObjectFinder The relational object finder supports the search for relational schema objects.
 

Class Summary
IBIConnection.Supports Returns true or false, depending on what kind of service the data provider provides.
IBIOlap.Supports Returns Boolean.TRUE or Boolean.FALSE, depending on what kind of features the OLAP provider supports.
IBIRelational.Supports Returns true or false, depending on what kind of features the relational provider supports.
 

Package com.sap.ip.bi.sdk.dac.connector Description

Provides interfaces and implementation for a client to access data from connectors such as the BI Java Connectors. The BI Java SDK's connection management conforms to the J2EE Connector Architecture (JCA) specification as well as SAP Enterprise Portal's Portal Connection Framework APIs. This package documentation contains the following sections:

Overview

Sun's J2EE Connector Architecture (JCA) defines a standard architecture for connecting the Java 2 Platform to heterogeneous Enterprise Information Systems (EISs) such as mainframe transaction processing and database systems. The JCA enables an EIS vendor to provide a standard resource adapter, in our case a BI Java Connector, which is defined as a system-level software driver used by a Java application to connect to an EIS. The connector plugs into an application server and provides connectivity between the EIS, the application server, and the application.

The BI Java Connectors implement JCA's Service Provider Interface (SPI) to realize the system contract. The connectors use the connection management components of both the JCA's Common Client Interface (CCI) and the SPI. In a layered approach, the BI Java Connectors implement the connection management interfaces in an abstract implementation layer, and each individual connector implements a concrete layer.

The figure below details this layered connection management approach:

SDK Connection Management Architecture diagramIBIConnectionIBIOlapIBIRelational

In brief, as depicted, JCA's CCI provides the Connection interface, which SAP's Enterprise Portal has extended with the IConnection interface of its Portal Connection Framework API. Taking this one step further, for BI-specific connections, we've extended IConnection with our IBIConnection interface. By extending the Portal Connection Framework interfaces and thus integrating with the Enterprise Portal Runtime, Java components can leverage services provided by the Portal such as SystemLandscape and ConnectorGateway.

Client Interface

The Common Client Interface (CCI) is a key component of the JCA specification. This is the interface that a resource adapter - in our case, a BI Java Connector -- provides to a client application to enable it to interact with its underlying EIS. This interface defines a standard client API for application components, which enables application components and enterprise architecture frameworks to drive interactions across heterogeneous EISs using a common client API.

Each BI Java Connector used by the BI Java SDK implements the CCI interfaces described below:

Consumer code deals only with the external CCI interfaces; these interfaces provide a wrap encapsulating all other JCA interfaces. In short, here's how to connect to data sources using the SDK:

  1. In your consumer code, look up the CCI connection factory interface of the connector.
  2. Create a connection specification (connection string) object and set the connection parameters, including user context. This may be done using a predefined connection string related to this connector. See the howto.html file inside each BI Java Connector's resource adapter archive for a list of specific connection parameters.
  3. Call the getConnection method that receives the connectionSpec object as a parameter.
  4. A CCI connection interface is returned as a result of the call.

Portal Connection Framework

SAP's Enterprise Portal has extended the CCI with its Portal Connection Framework interface, which consists of three components: Connection, Execution, and Metadata. The BI Java SDK uses this Portal Connection Framework, but only relies upon its Connection component. The Execution component defines functions, objects, and structures not currently used by the SDK, and for the Metadata functionality, the SDK has leveraged the CWM and JMI specifications.

The Connection component of the Portal Connection Framework provides the connection management interfaces (again, extending CCI's connection component), which include:

Service Provider Interface

The BI Java SDK's Service Provider Interface (SPI) handles connection management contracts between an application server and a resource adapter. Below are the service provider interfaces which need to be implemented by a resource adapter:

Managed Environment

SAP's BI resource adapters, the BI Java Connectors, may be used without an application server (in a non-managed environment), or may be deployed onto SAP's J2EE-based application server, the Web Application Server, version 6.40 (in a managed environment). The Web Application Server (WAS) is a J2EE application server that complies with JCA.

During the deployment process, the Web Application Server binds the Portal Connection Framework connection factory (IConnectionFactory) of the BI Java Connector to a JNDI lookup string. When the application server starts up, it instantiates a managed connection factory, passing an instance of its own connection manager to the BI Java Connector.

Code example for a managed environment, connecting using the BI JDBC Connector:

  Context initctx = null;
  IConnectionFactory connectionFactory = null;
  IConnection con;
    try
    {
      //obtain the initial JNDI context
      initctx = new InitialContext();
      // perform JNDI lookup to obtain connection factory
      connectionFactory = (IConnectionFactory)initctx.lookup("java:comp/env/"+"SDK_JDBC");
    }
    catch (Exception e)
    { ...
    }

    try
    {
      // retrieve the ConnectionSpec and set the values
      IConnectionSpec spec = connectionFactory.getConnectionSpec();
      spec.setPropertyValue("url","jdbc:odbc:Northwind");

      // retrieve the connection handle
      con = connectionFactory.getConnectionEx(spec);
      IBIRelational relational = ((IBIConnection) con).getRelational();
      ...
    }
    catch (Exception e)
    { ...
    }
 

In the above example, SDK_JDBC is the connector's JNDI name. See the connector's howto.html file, delivered in the resource adapter archive, for more information on each connector's particular properties.

Non-Managed Environment

As stated above, the BI Java Connectors may also be used without an application server (in a non-managed environment). The BI Java SDK contains the JAR files you need to develop applications using any of the BI Java Connectors and to use them in an unmanaged environment.

In this environment, your application client (the first tier) directly uses a BI Java Connector to access the EIS, which defines the second tier for a two-tier application. In this scenario, the BI Java Connector uses its default connection manager. Your consumer code creates an instance of the Portal Connection Framework IConnectionFactory without passing a connection manager as parameter. The IConnectionFactory creates a managed connection factory and the Connector's default connection manager.

Since the BI Java Connector is deployed in this scenario to an environment that does not contain the application server end of JCA, the managed connection factory, implemented by each individual BI Java Connector, is directly exposed to the consumer.

You can instantiate an instance of the managed connection factory and work directly with the physical connection layer to manage connections.

Code example for a non-managed environment, connecting using the BI JDBC Connector:

 ManagedConnectionFactory mcf = new JDBCManagedConnectionFactory();
 IConnectionFactory cf = (IConnectionFactory) mcf.createConnectionFactory();
 IConnectionSpec cs = cf.getConnectionSpec();
 ((Map) Cs).put("url","jdbc:odbc:Northwind");
 IConnection con = cf.getConnectionEx(Cs);
 IBIRelational relational = ((IBIConnection) con).getRelational();
 

Connection Specification and Portal Service

You need to specify certain parameters in order to configure your connection. The SDK implements the empty ConnectionSpec interface provided by the JCA for these purposes. In addition, the BI Java Connectors use the ConnectionSpec to define additional properties specific to the underlying EIS.

In order to conform to the Portal Connection Framework, we implement IConnectionSpec, which is an extension of ConnectionSpec.

In order to use Portal services such as the ConnectorGateway, we also need to implement several Portal-specific interfaces, including:

The following diagram illustrates ConnectionSpec and its related classes, using the BI ODBO Connector scenario as an example:

ConnectionSpec and related classes

BI Java Connectors

The JCA architecture manifests itself in the resource adapter, which plugs into an application server and provides connectivity between the EIS, the application server, and the application.

In the BI Java SDK, resource adapters are called connectors. Four JCA-compliant connectors, the BI Java Connectors, have been created for Java applications to connect to relational or OLAP data sources in an EIS. The connectors implement the specific client interface defined by the SDK's Connector Architecture.

As mentioned above, the BI Java SDK contains the JAR files you need to develop applications using any of the BI Java Connectors and to use them in an unmanaged scenario, but to use your application with a data source in the managed environment of the J2EE server, you need to deploy the appropriate BI Java Connector. The connectors themselves are distributed separately.

There are currently four BI Java Connectors available:

Testing the Connections

After you configure a BI Java Connector, you can perform a rough installation check by displaying the page for a given connector in your server. This package provides the servlets for these tests.

Perform the tests for a given connector by visiting the URLs in the table below:

Connector URL Result
BI JDBC Connector http://host:port/TestJDBC_Web/TestJDBCPage.jsp A list of tables appears

BI ODBO Connector

http://host:port/TOdbo/servlet/TestOdbo A list of cubes appears
BI SAP Query Connector http://host:port/TSapq/servlet/TestSapq A list of tables appears
BI XMLA Connector http://host:port/TXmla/servlet/TestXmla A list of cubes appears

Note:

These tests are designed to work with the default installation of the BI Java Connectors. Cloned connectors with new JNDI names are not tested by these servlets.

For Additional Information

Since:
3.50

SAP BI Java SDK

Copyright © 2004-2006 by SAP AG. All Rights Reserved.
SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.
These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies (SAP Group) for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.