Preface

The Oracle9i OLAP Developer's Guide to the OLAP API introduces Java programmers to the Oracle OLAP API which is the Java application programming interface for Oracle OLAP. Through Oracle OLAP, the OLAP API provides access to data stored in an Oracle database. The OLAP API's capabilities for querying, manipulating, and presenting data are particularly suited to applications that perform Online Analytical Processing.

This preface contains these topics:

Audience

Oracle9i OLAP Developer's Guide to the OLAP API is intended for Java programmers who are responsible for creating applications that perform analysis using Oracle OLAP.

To use this document, you need be familiar with Java, relational database management systems, data warehousing, and Oracle OLAP and Online Analytical Processing (OLAP) concepts.

Organization

This document contains:

Chapter 1, "Introduction to the OLAP API"

Introduces the OLAP API to application developers who plan to use it in their Java applications.

Chapter 2, "Understanding OLAP API Metadata"

Describes the metadata objects that the OLAP API provides, and explains how these objects relate to the metadata objects that a database administrator specifies when preparing the data using the OLAP Metadata APIs.

Chapter 3, "Connecting to a Data Store"

Explains the procedure for connecting to a data store through the OLAP API.

Chapter 4, "Discovering the Available Metadata"

Explains the procedure for discovering the metadata in a data store through the OLAP API.

Chapter 5, "Introduction to Querying"

Introduces Source objects which are the OLAP API objects that are the specifications for sets of data that you use when making queries.

Chapter 6, "Making Queries Using Source Methods"

Discusses how to make queries using Source methods.

Chapter 7, "Using a TransactionProvider"

Describes the Oracle OLAP API Transaction and TransactionProvider interfaces and describes how you use implementations of those interfaces in an application. You must create a TransactionProvider before you can create a DataProvider, and you must use methods on the TransactionProvider to prepare and commit a Transaction before you can create a Cursor for a derived Source.

Chapter 8, "Understanding Cursor Classes and Concepts"

Describes the Oracle OLAP API Cursor class and its related classes, which you use to retrieve and gain access to the results of a query. This chapter also describes the Cursor concepts of position, fetch size, and extent.

Chapter 9, "Retrieving Query Results"

Describes how to retrieve the results of a query with an Oracle OLAP API Cursor, how to gain access to those results, and how to customize the behavior of a Cursor to fit your method of displaying the results.

Chapter 10, "Creating Dynamic Queries"

Describes the Oracle OLAP API Template class and its related classes, which you use to create dynamic queries. This chapter also provides examples of implementations of those classes.

Appendix A, "Setting Up the Development Environment"

Describes the steps you take to set up your development environment for creating applications that use the OLAP API.

Conventions

This section describes the conventions used in the text and code examples of this documentation set. It describes:

Conventions in Text

We use various conventions in text to help you more quickly identify special terms. The following table describes those conventions and provides examples of their use.

Convention	Meaning	Example
Bold	Bold typeface indicates terms that are defined in the text or terms that appear in a glossary, or both.	When you specify this clause, you create an index-organized table.
Italics	Italic typeface denotes book titles and emphasis.	Oracle9i OLAP User's Guide Ensure that the recovery catalog and target database do not reside on the same disk.
Bold	Bold font denotes terms being defined for the first time,	The methods of the `Source` class and its subclasses return new `Source` objects sometimes called derived `Source` objects.
`UPPERCASE monospace (fixed-width) font`	Uppercase monospace typeface indicates elements supplied by the system. Such elements include parameters, privileges, datatypes, RMAN keywords, SQL keywords, SQL*Plus or utility commands, packages and methods, as well as system-supplied column names, database objects and structures, usernames, and roles.	The return value from its `getHierarchyType` method is LEVEL_HIERARCHY.
`lowercase monospace (fixed-width) font`	Lowercase monospace typeface indicates denotes Java program names, file names, path names, and Internet addresses.	Back up the datafiles and control files in the `/disk1/oracle/dbs` directory.
`MixedCase monospace (fixed-width) font`	Mixedcase monospace typeface is used for names of classes and interfaces and for multi-word names of variables, methods, and packages. The names of classes and interfaces begin with an upper-case letter. In all multi-word names, the second and succeeding words also begin with an upper-case letter.	To obtain access to the metadata, an application uses the `getRootSchema` method in `MdmMetadataProvider`.
`lowercase italic monospace (fixed-width) font`	Lowercase italic monospace font represents placeholders or variables.	You can specify the `parallel_clause`. Run `U``old_release``.SQL` where `old_release` refers to the release you installed prior to upgrading.

