|
Oracle® OLAP Java API Reference 11g Release 1 (11.1) B28128-03 |
This release of the Oracle OLAP Java API includes new features that provide the ability to do the following.
For lists of the packages, classes, fields, methods, and property settings that are new in the 11.1.0.7 release, see New Features in 11.1.0.7.
Legacy Oracle OLAP metadata objects that were created in a 10g version of Oracle Database can now exist in the same session as 11g OLAP metadata objects. This is possible because some of the top-level legacy metadata objects now have a namespace. For more information on namespaces, see the Namespaces topic.
The oracle.olapi.data.source.DataProvider class has the new ALL metadata reader mode setting, which is now the default metadata reader mode. In the ALL mode, the Oracle OLAP metadata reader recognizes 11g metadata objects and the 10g metadata object formats in the same session. For more information on metadata reader mode settings, see DataProvider Settings.
A namespace identifies the metadata format and the type of object of Oracle OLAP metadata objects that were created in a 10g version of Oracle Database. The metadata objects for a 10g cube, measure folder, dimension are represented in 11g by the oracle.olapi.metadata.mdm.MdmObject objects MdmCube, MdmOrganizationalSchema, and MdmPrimaryDimension. The getNamespace method of those objects returns the namespace. For an 11g object, the namespace is null.
The namespace of a legacy 10g metadata object appears as a prefix in the unique object identifier. The unique object ID is returned by the getID method. The namespace also appears in the Namespace attribute in the XML representation of the 10g object and in other references to the object in the XML. The version of the XML is now 1.1.
The MdmDatabaseSchema class has findOrCreate methods that take a namespace. Using such a method, an application can find a 10g metadata object but cannot create one. If an object of the specified name does not exist, Oracle OLAP creates an 11g object.
For more information on namespaces, see Using Namespaces in the class description of MdmMetadataProvider.
The new oracle.olapi.metadata.conversion package contains the class LegacyXMLConverter. With that class you can convert the XML for 10g Release 2 (10.2) OLAP metadata objects to the 11g XML format. The package also contains Exception classes for conveying problems that occur during the conversion.
You can now create an oracle.olapi.syntax.LoadCommand that specifies the use of serial or parallel processing when loading data in an analytic workspace. The LoadCommand also has a PRUNE option, which specifies that the build spawns jobs only for the partitions for which measure data exists.
The LoadCommand class now has constructor methods as well as static constant fields that produce LoadCommand objects. One of the constructors takes the name of a CubeMap. With that constructor, you can specify loading data from a source other than the default data source.
The ClearCommand and SolveCommand classes also have serial and parallel processing options.
With the oracle.olapi.syntax.AggregationFunctionExpression class, you can aggregate measure values over specified dimension members. You specify the dimension members with an AggregateOverMembersClause. You can use an AggregationFunctionExpression as the Expression for an MdmCustomMember of an MdmModel.
In an attribute column in an embedded totals (ET) view, you can now automatically populate the rows for lower levels in a dimension hierarchy with the attribute values that are mapped at a higher level. To do so, you specify true with the MdmBaseAttribute.setPopulateLineage method.
If you specify setPopulateLineage(false), then the attribute values appear only in the rows for the dimension members at the level to which the attribute is mapped. For dimension members at other levels, the attribute value is null. If you specify setPopulateLineage(true), then the attribute values appear in the rows for the members of the mapped level and for the dimension members of all levels that are descendants of the mapped level.
Populating the hierarchy lineage in an ET view makes the contents of the view more like the contents of a relational table in a star schema. For example, you could create a separate long description attribute on the dimension for each MdmDimensionLevel of the dimension. You would specify populating the lineage of those attributes by calling the setPopulateLineage(true) of each attribute. You would then make the attribute visible for a dimension level by adding the attribute to the MdmDimensionLevel with the addAttribute method.
The ET view for a hierarchy of the dimension would then have a column for each of the long description attributes. Those columns would contain the long description attribute values for the members of the mapped dimension level and for the dimension members of all levels that are descendants of the mapped level.
If the AWCubeOrganization for a cube has a materialized view option of REWRITE_MV_OPTION, then Oracle OLAP creates a materialized view for the cube that can be used by the database query rewrite system. The new REWRITE_WITH_ATTRIBUTES_MV_OPTION of AWCubeOrganization enables you to include in the rewrite MV the attributes for which the isPopulateLineage method returns true.
With the setAttributeGroupName method of an MdmBaseAttribute, you can specify a name for an attribute group. You can specify the same group name for other attributes. For example, you could create a long description attribute for each dimension level and give each attribute the group name of "LONG_DESCRIPTION". You could use the group name to identify similar kinds of attributes.
With the addObjectClassification method of an MdmObject, an application can add metadata to that object. The application can use the classification metadata for such purposes as identifying, grouping, or otherwise associating objects by classification.
You can now specify a language when mapping an attribute by using the findOrCreateAttributeMap(MdmBaseAttribute attribute, java.lang.String language) method of the oracle.olapi.metadata.mapping.DimensionMap class.
An implementation of the XMLWriterCallback interface provides Oracle OLAP the means to call back to an application while the MdmMetadataProvider is exporting the XML definition of an object. With an XMLWriterCallback, the application can specify whether or not to exclude an attribute or an owner name from the exported XML. The Oracle OLAP Java API introduced XMLWriterCallback in the 11.1.0.6 release.
In the 11.1.0.6 release, the Oracle OLAP Java API added the oracle.olapi.data.source.BuildResult class and DataProvider.executeBuild methods that take a BuildResult. With a BuildResult, an application can get the identification number for a build process. An analytic workspace automatically generates the identification number during a build. You can use the build number to track the progress of a build.
Some aspects of the Oracle OLAP Java API are much the same as in the 10g releases, such as the ability to create queries with classes in the oracle.olapi.data.source package and to retrieve the data with classes in the oracle.olapi.data.cursor package. However, in Oracle OLAP 11g Release 1 (11.1) the API has many new features. The major new features include the abilities to do the following:
The Oracle OLAP Java API now has the ability to create and maintain persistent metadata objects. The Oracle Database stores the metadata objects in the Oracle data dictionary.
An application maps the metadata objects to relational structures in an Oracle Database instance or to expressions that provide a data source. The application can deploy the metadata as relational OLAP (ROLAP) objects or it can deploy the metadata in an analytic workspace. For information on the advantages of the deployment types, see Oracle OLAP User's Guide.
To provide this new functionality, the Oracle OLAP Java API substantially revises the metadata model. The new model includes several new packages and has significant changes to some existing packages. For example, the oracle.olapi.metadata.mdm package has many new classes. It also has many new methods added to existing classes.
An application creates most metadata objects with findOrCreate methods of the owning object. For example, the following code finds the MdmStandardDimension named PRODUCTS_AWJ or creates a standard dimension with that name if it does not already exist. The mdmDBSchema object is the MdmDatabaseSchema that owns the dimension.
MdmStandardDimension prodDim =
mdmDBSchema.findOrCreateStandardDimension("PRODUCTS_AWJ");
Some classes and methods are deprecated in the new model. For example, all of the classes in the oracle.olapi.metadata.mtm package are deprecated, and methods of other classes that use the mtm classes are also deprecated. Some mtm classes mapped transient mdm objects to relational database structures, such as columns in tables and views. Other mtm specified how Oracle OLAP performed operations such as aggregation or allocation of the values of custom measures. That functionality is replaced by classes in the oracle.olapi.metadata subpackages deployment, mapping, and mdm, and the oracle.olapi.syntax package. With the new classes, an application can create permanent metadata objects, map them to data sources, and specify the operations that provide values for measures.
Because the metadata objects exist in the Oracle data dictionary, an Oracle Database DBA can restrict access to certain types of the metadata objects. A client application can set such restrictions by sending SQL commands, using the JDBC API, through the JDBC connection for the user session.
An application can now define, build, and maintain analytic workspaces. This new functionality is provided by classes in the oracle.olapi.metadata subpackages deployment, mapping, and mdm, and the oracle.olapi.syntax package. This functionality replaces the Oracle OLAP Analytic Workspace Java API, which is entirely deprecated in this release.
With the classes in the oracle.olap.syntax package, an application can create Java objects that are based on SQL expressions, functions, operators, and conditions. The SyntaxObject class has static methods that an application can use to convert SQL expressions into Java objects or to get the SQL syntax from a Java object.
An application can create the Java objects by using the SyntaxObject.fromSyntax method or by using a constructor. For example, the following example creates a StringExpression using a fromSyntax method and another StringExpression using a constructor method. The mp object is the MdmMetadataProvider for the session.
Note that the string in the fromSyntax method is enclosed in single quotation marks inside the double quotation marks because the string is a SQL string literal. The single quotation marks are not required when using the constructor for a StringExpression.
The example then calls the getValue method on both StringExpression objects and displays the values returned. It also calls the toSyntax method on one StringExpression and displays the result.
StringExpression exp = (StringExpression)
SyntaxObject.fromSyntax("'Hello world from syntax.'", mp);
StringExpression strExp =
new StringExpression("Hello world using constructor.");
println(exp.getValue() + " Output of exp.getValue().");
println(strExp.getValue() + " Ouput of strExp.getValue().");
println(strExp.toSyntax()+ " Ouput of strExp.toSyntax().");
The output of the code is the following:
Hello world from syntax. Output of exp.getValue(). Hello world using constructor. Output of strExp.getValue(). 'Hello world using constructor.' Output of strExp.toSyntax().
Another new feature is the ability to have multiple user sessions that share the same JDBC connection to the Oracle Database instance and that share the same cache of metadata objects. This ability is provided by the UserSession class in the oracle.olapi.session package.