Oracle OLAP Java API Reference: Class ExpressDataProvider

Overview

Package

Class

Tree

Deprecated

Index

Help

Oracle® OLAP Java API Reference
10g Release 2 (10.2)
B14348-01

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

oracle.express.olapi.data.full
Class ExpressDataProvider

java.lang.Object
  |
  +--oracle.olapi.data.source.DataProvider
        |
        +--oracle.express.olapi.data.full.ExpressDataProvider

public class ExpressDataProvider
extends DataProvider

A concrete subclass of DataProvider that creates objects that an application uses in creating queries and retrieving data from an Oracle Database instance. Each ExpressDataProvider is associated with an oracle.jdbc.OracleConnection and an ExpressTransactionProvider.

After creating a new ExpressDataProvider, an application must call its initialize method. After initializing the ExpressDataProvider, the application should call the getDefaultMetadataProvider method of the ExpressDataProvider to get the MetadataProvider to use.

By default, an ExpressDataProvider has the following characteristics:

It uses unique dimension hierarchy member values.
It recognizes both OLAP Catalog metadata and standard form analytic workspace metadata.
For an analytic workspace, it issues an ALTER SESSION SET NLS_LANGUAGE SQL command that sets the language of the database.

Using a constructor that takes a Properties or a Locale object, or both, an application can create an ExpressTransactionProvider that has different characteristics.

The following table lists the keys and the case-sensitive values for the properties that you can set in a Properties object and provides a brief description of them.

Key Value Property Description

Key	Value	Property Description
`HierarchyValueType`	`unique\|local`	Specifies whether to use unique or local values for members of dimension hierarchies. The use of `Model` objects requires unique dimension hierarchy values. For more information on unique and local values, see the Overview of this documentation. The `unique` value specifies using a three part value that identifies the dimension hierarchy, the level in the hierarchy, and the local value of the dimension member in the level. It is the default property value. The `local` value specifies using only the local dimension member value.
`MetadataReaderMode`	`ALL\|NONE\|10103AWONLY\|CWM2ONLY`	Specifies the type of metadata recognized by the `MetadataProvider` associated with the `ExpressDataProvider`. The `ALL` value specifies that the `MetadataProvider` recognizes both OLAP Catalog and standard form analytic workspace metadata. OLAP Catalog metadata is generated by Oracle Enterprise Manager and by PL/SQL CWM2 package APIs. It is the default property value. The `NONE` value specifies recognizing neither the OLAP Catalog nor the standard form analytic workspace metadata. An application can also create metadata objects by using classes in the `oracle.olapi.metadata.mtm` package. These objects are independent of the OLAP Catalog and the standard form analytic workspace metadata and are always recognized by the `MetadataProvider`. The `10103AWONLY` value specifies recognizing only standard form analytic workspace metadata. This metadata is generated for an analytic workspace by the Oracle OLAP Analytic Workspace Java API and by Analytic Workspace Manager. Oracle OLAP first used this type of metadata in Oracle Database 10g Release 1 (10.1.0.3). The `CWM2ONLY` value specifies recognizing only OLAP Catalog metadata.
`UseDefaultLanguage`	`YES\|NO`	Specifies whether Oracle OLAP issues an `ALTER SESSION SET NLS_LANGUAGE` SQL command that sets the language of the database and the OLAP DML command `STATIC_SESSION_LANGUAGE=TRUE` that prevents changing the language. This property affects only metadata and data from an analytic workspace. If an application wants to manage the language use, then it should specify `NO` for this property. The `YES` value specifies that Oracle OLAP issues the `ALTER SESSION SET NLS_LANGUAGE` and `STATIC_SESSION_LANGUAGE=TRUE` commands. It is the default value of the property. The `NO` value specifies that the Oracle OLAP does not issue the commands.

HierarchyValueType

unique|local

Specifies whether to use unique or local values for members of dimension hierarchies. The use of Model objects requires unique dimension hierarchy values. For more information on unique and local values, see the Overview of this documentation.

The unique value specifies using a three part value that identifies the dimension hierarchy, the level in the hierarchy, and the local value of the dimension member in the level. It is the default property value.

