Skip Headers

Oracle® Developer Suite Release Notes 10g (9.0.4) for Windows, Linux, Solaris, and HP-UX Part No. B10668-03 |
| Library | Contents | Index

# 6 Oracle Business Intelligence Beans

This chapter discusses the following Oracle Business Intelligence Beans (BI Beans) topics:

- Section 6.1, "Introduction"

- Section 6.2, "General Issues and Workarounds"

- Section 6.3, "Platform-specific Issues and Workarounds"

- Section 6.4, "Configuration Issues and Workarounds"

- Section 6.5, "Administration Issues and Workarounds"

- Section 6.6, "Documentation Errata"

## 6.1 Introduction

Oracle Business Intelligence Beans (hereinafter referred to as "BI Beans") is a set of standards-based JavaBeans that provides analysis-aware application building blocks designed for Oracle OLAP. Using Oracle JDeveloper and BI Beans, you can build Web applications quickly and easily. These applications expose the advanced analytic features of the Oracle database both to casual information viewers and to high-end users who require complete ad-hoc query and analysis functionality. For more information, consult the following:

- The Oracle Developer Suite 10g Installation Guide -- available from the Oracle Developer Suite product CD-ROM or DVD, or the Oracle Developer Suite Documentation Library.

- Certification and System Requirements -- can be downloaded from the BI Beans product area on Oracle Technology Network (`http://otn.oracle.com/products/bib/`); includes database versions and patch sets that are certified for this release as well as certified deployment environments.

- "Getting Started with BI Beans" -- a topic in the JDeveloper Help system; includes links to tutorials.

- BI Beans API Reference -- accessible from the JDeveloper Help menu.

- BI Beans samples -- published on the BI Beans product area on Oracle Technology Network; designed to assist you in coding common application tasks.

Note: BI Beans release 10g (9.0.4) is certified with J2SE 1.4.1. There are issues with this configuration in the areas of keyboard and mouse navigation and of dialog focus, as well as other minor issues, which will be addressed in a later release.

## 6.2 General Issues and Workarounds

### 6.2.1 Tutorials and samples

When you install the sample database schema, you might get an error that says the SH account is locked. If you want to remove the SH metadata and use only that from BIBDEMO, then the DBA must unlock the account. If you do not want to remove the SH metadata, then you can ignore this error and allow the installation script to continue. BI Beans will then display both BIBDEMO and SH metadata.

### 6.2.2 QueryBuilder and queries

- If you attempt to update a query that uses the NASuppression option, then an OLAP API exception might be generated. This problem does not exist when running against Oracle OLAP 9.2.0.4 or higher.

- BI Beans does not support the interspersing of symmetric and asymmetric drill operations. That is, the `AsymmetricDrilling` property of a `Query` object should not be changed during that object's lifetime.

- In DataDirector, if you set the `SuppressionState` method to either `DataDirector.ZERO_SUPPRESSION` or `DataDirector.NA_ZERO_SUPPRESSION`, then the result is the same: both zeros and nulls are suppressed in the results.

- You cannot save a favorite that references both a calculation and another favorite. Attempting to do so results in a null pointer exception.

- When you use QueryBuilder to create an asymmetric query, changes that you make on the Layout panel should be applied to the presentation before making changes to the Dimensions panel. Otherwise an exception will occur.

- In a query, if you create an asymmetric top/bottom step whose selection depends on a dimension that is on the page edge, then an error is generated. This problem does not exist in Oracle OLAP 9.2.0.4 and higher. If you are running against an earlier version of Oracle OLAP, then you can work around the problem by qualifying the measure to a specific dimension member from the page edge.

- If a query that you save in BI Beans 9.0.3 or 9.0.4 includes a favorite that references a custom measure, then that query cannot be used with BI Beans 9.0.2.

- In an Oracle9i (9.2.0.3) database, if you query for dimension members that have a sibling relationship, then you might encounter error number BIB-9509. To avoid this error, set the following parameter in the database's `init.ora` file: `_multi_join_key_table_lookup=false`.

### 6.2.3 Presentations

