Jdbc4olap-

User Guide

1

Table of Contents

1 Overview.......................................................................................................................................... 3

1.1 Purpose......................................................................................................................................3

1.2 Relational vs Multidimensional................................................................................................ 3

1.3 Jdbc4olap's model..................................................................................................................... 3

1.4 XML for Analysis..................................................................................................................... 5

1.5 SQL-MDX conversion..............................................................................................................5

2 Features.............................................................................................................................................6

2.1 Connection................................................................................................................................ 6

2.2 Metadata....................................................................................................................................6

2.3 Queries ..................................................................................................................................... 6

2.4 Optimisation..............................................................................................................................7

3 XMLA Setup ................................................................................................................................... 8

3.1 XMLA connection test..............................................................................................................8

3.1.1 Browser test.......................................................................................................................8

3.1.2 cURL test...........................................................................................................................8

3.2 SAP BW .................................................................................................................................13

4 Driver Setup....................................................................................................................................16

4.1 General setup.......................................................................................................................... 16

4.2 SAP BW – Prelytis Scenario...................................................................................................17

4.3 Open Office Base – Mondrian scenario..................................................................................20

2

1 Overview

1.1 Purposejdbc4olap is, as the name suggests, a jdbc driver for OLAP databases. Jdbc is an

interface that allows an application to connect to various relational databases whereas OLAP refers to multidimensional data software. Consequently, this project implies to make a bridge between two incompatible environments as they rely on different models and involve different technologies. You will see in this manual how, and with which limitations, this driver will allow you to retrieve data from your OLAP sources within a relational environment.

1.2 Relational vs MultidimensionalRelational databases, such as Oracle RDBMS, MySQL, MS SQL Server, enclose

sets of tables composed of several columns and containing rows of data. Columns from different tables can be linked in order to represent an association between these sets of data. SQL is the standard language to dialog with a relational database server, in order to retrieve or manipulate data.

Multidimensional databases, such as SAP BW, MS SQL Server Analysis Services, Mondrian, consist of cubes of several dimensions (not only 3 like in a real cube), composed of one or more hierarchies of levels whose values, called members, are data properties. The data is located at the intersection of these dimensions, in cube cells that contain different values called measures. MDX emerged as the standard language for multidimensional databases, and despite some similarities with SQL, has its own syntax and mechanisms.

1.3 Jdbc4olap's modelIn order to consider an OLAP base from a relational point of view, a correspondence

must be established between the two models. Let's consider the example cube shown in illustration 1.

3

It consists of 3 different dimensions: Products, Geography, and Time and their respective levels: {Product category, Product family}, {Continent, Country}, {Year, semester}. Two measures are available: Sales and Production. The cube could contain more than 3 dimensions but as you can guess, it is easier to illustrate. In jdbc4olap, that cube would be represented as you can see in illustration 2.

That schema keeps the links between the dimensions and the measures. An important precision must be made: this example displays a cube whose dimensions

4

Illustration 1: example cube

Illustration 2: relational representation of the example cube in jdbc4olap

include only one hierarchy. For example if the Geography dimension had different hierarchies corresponding to different ways of expressing a location, that would generate as many tables.

1.4 XML for AnalysisIn order to retrieve data, we need a way to dialog with the server. Among the

various possible ways to access OLAP databases, we chose XMLA. These initials indicate a standardization of the interface of access to multidimensional bases, defined by a consortium of major actors of the market. Here's the list of the principal decisional systems that use this standard:

● Hyperion Essbase 7● Microsoft Analysis Services 2005● Mondrian● SAP BW from 3.0a

Based on XML, SOAP and HTTP standards, this technology consists of a webservice available on the OLAP server which dialogues with XMLA clients by exchanging SOAP messages. There are several ways to secure a web service and thus a XMLA access: SSL encoding on the transport layer, XML encoding on the message layer, and also access control with a proxy. And, the driver being exclusively in read-only mode, there are no possible data-damage issues.

1.5 SQL-MDX conversionCubes being represented as a relational model, and the driver aiming for the best

JDBC compliancy, SQL was naturally the language to use. But as most OLAP servers only support MDX, a convertor had to be designed and integrated to the query process. This is why there are limitations on the supported queries, as all SQL query concepts can't be translated in MDX.

5

2 Features

2.1 ConnectionThe first step in JDBC compliance is to conform to its connection mechanism.

