Oracle® OLAP Analytic Workspace Java API Reference.

See:
Description

Packages

oracle.AWAction	Contains classes that define actions to perform on an analytic workspace.
oracle.AWXML	Contains classes that define a logical object model and instantiate it in an analytic workspace.

Oracle® OLAP Analytic Workspace Java API Reference.

June, 2005

This is the reference documentation for the Oracle OLAP Analytic Workspace Java API.

Overview

You can use the Analytic Workspace Java API to build applications that create and maintain standard form analytic workspaces within the Oracle Database. The API supports a multidimensional object model and provides tools for instantiating the model in an analytic workspace. An object hierarchy defines a set of ownership relationships between objects in the model.

The Analytic Workspace Java API uses the SPLExecutor class in the Oracle OLAP Java API to wrap OLAP DML commands for execution within the Database. The OLAP Java API is a companion API for generating OLAP queries of analytic workspaces and relational data warehouses. (For information on the OLAP Java API, see the Oracle OLAP Developer's Guide to the OLAP API and the Oracle OLAP Java API Reference. For information on the OLAP DML, see the Oracle OLAP DML Reference.)

Two Deployment Modes

The Analytic Workspace Java API supports two deployment modes. You can use it in creating a Java application, or you can use it to generate XML that is executable by a PL/SQL function. The XML storage capability makes the API available to any application that can connect to the Database and execute a stored procedure.

The functionality of the API is identical whether executed through Java or through PL/SQL. The same Java code that runs on the client and executes through JDBC also runs within the Database JVM and executes directly within the Database. When you install the Database with the OLAP option, the Analytic Workspace Java API is automatically loaded along with all the other OLAP server-side components.

Advantages of the Analytic Workspace Java API

Applications created with the Analytic Workspace Java API offer several advantages:

• They do not require pre-existing metadata.
• They support complex OLAP calculations without revealing the underlying OLAP DML.
• They load data from relational tables into analytic workspaces, but do not require a specific relational configuration such as a star or snowflake schema.

Using the Analytic Workspace Java API in a Java Application

You can use the Analytic Workspace Java API to build client applications that interact with the Database through JDBC. Both thick and thin connections are supported.

The AWXML package provides the classes that build an OLAP object model. Many of the classes have methods for generating XML. These are not needed in Java applications, however you can use them if you want your application to save the object definitions in addition to (or instead of) executing them dynamically. If you choose to create XML, then use the AWAction package to assemble the XML definitions into logical units of work. The AWXML package includes a class you can use to parse the stored XML and restore the objects in memory.

This documentation contains a sample program, BuildAWExample.java, that illustrates the use of the Analytic Workspace Java API. The program uses data from relational tables in the Global Schema for Documentation with OLAP Catalog Metadata. You can download a the SQL scripts and other files that create the sample schema from the Oracle Technology Network at http://www.oracle.com/technology/products/bi/olap/olap.html. To download the sample schema, in the Documentation section click Sample Schemas for Documentation, and then click Global Schema for Documentation with OLAP Catalog Metadata.

The BuildAWExample.java program defines an analytic workspace containing two logical cubes: a UNITS_CUBE_AW cube dimensioned by the TIME_AW, CUSTOMER_AW, PRODUCT_AW, and CHANNEL_AW dimensions, and the PRICE_COST_CUBE_AW cube dimensioned by TIME_AW and PRODUCT_AW. To view the source code for the example program, see BuildAWExample.java. For an outline of the sequence of Analytic Workspace Java API object creation and use in the example program, see Steps In Creating An Analytic Workspace.

Using the Analytic Workspace Java API to Generate XML

You can use the Analytic Workspace Java API to generate XML documents that serialize the object model for execution by a PL/SQL function. In this case, the database commands generated by the API execute directly within the Database, and not through a database connection.

To create XML for execution in the Database, use the AWXML package to build the object model and generate the XML that represents the object model. Use the AWAction package to build logical units of work into the XML. To instantiate the XML, load it into a CLOB and provide the CLOB as input to the INTERACTIONEXECUTE PL/SQL function. That function passes the input to the Analytic Workspace Java API running within the database JVM. The API parses the string and restores the Java objects in memory.For more information on the INTERACTIONEXECUTE function, see the Oracle OLAP Reference.

Creating Your Own XML

If you prefer to create your own XML, then use an XML development environment such as XMLSpy© and validate your XML against the Oracle OLAP XML schema defined in AWXML.xsd. Once you have validated the OLAP XML, you can execute it with the INTERACTIONEXECUTE function. In this case, you do not need to use the Java API at all.

You can obtain AWXML.xsd from the Oracle Technology Network Web site at http://www.oracle.com/technology/products/bi/olap/olap.html.

You can generate the documentation for AWXML.xsd within your XML development environment.

Intended Audience

This documentation is intended for Java programmers who are responsible for creating applications that build and maintain analytic workspaces. It assumes that you are already familiar with Java, Oracle OLAP, and data warehousing concepts.

Before You Begin

To use the Analytic Workspace Java API, you need the following:

• Access to an Oracle Database installed with the OLAP option.
• Database credentials for the relational schemas that contain the source data for your application.
• JDK 1.4 or higher. If you are using Oracle® JDeveloper as your development environment, then make sure that it includes the correct version of the JDK.

The OLAP-enabled Database provides the Analytic Workspace Java API class libraries as a jar file. To use the API, copy awxml.jar to the computer on which you develop your Java applications, or otherwise make it accessible to your development environment. In addition to awxml.jar, the OLAP API and certain Oracle JDBC jar files are also required. You must use the JDBC files included in your Oracle Database installation and not those from another Oracle product or from another vendor.

The following table lists the required class libraries with their locations under the ORACLE_HOME directory.

File Name	Location
awxml.jar	/olap/api/lib
olap_api.jar	/olap/api/lib
classes12.jar	/jdbc/lib
xmlparserv2.jar	/lib

For information on Oracle JDBC, see the Oracle JDBC Developer's Guide and Reference.

For information on installing an Oracle Database with the OLAP option, see your Oracle Database installation documentation. For more information on administering the OLAP option, see the Oracle OLAP Applicaton Developer's Guide.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at

http://www.oracle.com/accessibility/.

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Related Documentation

For more information about Oracle OLAP and Oracle data warehousing, refer to the following manuals:

• Oracle OLAP Developer's Guide to the OLAP API -- Introduces the Oracle OLAP API, a Java application programming interface for Oracle OLAP, which is used to perform OLAP queries of the data stored in an Oracle database. Describes the API and how to discover metadata, create queries, and retrieve data.
• Oracle OLAP Java API Reference -- Describes the classes and methods in the Oracle OLAP Java API for querying analytic workspaces and relational data warehouses.
• Oracle OLAP Application Developer's Guide -- Explains how SQL and Java applications can extend their analytic processing capabilities by using Oracle OLAP.
• Oracle OLAP Reference -- Explains the syntax of PL/SQL packages and types and the column structure of views related to Oracle OLAP.
• Oracle OLAP DML Reference -- Contains a complete description of the OLAP Data Manipulation Language (OLAP DML) used to define and manipulate analytic workspace objects.
• Oracle Data Warehousing Guide -- Discusses the database structures, concepts, and issues involved in creating a data warehouse to support online analytical processing solutions.