- Because of Sun J2SE 1.4 regression bug 4749538, pie graphs and other graphs with circular components may not render optimally. You can resolve this issue by using graphic anti-aliasing on the graph and removing 3D effect, if it has been applied.

- To ensure that HTML presentations work as expected when they are placed in frames, you must configure the `EventTarget` of the `BIConstants.PAGE_EVENT` of the FindMember bean to target the frame that contains the presentation. For example, if the presentation frame is named `pres_frame`, then you would add code such as the following to the FindMember JSP page:

      <%@ page import="oracle.dss.thin.beans.BIConstants"%>
      <%@ page import="oracle.dss.thin.beans.EventTargetImpl"%>
      <%@ page import="oracle.dss.thin.beans.dataView.FindMember"%>
      ...
      /orabi:BIThinSession>
      <%
      FindMember f = (FindMember)pageContext.findAttribute("findMember");
      EventTargetImpl target=(EventTargetImpl)f.getEventTarget(BIConstants.PAGE_
      EVENT);
      target.setTargetFrame("pres_frame");
      %>

- If a number format includes a locale-based ISO currency symbol, then that symbol will not be saved. When you load the presentation, the standard locale-based symbol (such as "$") will be displayed instead.

### 6.2.4 BI Beans Catalog

- Previous releases of the BI Beans Catalog did not save presentations or selections that have long dimension names. If you encounter this problem, then you can install the 9.0.3.2 (or higher) release of the Catalog to correct it. Alternatively, if you want to continue using an earlier version of the Catalog, then you can use the following workaround. Copy the SQL*Plus commands that are provided below into a script named `bi_fixcolumnwidth.sql`. You can then call this script with the `@bi_fixcolumnwidth` command:

      alter table bism_objects modify comp_subtype1 varchar2(256);
      alter table bism_objects modify comp_subtype2 varchar2(512);
      alter table bism_objects modify comp_subtype3 varchar2(1333);
      drop type bism_objects_table_t;
      drop type bism_objects_table_new_t;
      create or replace type bism_objects_obj_t as object
      (
      USER_VISIBLE varchar2(1),
      OBJECT_TYPE_ID number(5),
      VERSION number(6),
      TIME_DATE_CREATED date,
      TIME_DATE_MODIFIED date,
      OBJECT_ID raw(16),
      CONTAINER_ID raw(16),
      FOLDER_ID raw(16),
      CREATED_BY raw(16),
      LAST_MODIFIED_BY raw(16),
      OBJECT_NAME varchar2(1333),
      TITLE varchar2(128),
      APPLICATION varchar2(256),
      DATABASE varchar2(256),
      DESCRIPTION varchar2(1333),
      KEYWORDS varchar2(1333),
      XML clob,
      APPLICATION_SUBTYPE1 varchar2(32) ,
      COMP_SUBTYPE1 varchar2(256),
      COMP_SUBTYPE2 varchar2(512) ,
      COMP_SUBTYPE3 varchar2(1333)
      );
      /
      create or replace type bism_objects_obj_new_t as object
      (
      USER_VISIBLE varchar2(1),
      OBJECT_TYPE_ID number(5),
      VERSION number(6),
      TIME_DATE_CREATED date,
      TIME_DATE_MODIFIED date,
      OBJECT_ID raw(16),
      CONTAINER_ID raw(16),
      FOLDER_ID raw(16),
      CREATED_BY VARCHAR2(64),
      LAST_MODIFIED_BY VARCHAR2(64),
      OBJECT_NAME varchar2(1333),
      TITLE varchar2(128),
      APPLICATION varchar2(256),
      DATABASE varchar2(256),
      DESCRIPTION varchar2(1333),
      KEYWORDS varchar2(1333),
      XML clob,
      APPLICATION_SUBTYPE1 varchar2(32) ,
      COMP_SUBTYPE1 varchar2(256),
      COMP_SUBTYPE2 varchar2(512) ,
      COMP_SUBTYPE3 varchar2(1333)
      );
      /
      create or replace type bism_objects_table_t as table of bism_objects_obj_t;
      /
      create or replace type bism_objects_table_new_t as table of bism_objects
      obj_new_t;
      /

