3 Discovering Metadata

Connecting to Oracle OLAP

To connect to the Oracle OLAP server in an Oracle Database instance, an OLAP Java API client application uses the Oracle implementation of the Java Database Connectivity (JDBC) API from Sun Microsystems. The Oracle JDBC classes that you use to establish a connection to Oracle OLAP are in the Java archive file ojdbc5.jar. For information about getting that file, see Appendix A, "Setting Up the Development Environment".

oracle.jdbc.OracleConnection conn = null;
try 
{
  OracleDataSource ods = new OracleDataSource();
  ods.setURL(props.getProperty("url"));
  ods.setUser(props.getProperty("user"));
  ods.setPassword(props.getProperty("password"));
  conn = (oracle.jdbc.OracleConnection) ods.getConnection();
}
catch(SQLException e) 
{
  System.out.println("Connection attempt failed. " + e);
}

DataProvider dp = new DataProvider();
try
{
  UserSession session = dp.createSession(conn);
}
catch(SQLException e)
{
  System.out.println("Could not create a UserSession. " + e);
}

dp.close();     // dp is the DataProvider

try
{
  conn.close();     // conn is the OracleConnection
}
catch(SQLException e) 
{
  System.out.println("Cannot close the connection. " + e);
}

Overview of the Procedure for Discovering Metadata

The OLAP Java API provides access to the data of an analytic workspace or that is in relational structures. This collection of data is the data store for the application.

Potentially, the data store includes all of the subchemas of the MdmRootSchema. However, the scope of the data store that is visible when an application is running depends on the database privileges that apply to the user ID through which the connection was made. A user can see all of the MdmDatabaseSchema objects that exist under the MdmRootSchema, but the user can see the objects that are owned by an MdmDatabaseSchema only if the user has access rights to the metadata objects. For information on granting access rights and on object security, see Oracle OLAP User's Guide.

Creating an MdmMetadataProvider

An MdmMetadataProvider gives access to the metadata in a data store by providing the MdmRootSchema. Before you can create an MdmMetadataProvider, you must create a DataProvider as described in Chapter 4, "Creating Metadata and Analytic Workspaces". Example 3-4 creates an MdmMetadataProvider. In the example, dp is the DataProvider.

MdmMetadataProvider mp = null;
try
{
  mp = (MdmMetadataProvider) dp.getMdmMetadataProvider();
}
catch (Exception e) 
{
  println("Cannot get the MDM metadata provider. " + e);
}

Getting the MdmSchema Objects

The Oracle OLAP metadata objects that provide access to the data in a data store are organized by MdmSchema objects. The top-level MdmSchema is the MdmRootSchema. Getting the MdmRootSchema is the first step in exploring the metadata in your data store. From the MdmRootSchema, you can get the MdmDatabaseSchema objects. The MdmRootSchema has an MdmDatabaseSchema for each database user. An MdmDatabaseSchema can have MdmOrganizationalSchema objects that organize the metadata objects owned by the MdmDatabaseSchema.

Example 3-5 demonstrates getting the MdmRootSchema, the MdmDatabaseSchema objects under it, and any MdmOrganizationalSchema objects under them.

private void getSchemas(MdmMetadataProvider mp)
{
  MdmRootSchema mdmRootSchema = (MdmRootSchema)mp.getRootSchema();
  List<MdmDatabaseSchema> dbSchemas = mdmRootSchema.getDatabaseSchemas();
  for(MdmDatabaseSchema mdmDBSchema : dbSchemas)
  {
    println(mdmDBSchema.getName());
    getOrgSchemas(mdmDBSchema);
  } 
}

private void getOrgSchemas(MdmSchema mdmSchema)
{
  ArrayList orgSchemaList = new ArrayList();

  if (mdmSchema instanceof MdmDatabaseSchema)
  {
    MdmDatabaseSchema mdmDBSchema = (MdmDatabaseSchema) mdmSchema;
    orgSchemaList = (ArrayList) mdmDBSchema.getOrganizationalSchemas();
  }
  else if (mdmSchema instanceof MdmOrganizationalSchema)
  {
    MdmOrganizationalSchema mdmOrgSchema = (MdmOrganizationalSchema) 
                                            mdmSchema;
    orgSchemaList = (ArrayList) mdmOrgSchema.getOrganizationalSchemas();
  }

  if (orgSchemaList.size() > 0)
  {
    println("The MdmOrganizationalSchema subschemas of "
            + mdmSchema.getName() + " are:");
    Iterator orgSchemaListItr = orgSchemaList.iterator();
    while (orgSchemaListItr.hasNext())
    {
      MdmOrganizationalSchema mdmOrgSchema = (MdmOrganizationalSchema)
                                            orgSchemaListItr.next();
      println(mdmOrgSchema.getName());
      getOrgSchemas(mdmOrgSchema);
    }
  }
  else
  {
    println(mdmSchema.getName() + " does not have any" +
            " MdmOrganizationalSchema subschemas.");
  }
}

Rather than getting all of the MdmDatabaseSchema objects, you can use the getDatabaseSchema method of the MdmRootSchema to get the schema for an individual user. Example Example 3-6 demonstrates getting the MdmDatabaseSchema for the GLOBAL user.

MdmDatabaseSchema mdmGlobalSchema = mdmRootSchema.getDatabaseSchema("GLOBAL");

Getting the Contents of an MdmSchema

From an MdmSchema, you can get all of the subschema, MdmCube, MdmPrimaryDimension, and MdmMeasure objects that it contains. Also, the MdmRootSchema has an MdmMeasureDimension that has a List of all of the available MdmMeasure objects.