The local value specifies using only the local dimension member value.

MetadataReaderMode

ALL|NONE|10103AWONLY|CWM2ONLY

Specifies the type of metadata recognized by the MetadataProvider associated with the ExpressDataProvider.

The ALL value specifies that the MetadataProvider recognizes both OLAP Catalog and standard form analytic workspace metadata. OLAP Catalog metadata is generated by Oracle Enterprise Manager and by PL/SQL CWM2 package APIs. It is the default property value.

The NONE value specifies recognizing neither the OLAP Catalog nor the standard form analytic workspace metadata. An application can also create metadata objects by using classes in the oracle.olapi.metadata.mtm package. These objects are independent of the OLAP Catalog and the standard form analytic workspace metadata and are always recognized by the MetadataProvider.

The 10103AWONLY value specifies recognizing only standard form analytic workspace metadata. This metadata is generated for an analytic workspace by the Oracle OLAP Analytic Workspace Java API and by Analytic Workspace Manager. Oracle OLAP first used this type of metadata in Oracle Database 10g Release 1 (10.1.0.3).

The CWM2ONLY value specifies recognizing only OLAP Catalog metadata.

UseDefaultLanguage

YES|NO

Specifies whether Oracle OLAP issues an ALTER SESSION SET NLS_LANGUAGE SQL command that sets the language of the database and the OLAP DML command STATIC_SESSION_LANGUAGE=TRUE that prevents changing the language. This property affects only metadata and data from an analytic workspace. If an application wants to manage the language use, then it should specify NO for this property.

The YES value specifies that Oracle OLAP issues the ALTER SESSION SET NLS_LANGUAGE and STATIC_SESSION_LANGUAGE=TRUE commands. It is the default value of the property.

The NO value specifies that the Oracle OLAP does not issue the commands.

As an example, the following code sets properties that specify using local dimension member values and recognizing only analytic workspace metadata.

 props.setProperty("HierarchyValueType", "local");
 props.setProperty("MetadataReaderMode", "10103AWONLY");

For one or more queries you can override the hierarchy value type of the ExpressDataProvider with a createCursorManager method that takes a Properties object as an input parameter.

Constructor Summary
`ExpressDataProvider(oracle.jdbc.OracleConnection connection, TransactionProvider transactionProvider)` Creates an `ExpressDataProvider` with the default characteristics.
`ExpressDataProvider(oracle.jdbc.OracleConnection connection, TransactionProvider transactionProvider, java.util.Locale locale)` Creates an `ExpressDataProvider` that provides the `String` values of an analytic workspace in the language specified by the `Locale`.
`ExpressDataProvider(oracle.jdbc.OracleConnection connection, TransactionProvider transactionProvider, java.util.Locale locale, java.util.Properties props)` Creates a new `ExpressDataProvider` that provides the `String` values of an analytic workspace in the language specified by the `Locale` and that has the characteristics specified in the `Properties` object.
`ExpressDataProvider(oracle.jdbc.OracleConnection connection, TransactionProvider transactionProvider, java.util.Properties props)` Creates a new `ExpressDataProvider` with the characteristics specified in the `Properties` object.