- When you use JDeveloper to copy objects to the BI Beans Catalog, you specify the Catalog User in the first page of the Copy Objects to Remote Catalog wizard. This user must have WRITE (or higher) access to the root folder of the runtime Catalog.

- The following characters are not allowed in object names: `\ / : * ? < > |`.

- If you encounter performance issues on a WAN during the copying of objects to and from the BI Beans Catalog, then Oracle recommends that you use the Oracle9i OCI drivers instead of the thin JDBC drivers, as described in Section 6.4.1, "JDBC Drivers".

- You must ensure that the Oracle database is compatible with the character set that is being used for the names of objects that are being saved and restored to the BI Beans Catalog. That is, the database character set must be the same as or a superset of the Catalog character set.

- If a folder in the BI Beans Catalog contains an OLAP Catalog object (that is, a metadata object from the OLAP Catalog), then if you save a BI Beans object with the same name into that same folder, you create a naming conflict. Although the new object is saved, when you run the application, you will not see the newly-saved object in the BI Beans Explorer and it will not be loaded. You must either rename the object or remove it from the appropriate BI Beans Catalog (that is, local or remote).

- You should use the BI Beans Explorer for file operations in the local file-based Catalog, rather than using your operating system's methods for performing such operations. Each BI Designer has its own local Catalog. To run the BI Beans Explorer to show the local Catalog for one BI Designer, follow these steps:

  1. Open a command prompt and navigate to `oracle_home``/bibeans/bin`.

  2. Enter `bi_explorer.bat` (on Windows) or `bi_explorer.csh` (Linux, Solaris, and HP-UX). BI Beans Explorer starts.

  3. In BI Beans Explorer, from the File menu, choose Connect. The Connect to Catalog dialog appears.

  4. Select Choose. The Choose Catalog wizard starts.

  5. In the first wizard page, specify File as the Catalog Type, then choose Next.

  6. In the second page, specify the root directory. To locate the correct directory to enter, start JDeveloper. In your current project, right-click the BI Designer that contains the local file-based Catalog, and choose Settings. Click the Design Settings tab. The root directory is the path that is specified in the Directory field.

  7. Choose Finish to return to the Connect to Catalog dialog.

  8. Specify a name in the Username field. This is the name that will appear in the Last modified by field in BI Beans Explorer.

  9. Choose OK. The local catalog appears. You can use BI Beans Explorer to manipulate objects in this catalog.

### 6.2.5 General deployment issues

In HTML-client applications, requirements for image generation on Linux, Solaris, and HP-UX differ depending on which JDK you use, as follows:

- JDK 1.3 -- X server must be running on the middle tier. One option is to use X Virtual Frame Buffer (XVFB), which can run in "headless" environments -- that is, on computers that lack frame buffer hardware. You can download XVFB for Sun Solaris from Oracle Technology Network (`http://otn.oracle.com/products/ias/ias_utilities.html`). XVFB for other platforms must be downloaded from the platform vendor's Web site.

- J2SE 1.4 -- X server is not required. However, you must add the following Java `Option -Djava.awt.headless=true`, as described in the Help topic "Requirements for the Deployment Environment."

- You can deploy BI Beans applications to BEA WebLogic Server. For details, see Deploying Applications to BEA WebLogic Server, which is available from the BI Beans product area on Oracle Technology Network (`http://otn.oracle.com/products/bib/`)

### 6.2.6 Configuration steps for deploying HTML-client applications

#### 6.2.6.1 Deploying to OC4J

You must ensure that you are using the correct JDBC files, as follows:

- OC4J in Oracle Application Server (9.0.3 or 10g) -- You cannot deploy a BI Beans application to the OC4J instance that is part of Oracle Application Server 10g without first configuring it as described in the technical note Setting Up a Separate OC4J Instance for a BI Beans Application, which is available from the BI Beans product area on Oracle Technology Network (`http://otn.oracle.com/products/bib/`). There are two versions of this technical note. Refer to the one that is appropriate for your platform.