Indeed, once the driver is installed, any jdbc connection attempt with a location starting with jdbc:jdbc4olap: will select jdbc4olap as the driver to use for the connection and further operations.

2.2 MetadataThe JDBC's DatabaseMetadata interface is fully implemented. This firstly means

that the driver's possibilities and limitations are indicated, but also that the user can interrogate a server to discover its data. Indeed the driver is able to navigate through available catalogs, schemas, tables and columns. These features are usually used to help the user setup a query.

2.3 Queries As explained above, there are limitations in the supported SQL queries, due to the

conversion to MDX and the impossibility to adapt some concepts. The query must look as follow :

query := 'SELECT' fieldList 'FROM' tableList 'WHERE' filterList 'GROUP BY' expressionList ';'

fieldList := (field (',' field)*) | '*'field := tableStar | columnNametableStar := (catalog.schema.table|table|tableAlias)'.*'columnName := [catalog.schema.table.|table.|tableAlias.]column [['AS']

fieldAlias]tableList := table (',' table)*table := catalog.schema.table [tableAlias]filterList := sqlExpression ('AND' sqlExpression)*sqlExpression := operand (relationalExpression | inClause)operand := NUMBER | STRING | filterColumn | '?'relationalExpression := '=' operandinClause := 'IN' '(' expressionList ')'expressionList := operand (',' operand)*filterColumn := [catalog.schema.table.|table.|tableAlias.](column|fieldAlias)

6

As we can see on this grammar, most of the limitations apply to the filters, who can only be combined by AND operators, and consist of '=' or 'IN' clauses.

In the current release, the filters like 'column = column' are ignored. Indeed it's implied that the joins are set correctly to establish the model described before. So it's impossible to process a cartesian product.

If you look carefully at the grammar, you will notice that '?' is supported in the filters. It means that both statements and prepared statements are handled.

2.4 OptimisationIt is possible to improve the driver's performance using HTTP compression. Indeed,

the XMLA streams exchanged can be quite heavy, so compressing them accelerates the transfers and therefore the execution time.

On the driver's side the streamCompression property must be set to 1. In LiveDashboard that is done on the Properties tab of the world.

The OLAP server also has to be ready to send compressed streams. On Essbase, it depends on the server.xml file, usually located in C:\Hyperion\deployments\Tomcat5\aps\conf\. The connector tag for the 13080 port must have the following attribute: compression = “on”. If a modification has to be made, it will be applied after restarting the Hyperion S9 Provider Services ATS5 service.

7

3 XMLA Setup

3.1 XMLA connection test

3.1.1 Browser testWhatever the OLAP server, the availability of the XMLA web service can be

checked by launching its url on a web browser. If the reply is not a 404 error, then the service is available. For example on Essbase:

3.1.2 cURL testThe browser test is not enough, as XMLA servers often require credentials. The

simplest way to check that a XMLA web service can be used is to use cURL, available here: http://curl.haxx.se/ This command line tool allows to easily query a FTP or HTTP server. Two XMLA queries are needed in this case.

• One DISCOVER_DATASOURCES query:◦ Download the xmla4curl1.txt file here :

http://sourceforge.net/projects/jdbc4olap/files/Tools/xmla4curl1.txt/download

◦ Copy it in the curl folder then launch the following command, with the proper url (previously checked with the browser test) :

curl --basic -u user:password -H "Content-Type: application/soap+xml;charset=UTF8" --data @xmla4curl1.txt http://localhost:13080/aps/XMLA

Note that this command doesn't check credentials, so user/password values in the command line don't matter. The server should reply with a XMLA stream like this:

8