Method Summary
`void`	`close()` Closes the `ExpressDataProvider` and releases its associated resources.
`SpecifiedCursorManager`	`createCursorManager(CursorManagerSpecification cursorManagerSpecification, Source[] inputSources, java.util.Properties queryParameters)` Creates a `SpecifiedCursorManager` that can override the hierarchy value type of the `ExpressDataProvider`.
`SpecifiedCursorManager[]`	`createCursorManagers(CursorManagerSpecification[] cursorManagerSpecifications, Source[][] inputLists)` Creates an array of `SpecifiedCursorManager` objects.
`CursorManager[]`	`createCursorManagers(Source[] rootSources, int[] fetchSizes, CursorInfoSpecification[] cursorInfoSpecs, java.util.Properties queryProperties)` Creates an array of `ExpressDataCursorManager` objects that can override the hierarchy value type of the `ExpressDataProvider`.
`SQLCursorManager[]`	`createSQLCursorManagers(Source[] sources)` Creates a `SQLCursorManager` for each `Source` in the `sources` array.
`SQLCursorManager[]`	`createSQLCursorManagers(Source[] sources, boolean createCountColumn, java.lang.String[] generatedSQLStatements)` Creates a `SQLCursorManager` for each `Source` in the `sources` array and provides the SQL statements and a count column for each query.
`SQLCursorManager[]`	`createSQLCursorManagers(Source[] sources, java.lang.String[] generatedSQLStatements)` Creates a `SQLCursorManager` for each `Source` in the `sources` array and provides the SQL statements for each query.
`oracle.jdbc.OracleConnection`	`getConnection()` Retrieves the `oracle.jdbc.OracleConnection` object that represents the connection between the client application and the Oracle Database instance.
`MetadataProvider`	`getDefaultMetadataProvider()` Retrieves the `MetadataProvider` associated with the connection.
`void`	`initialize()` Initializes the `ExpressDataProvider`.
`boolean`	`isOpen()` Indicates whether the connection to the Oracle Database instance is currently open.

Methods inherited from class oracle.olapi.data.source.DataProvider

createConstantSource, createConstantSource, createConstantSource, createConstantSource, createConstantSource, createConstantSource, createConstantSource, createConstantSource, createCursorInfoSpecification, createCursorManager, createCursorManager, createCursorManager, createCursorManager, createCursorManagers, createCursorManagers, createCursorManagerSpecification, createListSource, createListSource, createListSource, createListSource, createListSource, createListSource, createListSource, createListSource, createListSource, createModel, createModel, createModel, createModel, createModel, createModel, createModel, createParameterizedSource, createParameterizedSource, createParameterizedSource, createParameterizedSource, createRangeSource, createRangeSource, createRangeSource, createRangeSource, createSQLCursorManager, getEmptySource, getFundamentalMetadataProvider, getTransactionProvider, getVoidSource

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExpressDataProvider

public ExpressDataProvider(oracle.jdbc.OracleConnection connection,
                           TransactionProvider transactionProvider)

Creates an ExpressDataProvider with the default characteristics.

Parameters:: connection - An oracle.jdbc.OracleConnection.; transactionProvider - An ExpressTransactionProvider.

ExpressDataProvider

public ExpressDataProvider(oracle.jdbc.OracleConnection connection,
                           TransactionProvider transactionProvider,
                           java.util.Locale locale)

Creates an ExpressDataProvider that provides the String values of an analytic workspace in the language specified by the Locale.

Parameters:: connection - An oracle.jdbc.OracleConnection.; transactionProvider - An ExpressTransactionProvider.; locale - The java.util.Locale that specifies the language to use for an analytic workspace.

ExpressDataProvider

public ExpressDataProvider(oracle.jdbc.OracleConnection connection,
                           TransactionProvider transactionProvider,
                           java.util.Properties props)

Creates a new ExpressDataProvider with the characteristics specified in the Properties object. For a list of the properties that you can set, see the class description.

Parameters:: connection - An oracle.jdbc.OracleConnection.; transactionProvider - An ExpressTransactionProvider.; props - A java.util.Properties object that specifies characteristics of the ExpressDataProvider.

ExpressDataProvider

public ExpressDataProvider(oracle.jdbc.OracleConnection connection,
                           TransactionProvider transactionProvider,
                           java.util.Locale locale,
                           java.util.Properties props)

Creates a new ExpressDataProvider that provides the String values of an analytic workspace in the language specified by the Locale and that has the characteristics specified in the Properties object. For a list of the properties that you can set, see the class description.

Parameters:: connection - An oracle.jdbc.OracleConnection.; transactionProvider - An ExpressTransactionProvider.; locale - The java.util.Locale that specifies the language to use for an analytic workspace.; props - A java.util.Properties object that specifies characteristics of the ExpressDataProvider.

Method Detail

initialize

public void initialize()
                throws java.sql.SQLException

Initializes the ExpressDataProvider. Always call this method after creating a new ExpressDataProvider.

Overrides:: initialize in class DataProvider