- OC4J that was downloaded from Oracle Technology Network -- If you are deploying to a standalone OC4J instance that you downloaded from Oracle Technology Network, then you must reconfigure OC4J as follows:

  1. Stop OC4J.

  2. Rename `oc4j_home``/jdbc/lib` to `oc4j_home``/jdbc/lib.old`.

  3. Create a new directory named `oc4j_home``/jdbc/lib`.

  4. Copy the files `classes12.jar`, `classes12dms.jar`, and `nls_charset12.jar` from the `oracle_home``/bibeans/jdbc/lib_92` directory to the new directory that you created in the previous step.

  5. You can now start OC4J and deploy and run a BI Beans application.

#### 6.2.6.2 Migrating Applications Deployed to OC4J

If you have an Oracle BI Beans 9.0.3 application that you want to deploy to OC4J 10g (9.0.4), then you must perform the following steps:

1. Copy the `BITags.tld` file from the `public_html/webapp` directory to the `public_html/WEB-INF` directory.

2. Open `web.xml` and change the value of the `<taglib-location>` element to the new location of `BITags.tld`. For example:

       <taglib>
         <taglib-uri>http://xmlns.oracle.com/bibeans/</taglib-uri>
         <taglib-location>/WEB-INF/BITags.tld</taglib-location>
       </taglib>

   Note: If you use Oracle9i JDeveloper (9.0.4) to insert a new tag into the existing 9.0.3 Oracle BI Beans application, then the preceding changes happen automatically.

#### 6.2.6.3 Deploying to Tomcat

Before you package a BI Beans application for deployment to Tomcat, you must edit the application's `web.xml` file to add a leading forward slash (/) to the `url-pattern` element. The following example shows the `servlet-mapping` element in the application's `web.xml` file. The forward slash (shown with emphasis) has been added to the `url-pattern`:

    <servlet-mapping>
       <servlet-name>webapp</servlet-name>
       <url-pattern>/webapp</url-pattern>
    </servlet-mapping>

#### 6.2.6.4 Deploying to JBoss

Before you package a BI Beans application for deployment to JBoss, you must edit the application's `application.xml` file to add a leading forward slash (/) to the `context-root` element. The following example shows the `web` element in the application's `application.xml` file, which is packaged in the generated EAR file. The forward slash (shown with emphasis) has been added to the `context-root`:

    <web>
       <web-uri>uixappz.war</web-uri>
       <context-root>/uixapp</context-root>
    </web>

### 6.2.7 Deploying to Java Web Start

Java applet deployments are not supported for this release. However, you can use Java Web Start to deploy a BI Beans Java-client application, as shown in the following outline. References apply to version 1.4.2; check the Sun Web site for updates. You can access documentation for version 1.4.2 from `http://java.sun.com/products/javawebstart/developers.html`.

Note: To deploy to Java Web Start successfully, you must compile the application using Sun's JDK.

1. Configure your Web server for Java Web Start, as described in the Java Web Start Developer's Guide (`http://java.sun.com/j2se/1.4.2/docs/guide/jws/developersguide/contents.html`).

2. Use JDeveloper to deploy the Java-client application, as usual. In the deployment profile, you must:

   - Deploy the application as a JAR file.

   - Include the following libraries: BIBEANS Runtime, BC4J Runtime, OLAP API 92, and Oracle JDBC 92.

3. You must sign the application JAR file. For more information, see (for Solaris) `http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/jarsigner.html` or (for Windows) `http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/jarsigner.html`.

4. Generate the JNLP file (the configuration file for Java Web Start) for the application, then set all permissions for the `<security>` element.

5. Still in the JNLP file, set `<j2se version>` to 1.3. For example:

   `<resources> <j2se version="1.3"/> <jar .../> </resources>`

   Note: This step is necessary to work around a bug in Java Web Start with J2SE 1.4. If you must use J2SE 1.4, then you must use JDK version 1.4.2 or higher, which fixes this bug.

6. Copy the signed JAR file and the JNLP file to your Web server.

7. Create an HTML page that opens the JNLP file.