Conventions in Code Examples

Code examples illustrate Java, SQL, PL/SQL, SQL*Plus, or other command-line statements. They are displayed in a monospace (fixed-width) font and separated from normal text as shown in this example:

Source unitCost = mdmUnitCost.getSource;

The following table describes typographic conventions used in Java code examples and provides examples of their use.

Convention	Meaning
{ }	Braces enclose a block of statements.
//	A double slash begins a single-line comment, which extends to the end of a line.
`/* */`	A slash-asterisk and an asterisk-slash delimit a multi-line comment, which can span multiple lines/
`...`	Horizontal ellipsis shows that statements or clauses irrelevant to the discussion were left out.

Conventions for Windows Operating Systems

The following table describes conventions for Windows operating systems and provides examples of their use.

Convention	Meaning	Example
Choose Start >	How to start a program.	To start the Database Configuration Assistant, choose Start > Programs > Oracle - HOME_NAME > Configuration and Migration Tools > Database Configuration Assistant.
File and directory names	File and directory names are not case sensitive. The following special characters are not allowed: left angle bracket (<), right angle bracket (>), colon (:), double quotation marks ("), slash (/), pipe (\|), and dash (-). The special character backslash (\) is treated as an element separator, even when it appears in quotes. If the file name begins with \\, then Windows assumes it uses the Universal Naming Convention.	c:\winnt"\"system32 is the same as C:\WINNT\SYSTEM32
`C:\>`	Represents the Windows command prompt of the current hard disk drive. The escape character in a command prompt is the caret (^). Your prompt reflects the subdirectory in which you are working. Referred to as the command prompt in this manual.	C:\oracle\oradata>
Special characters	The backslash (\) special character is sometimes required as an escape character for the double quotation mark (") special character at the Windows command prompt. Parentheses and the single quotation mark (') do not require an escape character. Refer to your Windows operating system documentation for more information on escape and special characters.	C:\>exp scott/tiger TABLES=emp QUERY=\"WHERE job='SALESMAN' and sal<1600\" C:\>imp SYSTEM/password FROMUSER=scott TABLES=(emp, dept)
HOME_NAME	Represents the Oracle home name. The home name can be up to 16 alphanumeric characters. The only special character allowed in the home name is the underscore.	C:\> net start OracleHOME_NAMETNSListener
`ORACLE_HOME` and `ORACLE_BASE`	In releases prior to Oracle8i release 8.1.3, when you installed Oracle components, all subdirectories were located under a top level `ORACLE_HOME` directory that by default used one of the following names: `C:\orant` for Windows NT `C:\orawin98` for Windows 98 This release complies with Optimal Flexible Architecture (OFA) guidelines. All subdirectories are not under a top level `ORACLE_HOME` directory. There is a top level directory called `ORACLE_BASE` that by default is `C:\oracle`. If you install the latest Oracle9i release on a computer with no other Oracle software installed, then the default setting for the first Oracle home directory is `C:\oracle\orann` where `nn` is the latest release number. The Oracle home directory is located directly under `ORACLE_BASE`. All directory path examples in this guide follow OFA conventions. Refer to Oracle9i Database Getting Started for Windows for additional information about OFA compliances and for information about installing Oracle products in non-OFA compliant directories.	Go to the `ORACLE_BASE``\``ORACLE_HOME``\rdbms\admin` directory.

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 Corporation 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

JAWS, a Windows screen reader, 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, JAWS may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle Corporation does not own or control. Oracle Corporation neither evaluates nor makes any representations regarding the accessibility of these Web sites.