getConnection

public oracle.jdbc.OracleConnection getConnection()

Retrieves the oracle.jdbc.OracleConnection object that represents the connection between the client application and the Oracle Database instance.

Returns:: An oracle.jdbc.OracleConnection object that represents the connection between the client application and the Oracle Database instance.

createCursorManagers

public CursorManager[] createCursorManagers(Source[] rootSources,
                                            int[] fetchSizes,
                                            CursorInfoSpecification[] cursorInfoSpecs,
                                            java.util.Properties queryProperties)

Creates an array of ExpressDataCursorManager objects that can override the hierarchy value type of the ExpressDataProvider. The array contains one ExpressDataCursorManager for each Source in the rootSources array. You use the ExpressDataCursorManager objects to create Cursor objects that retrieve the results of the queries.

The fetchSizes and cursorInfoSpecs arrays supply a fetch size and a CursorInfoSpecification for the ExpressDataCursorManager for the corresponding Source in the rootSources array. A fetch size of -1 fetches the entire result set.

With the Properties object for the queryProperties parameter, you can specify the use local or unique dimension hierarchy member values for retrieving data for a query. The property setting must match the query. For example, if you use local values to specify a query, then the hierarchy value type must be set to local for a Cursor to retrieve data. To use local values, set the property as in the following:

 queryProperties.setProperty("HierarchyValueType", "local");

To use unique values, set the property as in the following:

 queryProperties.setProperty("HierarchyValueType", "unique");

For more information on unique and local values, see the Overview of this documentation.

Overrides:: createCursorManagers in class DataProvider

Parameters:: rootSources - An array of Source objects for which you want CursorManager objects.; fetchSizes - An array of integers that specify the fetch sizes for the Cursor objects created by the corresponding CursorManager objects.; cursorInfoSpecs - An array of CursorInfoSpecification objects for the corresponding CursorManager objects.; queryProperties - A >java.util.Properties object that specifies the use of local or unique dimension hierarchy member values.
Returns:: An array of CursorManager objects for the corresponding Source objects.

createCursorManager

public final SpecifiedCursorManager createCursorManager(CursorManagerSpecification cursorManagerSpecification,
                                                        Source[] inputSources,
                                                        java.util.Properties queryParameters)
                                                 throws CursorManagerSpecificationExpiredException,
                                                        DataProviderMismatchException,
                                                        ExpressServerException,
                                                        ObjectClosedException,
                                                        TransactionalObjectInvalidException

Creates a SpecifiedCursorManager that can override the hierarchy value type of the ExpressDataProvider. This method returns an instance of ExpressSpecifiedCursorManager. You use an ExpressSpecifiedCursorManager to create Cursor object that retrieve the results of a query.

If the Source that you used to create the CursorManagerSpecification has inputs, then with the inputSources array you must specify Source objects that can match to the inputs. Otherwise, the inputSources array can be empty. A Source that you include in the inputSources array must not have any inputs itself and it must not have any outputs.

When you create a Cursor from the ExpressSpecifiedCursorManager, you use CursorInput objects to specify values for the input Source objects. If the inputSources array is empty, then you do not have to pass in an array of CursorInput objects when creating a Cursor.

With the Properties object for the queryParameters parameter, you can specify that the ExpressSpecifiedCursorManager use local or unique dimension hierarchy member values for retrieving data for a query. The property setting must match the query. For example, if you use unique values to specify a query, then the hierarchy value type must be set to unique for a Cursor to retrieve data. To use local values, set the property as in the following:

 queryParameters.setProperty("HierarchyValueType", "local");

To use unique values, set the property as in the following:

 queryParameters.setProperty("HierarchyValueType", "unique");

For more information on unique and local values, see the Overview of this documentation.

Overrides:: createCursorManager in class DataProvider

Parameters:: cursorManagerSpecification - A CursorManagerSpecification for a Source. If the Source has inputs, then the inputSources array must provide Source objects that match to the inputs.; inputSources - An array of Source objects, one for each input of the Source used to create the CursorManagerSpecification. If that Source does not have inputs, the array can be empty.; queryParameters - A java.util.Properties object that specifies the use of local or unique dimension hierarchy member values.
Returns:: A SpecifiedCursorManager.