### 6.2.8 Internationalization issues

- The default character set for exporting data is UTF-8. To use a different character set, you must specify the export character encoding, as follows:

  - Generated JSP application -- Set export encoding using the `setExportCharacterEncoding` method in the `BIThinSession` tag on the export page. For example:

        <orabi:BIThinSession id="BIThinSession1"
        configuration="/Project1BIConfig1.xml">
        <orabi:Presentation id="untitled1_Presentation1"
        location="Presentation1"/>
        <orabi:DialogLink id="untitled1_DialogLink1"
        presentationId="untitled1_Presentation1"
        targetPage="untitled2.jsp" targetToolId="untitled2_ExportOptions1"
        text="Export" />
        <% untitled1_Presentation1.setExportCharacterEncoding("SJIS"); %>
        </orabi:BIThinSession>

  - Generated uiXML application -- Modify the `biuixapp` `n`.`java` file, where n is a unique number in the JDeveloper project, by setting `dataview.setExportCharacterEncoding` in the `Analyze_preRendering()` method. For example: `dataview.setExportCharacterEncoding("SJIS")`

  - Generated servlet application -- Include the `exportCharacterEncoding` parameter in the `web.xml` file on the project node. Use the IANA encoding name, such as Shift-JIS. For example: `exportCharacterEncoding=Shift-JIS`

- When you run a JSP, if the value of the `charset` attribute in the JSP encoding does not match the value in the BIThinSession tag, then an error is generated. You can work around this problem either by ensuring that the values match or by removing the `charset` value from the BIThinSession.

- Due to a bug in the OLAP option of Oracle9i Release 2 (9.2.0.4), if the character set of the Oracle database is a multibyte character set, then an exception occurs when you attempt to access data. If your schema requires a multibyte character set, then contact Oracle Support for information about the availability of a patch to correct this problem.

### 6.2.9 Accessibility limitations

- The current version of the JAWS screen reader does not identify and read tables in Java applications. This problem occurs in the JDeveloper Help system, which incorporates the BI Beans Help system. You can access both the standalone BI Beans Help system and the integrated JDeveloper Help system from Oracle Technology Network, where they are published in a format that allows tables to be read correctly by JAWS.

- Other accessibility issues include the following:

  - Keyboard access does not work in the Hidden Items panel of the QueryBuilder.

  - If you are using J2SE 1.4.1, then you cannot access toolbar buttons with the keyboard.

  - In some cases, the Esc key does not dismiss the panel.

  - For combo boxes in which you choose a line thickness, JAWS reads the label incorrectly. Instead of reading "Line Thickness combo box <number of pixels>," JAWS reads "Line Width combo box <number of pixels>."

  - JAWS does not read the description for some of the panels in the OLAP Connection wizard.

  - If you are using J2SE 1.4.1, then shortcut keys do not work correctly in the New Presentation wizard.

  - In all graph axis UI panels, pressing the Tab key does not move the focus correctly.

## 6.3 Platform-specific Issues and Workarounds

There are no known platform-specific issues.

## 6.4 Configuration Issues and Workarounds

### 6.4.1 JDBC Drivers

#### 6.4.1.1 Upgrading the drivers automatically

BI Beans requires the Oracle9i Release 2 JDBC drivers, which ship with BI Beans. However, because JDeveloper ships with the Release 1 drivers, you cannot perform any BI Beans-related action until you have run the upgrade program, which you are prompted to do whenever you attempt to access a BI Beans designtime wizard or to open an object from a BI Designer.

Note: Because the location of the JDBC JAR files has changed in BI Beans 10g (9.0.4), you must upgrade even if you did so in release 9.0.3.

The upgrade program performs these steps:

- It copies the Release 2 JDBC JAR files from the `oracle_home``/bibeans/jdbc/lib_92` directory to the `oracle_home``/jdev/lib/patches` directory. This change affects the entire JDeveloper environment.

- The Project Settings are handled automatically for projects to which you add BI Beans objects.

These automatic steps ensure that you have the right drivers and the right designtime settings for any new BI Beans projects that you might create and for any existing projects to which you have made additions.