<?xml version="1.0"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><m:DiscoverResponse xmlns:m="urn:schemas-microsoft-com:xml-analysis"><m:return xsi:type="xsd:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><root xmlns="urn:schemas-microsoft-com:xml-analysis:rowset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><xsd:schema xmlns="urn:schemas-microsoft-com:xml-analysis:rowset" targetNamespace="urn:schemas-microsoft-com:xml-analysis:rowset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:xml-sql" elementFormDefault="qualified"><xsd:element name="root"><xsd:complexType><xsd:sequence minOccurs="0" maxOccurs="unbounded"><xsd:element name="row" type="row"/></xsd:sequence></xsd:complexType></xsd:element><xsd:complexType name="row"><xsd:sequence maxOccurs="unbounded" minOccurs="0"><xsd:element name="DataSourceName" type="xsd:string" sql:field="DataSourceName"/><xsd:element name="DataSourceDescription" type="xsd:string" sql:field="DataSourceDescription"/><xsd:element name="URL" type="xsd:string" sql:field="URL" minOccurs="0"/><xsd:element name="DataSourceInfo" type="xsd:string" sql:field="DataSourceInfo"/><xsd:element name="ProviderName" type="xsd:string" sql:field="ProviderName"/><xsd:element name="ProviderType" sql:field="ProviderType"><xsd:complexType><xsd:sequence maxOccurs="unbounded" minOccurs="0"><xsd:any processContents="lax" maxOccurs="unbounded"/></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="AuthenticationMode" sql:type="xsd:string" sql:field="AuthenticationMode"/></xsd:sequence></xsd:complexType></xsd:schema><row><DataSourceName>essbase931</DataSourceName><DataSourceDescription>Essbase OLAP Server on essbase931 machine</DataSourceDescription><DataSourceInfo>Provider=Essbase;Data Source=essbase931</DataSourceInfo><ProviderName>Essbase XML for Analysis</ProviderName><ProviderType><MDP/></ProviderType>

9

<AuthenticationMode>Authenticated</AuthenticationMode></row></root></m:return></m:DiscoverResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

The purpose of this operation is to retrieve the DataSourceInfo necessary in the next step. In this example: “Provider=Essbase;Data Source=essbase931”

• A DISCOVER_CATALOGS query:◦ Download the xmla4curl2.txt file here:

http://sourceforge.net/projects/jdbc4olap/files/Tools/xmla4curl2.txt/download

◦ Copy it in the curl folder and modify the DataSourceInfo with the string obtained above.

◦ Then launch the following command with the proper url and login/password :curl --basic -u user:password -H "Content-Type: application/soap+xml;charset=UTF8" --data @xmla2.txt http://localhost:13080/aps/XMLA

It should display a XMLA stream that contain the list of available catalogs: <?xml version="1.0"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><m:DiscoverResponse xmlns:m="urn:schemas-microsoft-com:xml-analysis"><m:return xsi:type="xsd:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><root xmlns="urn:schemas-microsoft-com:xml-analysis:rowset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><xsd:schema xmlns="urn:schemas-microsoft-com:xml-analysis:rowset" targetNamespace="urn:schemas-microsoft-com:xml-analysis:rowset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:xml-sql" elementFormDefault="qualified"><xsd:element name="root"><xsd:complexType><xsd:sequence minOccurs="0" maxOccurs="unbounded"><xsd:element name="row" type="row"/></xsd:sequence></xsd:complexType></xsd:element><xsd:complexType name="row">

10

<xsd:sequence maxOccurs="unbounded" minOccurs="0"><xsd:element name="CATALOG_NAME" type="xsd:string" sql:field="CATALOG_NAME"/><xsd:element name="DESCRIPTION" type="xsd:string" sql:field="DESCRIPTION" minOccurs="0"/></xsd:sequence></xsd:complexType></xsd:schema><row><CATALOG_NAME>ASOsamp</CATALOG_NAME></row><row><CATALOG_NAME>Demo</CATALOG_NAME></row><row><CATALOG_NAME>DMDemo</CATALOG_NAME></row><row><CATALOG_NAME>Sampeast</CATALOG_NAME></row><row><CATALOG_NAME>Sample</CATALOG_NAME></row><row><CATALOG_NAME>Sample_U</CATALOG_NAME></row><row><CATALOG_NAME>Samppart</CATALOG_NAME></row></root></m:return></m:DiscoverResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

Then the test is passed and this XMLA web service can be used. But if the user does not have sufficient permissions, you get an error message like this (with Essbase in this example): <?xml version="1.0" encoding='UTF-8'?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><SOAP-ENV:Fault><faultcode> XMLAnalysisError.20001</faultcode><faultstring><![CDATA[User authentication needed. Please sign on.]]></faultstring><faultactor> XML for Analysis Provider for Essbase </faultactor><detail><Error ErrorCode= "20001"Description = "User authentication needed. Please sign on."Source = "XML for Analysis Provider for Essbase "HelpFile=""/>

11

</detail></SOAP-ENV:Fault></SOAP-ENV:Body></SOAP-ENV:Envelope>First of all, get sure that the login / passwords used are correct. Then check if necessary on the OLAP server that the user in question have sufficient rights.

12

3.2 SAP BW You can activate the XMLA web service from SAP netweaver, in the services

section, deploying the menu at SAP/BW/XML/SOAP/XMLA, as you can see in the illustration 3.