isOpen

public final boolean isOpen()

Indicates whether the connection to the Oracle Database instance is currently open. If it is closed, then no further access to the metadata or to the associated data is possible. If Oracle OLAP retrieved metadata before the connection was closed and cached it on the client, then it is still available for processing; however, the data might not be current.

Overrides:: isOpen in class DataProvider

Returns:: true when the connection is open; false when it is not.

getDefaultMetadataProvider

public MetadataProvider getDefaultMetadataProvider()

Retrieves the MetadataProvider associated with the connection.

Returns:: The MetadataProvider associated with the connection.

close

public void close()

Closes the ExpressDataProvider and releases its associated resources.

Overrides:: close in class DataProvider

createSQLCursorManagers

public final SQLCursorManager[] createSQLCursorManagers(Source[] sources)

Creates a SQLCursorManager for each Source in the sources array. All of the Source objects in the array must belong to the same Transaction. With a SQLCursorManager, you can obtain the SQL statements that Oracle OLAP generates for a query.

Overrides:: createSQLCursorManagers in class DataProvider

Parameters:: sources - An array of Source objects for which you want to create SQLCursorManager objects.
Returns:: An array of SQLCursorManager for the specified Source objects.

createSQLCursorManagers

public final SQLCursorManager[] createSQLCursorManagers(Source[] sources,
                                                        java.lang.String[] generatedSQLStatements)

Creates a SQLCursorManager for each Source in the sources array and provides the SQL statements for each query. This method replaces the elements of the generatedSQLStatements array with the SQL statements that the Oracle OLAP SQL generator produces for the Source in the corresponding element of the sources array.

All of the Source objects in the sources array must belong to the same Transaction. The generatedSQLStatements array must be the same size as the sources array.

Parameters:: sources - An array of Source objects for which you want SQLCursorManager objects.; generatedSQLStatements - An array of String objects that that this method replaces with the SQL statements generated for the corresponding objects in the sources array.
Returns:: An array of SQLCursorManager objects.

createSQLCursorManagers

public final SQLCursorManager[] createSQLCursorManagers(Source[] sources,
                                                        boolean createCountColumn,
                                                        java.lang.String[] generatedSQLStatements)

Creates a SQLCursorManager for each Source in the sources array and provides the SQL statements and a count column for each query. This method replaces the elements of the generatedSQLStatements array with the count column and the SQL statements that the Oracle OLAP SQL generator produces for the Source in the corresponding element of the sources array.

All of the Source objects in the sources array must belong to the same Transaction. The generatedSQLStatements array must be the same size as the sources array.

Parameters:: sources - An array of Source objects for which you want SQLCursorManager objects.; createCountColumn - A boolean that specifies whether to include a count column in the generated SQL.; generatedSQLStatements - An array of String objects that that this method replaces with the the count column and SQL statements generated for the corresponding objects in the sources array.
Returns:: An array of SQLCursorManager objects.

createCursorManagers

public final SpecifiedCursorManager[] createCursorManagers(CursorManagerSpecification[] cursorManagerSpecifications,
                                                           Source[][] inputLists)
                                                    throws DataProviderMismatchException,
                                                           ExpressServerException,
                                                           ObjectClosedException,
                                                           TransactionalObjectInvalidException

Creates an array of SpecifiedCursorManager objects. The array contains one SpecifiedCursorManager for each CursorManagerSpecification in the cursorManagerSpecifications array. The inputLists array contains the arrays of input Source objects required by the corresponding CursorManagerSpecification objects.

Parameters:: cursorManagerSpecifications - An array of CursorManagerSpecification objects for which you want CursorManager objects.; inputLists - An array of arrays of Source objects that are the input Source objects required by the CursorManagerSpecification objects.
Returns:: An array of SpecifiedCursorManager objects for the CursorManagerSpecification objects.
See Also:: DataProvider.createCursorManager(CursorManagerSpecification cursorManagerSpecification, Source[] inputSources)