#### 6.4.1.2 Upgrading the drivers manually

If you have projects that are not upgraded automatically, then follow these steps to run and deploy them:

- To run -- Before you run the application, edit its Project Settings, as follows. For step-by-step instructions, see the Oracle Developer Suite 10g Installation Guide.

  - For Linux, Solaris, and HP-UX platforms, add `-Djava.ext.dirs=``oracle_home``/jdev/lib/patches` to the Java Options, replacing `oracle_home` with the full path. For Windows, add `oracle_home``\jdev\lib\patches`. This setting is critical for HTML-client applications, less so for Java-client applications.

  - Substitute Oracle JDBC 92 for Oracle JDBC in the Selected Libraries list.

- To deploy -- Before you create a deployment profile in JDeveloper, do one of the following:

  - For HTML-client applications, consult the technical note Setting Up a Separate OC4J Instance for a BI Beans Application, which is available from the BI Beans product area on Oracle Technology Network (`http://otn.oracle.com/docs/products/bib/`). There are two versions of this technical note. Refer to the one that is appropriate for your platform.

  - For Java-client applications, if you already edited the Projects Settings to substitute Oracle JDBC 92 for Oracle JDBC, then no additional changes are needed. If not, then edit the Project Settings, as described above.

#### 6.4.1.3 Restoring the original drivers

To restore the original drivers, follow these steps:

1. Delete `classes12.jar`, `classes12dms.jar`, and `nls_charset12.jar` from the `oracle_home``/jdev/lib/patches` directory.

2. Remove the Java Option `-Djava.ext.dirs`.

3. Remove Oracle JDBC 92 from the selected libraries list and replace it with Oracle JDBC.

### 6.4.2 Changing from the thin to the thick drivers

If you want an application to use the Oracle JDBC Thick (OCI) driver rather than the default Oracle JDBC Thin (Pure Java) driver, and you are using the default pluggable connection drivers that ship with BI Beans, then you must edit the application configuration file. You can do this in either of two ways, as follows:

- By editing the file in JDeveloper, where the configuration file was generated by the BI Designer -- Right-click the BI Designer and choose Settings. Select the Run Settings tab, then choose either New or Edit for the connection that you want to change and follow the wizard that appears. The driver type is part of the connection definition. You can specify a connection for either or both the BI Beans Catalog and Data Source.

- By editing the file by hand -- Open the file, which you will find in the `src` directory under the `project` directory. Its filename will be `project_name` `biconfig``#`.`xml`, where # is the unique number in the JDeveloper project. Locate the `<PersistenceConnection>` element (for the BI Beans Catalog connection) and the `<OLAPConnection>` element (for the data connection). For either or both, change the value of `JdbcDriverType` to "`oci8`".

### 6.4.3 BI Beans configuration diagnostic utility

BI Beans includes a utility that examines and reports on the configuration of your client environment. The purpose of the configuration diagnostic utility is to gather information about your configuration in order to diagnose problems. It displays information such as the release numbers for BI Beans, JDeveloper, and the Oracle database, and it runs diagnostic tests against the OLAP Catalog metadata. For additional information, see `oracle_home``/bibeans/bin/bi_checkconfig.html`.

Note that you must upgrade to the new version of the JDBC drivers before you run the utility. For instructions on how to do this, see Section 6.4.1, "JDBC Drivers". For additional information, consult the technical note that describes the utility and is installed with it: `oracle_home``/bibeans/bin/bi_checkconfig.html`.

### 6.4.4 Connections

- Because of an OLAP bug, the `executeCommand` method of the `Connection` object might not work in BI Beans applications that connect to 64-bit Linux, Solaris, or HP-UX server instances. If you encounter this problem, then you can use the DBMS_AW PL/SQL package through a JDBC connection.

- Because of changes in J2SE 1.4, the `getCause` method of the `BIException` class and its subclasses was renamed to `getBIRootCause` in BI Beans release 9.0.3.

## 6.5 Administration Issues and Workarounds

There are no known administration issues.

## 6.6 Documentation Errata

There are no known documentation errors.