Use the « activate service » option if necesary from the contextual menu to enable XMLA. You can also use the « Test service » option, highlighted in the example, to check that the webservice is available. It will open a browser that should display a XML stream, as in illustration 4. At the same time it will give you the webservice url needed to setup your jdbc connection.

13

Illustration 3: XMLA webservice in SAP Netweaver

QueryCubes must be configured in order to be available through the SAP BW XML/A interface. In the Bex Query Designer, go to the Extended tab of the Query Properties dialog box and select the Allow External Access to this Query check box, as you can see in illustration 5.

14

Illustration 4: SAP Netweaver XMLA test

15

Illustration 5: allow external access to QueryCubes

4 Driver Setup

4.1 General setupYou first need to ensure that you have the latest version of the driver by checking

our sourceforge download section. Then you must add the different jar files from the archive to your classpath. When setting up the jdbc connection in your software, you have to mention the driver class: « org.jdbc4olap.jdbc.OlapDriver ». The url must start with 'jdbc:jdbc4olap:' for the driver manager to select the jdbc4olap driver. You may have to setup your OLAP server to activate the XMLA webservice, and to know its url. Depending on the provider, it will look like one of these :

● MS SQL Server: jdbc:jdbc4olap:http://server:port/OLAP/msmdpump.dll ● Mondrian: jdbc:jdbc4olap:http://server:port/mondrian/xmla ● SAP BW: jdbc:jdbc4olap:http://server:port/sap/bw/soap/xmla?sap-client=number

16

4.2 SAP BW – Prelytis ScenarioWe will now show you how to setup Prelytis LiveDashboard in order to visualize

your SAP data in your dashboards. The driver is actually comprised of 5 jar files:

● activation.jar● commons-codec.jar● jdbc4olap.jar● saaj-api.jar● saaj-impl.jar

First you have to copy these jar files into the library directory of your application server, i.e. apache-tomcat-6.0.18/lib for tomcat, or jboss/server/default/lib for jboss. If that directory already contains some of the jars used by jdbc4olap, don't overwrite them. Now restart the application server.

Then log into Prelytis as superadmin, and enter the driver session in order to create a new one, as shown in illustration 6.

Then click on the Properties tab and adjust the settings like in illustration 7.

17

Illustration 6: Prelytis Driver Description

Create a world based on this driver to access our cubes. We just have to give a name, select the driver we created, fill in the URL of the SAP BW XMLA webservice, a username and its password. You can test the connection by hitting the yellow button. As a result, LDB will show a green message to validate the proper functioning.

18

Illustration 7: Prelytis Driver Properties

You may now create reports using this world and retrieve SAP BW data. However, there are restrictions when working with cubes from a relational environment, which you should be aware of, For example when using more than one filter, they can only be combined by the AND operator. But most of the unavailable functionalities are not needed in a cube. Let's consider the example cube in the illustration 1. With a relational database, in order to display a data for each country and for their continent, we would probably have to use a calculation line. But in a cube the data is already available.

19

Illustration 8: Prelytis World Configuration

4.3 Open Office Base – Mondrian scenarioHere are the different detailed steps in using the driver from Open Office Base to

access a Mondrian OLAP database.Start Open Office Base, and since a database must opened, create one if

necessary:

In the next screen, you will not need to register but choose top open the database for editing. Finally, choose a location and filename for that base.

Go to Tools/Options and open Open Office.org/Java settings:

20

Select a JRE 1.5 or add one with the «Add... » button if none is available. Click on « Class Path... » and add all the jar files from the jdbc4olap archive:

Everything is now correctly set up, we will not need this newly created base, anymore. We can restart Open Office to create a JDBC connection:

21

The «Test Class» button should retrieve the following message:

22

And the «Connection Test» from the next screen should end the same way :

Once again, choose to register or not but opt for the editing mode, and choose a filename. Then go to Tables, and after a few seconds you will see the database with the jdbc4olap relational model:

23

You may now use the database connection effectively. All the functionnalities haven't been tested yet, but you can for example create a new query :

Only add tables from the same schema, because otherwise it would generate a query from different cubes, and that can't be done. Then select the columns you want on your query. A bug in Open Office can occur here: if you double click in a box (that appeared when you added a table) to select a column it works fine, but if you use the combo in the bottom part of the screen to make your selection it changes the name of the column, and results in the query failure.

24

You can finally launch the query to check its validity and its results :

25