If you want to display all of the dimensions and methods that are owned by a particular user, then you could get the lists of dimensions and measures from the MdmDatabaseSchema for that user. Example 3-7 gets the dimensions and measures from the MdmDatabaseSchema from Example 3-6. It displays the name of each dimension and measure.

private void getObjects(MdmDatabaseSchema mdmGlobalSchema)
{
  List dimList = mdmGlobalSchema.getDimensions();
  String objName = mdmGlobalSchema.getName() + " schema";
  getNames(dimList, "dimensions", objName);

  List measList = mdmGlobalSchema.getMeasures();
  getNames(measList, "measures", objName);
}

private void getNames(List objectList, String objTypes, String objName)
{
  println("The " + objTypes + " of the " + objName + " are:");
  Iterator objListItr = objectList.iterator();
  while (objListItr.hasNext())
  {
    MdmObject mdmObj = (MdmObject) objListItr.next();
    println(mdmObj.getName());
  }
}

The output of Example 3-7 is the following.

The dimensions of the GLOBAL schema are:
CHANNEL_AWJ
CUSTOMER_AWJ
PRODUCT_AWJ
TIME_AWJ
The measures of the GLOBAL schema are:
UNIT_COST
UNIT_PRICE
UNITS
SALES

To display just the dimensions and measures associated with an MdmCube, you could use the getTopLevelObject method of an MdmDatabaseSchema to get the cube and then get the dimensions and measures of the cube. Example 3-8 gets an MdmCube from the MdmDatabaseSchema of Example 3-6 and displays the names of the dimensions and measures associated with it using the getNames method of Example 3-7.

private void getCubeObjects(MdmDatabaseSchema mdmGlobalSchema)
{
  MdmCube mdmUnitsCube = (MdmCube)
                     mdmGlobalSchema.getTopLevelObject("PRICE_CUBE_AWJ");
  String objName = mdmUnitsCube.getName() + " cube";
  List dimList = mdmUnitsCube.getDimensions();
  getNames(dimList, "dimensions", objName);

  List<MdmMeasure> measList = mdmUnitsCube.getMeasures();
  getNames(measList, "measures", objName);
}

The output of Example 3-8 is the following.

The dimensions of the PRICE_CUBE_AWJ cube are:
TIME_AWJ
PRODUCT_AWJ
The measures of the PRICE_CUBE_AWJ cube are:
UNIT_COST
UNIT_PRICE

Getting the Objects Contained by an MdmPrimaryDimension

In discovering the metadata objects to use in creating queries and displaying the data, an application typically gets the MdmSubDimension components of an MdmPrimaryDimension and the MdmAttribute objects that are associated with the dimension. This section demonstrates getting the components and attributes of a dimension.

private void getHierarchiesAndLevels(MdmDatabaseSchema mdmGlobalSchema)
{
  MdmPrimaryDimension mdmCustDim = (MdmPrimaryDimension)
                     mdmGlobalSchema.getTopLevelObject("CUSTOMER_AWJ");
  List<MdmHierarchy> hierList = mdmCustDim.getHierarchies();
  println("The hierarchies of the dimension are:");
  for (MdmHierarchy mdmHier : hierList)
  {
    println(mdmHier.getName());
    if (mdmHier instanceof MdmLevelHierarchy)
    {
      MdmLevelHierarchy mdmLevelHier = (MdmLevelHierarchy) mdmHier; 
      List<MdmHierarchyLevel> hierLevelList = mdmLevelHier.getHierarchyLevels();
      println("  The levels of the hierarchy are:");
      for (MdmHierarchyLevel mdmHierLevel : hierLevelList)
      {
        println("  " + mdmHierLevel.getName());
      }
    }
  }
}

The hierarchies of the dimension are:
SHIPMENTS
  The levels of the hierarchy are:
  TOTAL_CUSTOMER
  REGION
  WAREHOUSE
  SHIP_TO
MARKETS
  The levels of the hierarchy are:
  TOTAL_MARKET
  MARKET_SEGMENT
  ACCOUNT
  SHIP_TO

private void getAttributes(MdmDatabaseSchema mdmGlobalSchema)
{
  MdmTimeDimension mdmTimeDim = (MdmTimeDimension)
                     mdmGlobalSchema.getTopLevelObject("TIME_AWJ");
  List attrList = mdmTimeDim.getAttributes();
  Iterator attrListItr = attrList.iterator();
  println("The MdmAttribute objects of " + mdmTimeDim.getName() + " are:");
  while (attrListItr.hasNext()) 
  {
    MdmAttribute mdmAttr = (MdmAttribute) attrListItr.next();
    println("  " + mdmAttr.getName());
  }

  MdmAttribute mdmParentAttr = mdmTimeDim.getParentAttribute();
  println("The parent attribute is " + mdmParentAttr.getName() + ".");
}

The MdmAttribute objects of TIME_AWJ are:
  LONG_DESCRIPTION
  SHORT_DESCRIPTION
  END_DATE
  TIME_SPAN
The parent attribute is PARENT_ATTRIBUTE.

Getting the Source for a Metadata Object

A metadata object represents a set of data, but it does not provide the ability to create queries on that data. The object is informational. It records the existence, structure, and characteristics of the data. It does not give access to the data values.

To access the data values for a metadata object, an application gets the Source object for that metadata object. A Source for a metadata object is a primary Source.

To get the primary Source for a metadata object, an application calls the getSource method of that metadata object. For example, if an application needs to display the quantity of product units sold during the year 1999, then it must use the getSource method of the MdmMeasure for that data, which is mdmUnits in the following example.

Source units = mdmUnits.getSource();