Oracle is a registered trademark and Oracle9i is a trademark or registered
trademark of Oracle Corporation. Other names may be trademarks of their respective
owners.
Oracle9i Business Intelligence Beans
Installation Guide
Version 9.0.3
December 2002
Contents
Before you install Oracle9i Business Intelligence Beans (hereinafter
referred to as "BI Beans"), please review the contents of this guide,
which contains the following sections:
System requirements for BI Beans are the same as those for Oracle9i
JDeveloper Version 9.0.3. For details, consult Installing
Oracle9i JDeveloper Version 9.0.3 (/products/jdev/htdocs/install_903.html).
The BI Beans release notes include a matrix
of supported configurations for both the design and runtime environments.
Before You Begin
Before you install BI Beans, you must determine which version of the Oracle9i
database you will use with your application. BI Beans is certified against both
Release 1 (9.0.1.3.x) and Release 2 (9.2.0.x.x) of
Oracle9i with the OLAP option. The installation script prompts you
for the database release to run against, and setup and configuration steps are
different depending on whether you choose to run against Release
1 or Release 2.
Important: You should follow these steps whether you are installing
for the first time or upgrading from a previous release.
Installing BI Beans from Oracle Technology Network
You can install and configure the database either before or after installing
JDeveloper and BI Beans. However, you must install JDeveloper before
you install BI Beans.
Special note for users who installed BI Beans release 9.0.3.3:
You do not need to reinstall JDeveloper. You can simply start the following
procedure with step 3 and continue as given until step 8. On the File Locations
page (step 8), instead of defining a new Oracle Home in the Destination
Name field, choose the Oracle Home where you installed release 9.0.3.3
from the drop-down list. The Destination Path will
be filled in automatically. Complete the rest of the procedure as given. The
installation program will automatically uninstall release 9.0.3.3 and install
9.0.3.4 (or later).
Follow these steps to install JDeveloper and BI Beans:
Download and install Oracle9i JDeveloper Version 9.0.3 into a
new directory, following the instructions in the Installing
Oracle9i JDeveloper Version 9.0.3 (/products/jdev/htdocs/install_903.html).
This file is also downloaded with the software.
Important: Do not extract JDeveloper into an existing
Oracle home directory. Doing so creates problems with both the JDeveloper
installation and with BI Beans. Also, do not overwrite a previous installation.
There are two types of JDeveloper installation: base and complete. The
base installation includes only the basic JDeveloper files. It does not
include the JDK or any documentation, which you must download and install
separately. On MS Windows, the complete installation contains everything
you need to run JDeveloper, including the complete JDeveloper Help system
and JDK 1.3. On UNIX platforms, the complete installation includes the JDeveloper
Help system, but not the JDK. Neither installation includes BI Beans or
its Help, which are downloaded and installed separately.
By default, JDeveloper expects the JDK to be in the ../../jdk
directory (on MS Windows) or in the /usr/java/jdk1.3 directory
(on UNIX). If your JDK is not in the default location, then you must edit
jdev/bin/jdev.conf to change the setting of the SetJavaHome
option. Note that BI Beans requires JDK 1.3.1x when running against
Oracle9i Release 1 (9.0.1.x).
Download the latest BI Beans release (9.0.3.4 or later) from Oracle
Technology Network (/software/products/bib/index.html).
On the machine where you installed JDeveloper, extract the downloaded file
into a temporary directory.
Start Oracle Universal Installer from the unzipped file structure as follows:
MS Windows -- Run setup.exe from install\win32.
Solaris -- Run runInstaller from install/solaris.
If you see an error message that says permission is denied, then you
must change the permission on runInstaller to executable.
HP-UX or LINUX -- Run runInstaller
from the current directory. If you see an error message that says permission
is denied, then you must change the permission on runInstaller
to executable.
On the Welcome page, click Next to continue.
On the Choose Oracle Database page, select the database release you want
to connect to, then choose Next. Later, when
you are working in JDeveloper, you can change this connection configuration,
as described in the Help topic "Switching Connections Between Release
9.0.1 and Release 9.2 of the Oracle9i Database."
Specifying the database release is required because Release 1 and Release
2 of the Oracle9i database use different versions of the JDBC and
OLAP API libraries, which are essential for performing OLAP queries. By
choosing a database release here, you are specifying which version of these
libraries will be loaded. This change affects the entire JDeveloper environment,
including the embedded OC4J instance. Uninstalling BI Beans does not automatically
restore the original libraries. You must do so manually, as described in
Uninstalling BI Beans.
On the File Locations page, supply values for the fields as follows:
Source path. This field is populated for you. Verify that
the value that is shown ends with stage/products.jar (for example,
on Windows, c:\temp\stage\products.jar).
Destination Name. Enter a new name in order to create
a new Oracle home directory. Do not choose an existing Oracle home directory.
Destination Path. Enter the path for the directory into
which you installed JDeveloper. Because JDeveloper does not use Oracle Universal
Installer, it is not installed into an Oracle Home. However, BI Beans must
be installed into an Oracle Home, which must be the JDeveloper installation
directory. To determine the correct path, search for the JDeveloper executable
(jdev.exe on Windows and jdev on UNIX), which
is in jdev/bin. The correct directory is two levels above the
directory that contains the JDeveloper executable.
For example, on UNIX, if you find the executable file in $HOME/jdev/jdev/bin,
then the installation directory is $HOME/jdev. In the Windows
example of the File Locations screen, shown below, the name of the new Oracle
home directory is ORACLE_JDEV_HOME. In this example, the JDeveloper executable
file is in c:\jdev_oc4j\jdev\bin, so the Destination Path is
c:\jdev_oc4j.
Click Next to continue.
On the Summary Page, click Install to start the installation.
After the installation completes successfully, click Exit.
Start JDeveloper by executing jdev.exe on Windows or jdev
on UNIX. (On UNIX, if you see an error message that says permission is denied,
then you must change the permission of jdev to executable.)
BI Beans is fully integrated into JDeveloper.
If you are upgrading from the previous version, migrate your JDeveloper
projects as described in the Help topic "Migrating Projects Between
Different Installations of JDeveloper 9.0.3," then follow the instructions
in the section Migrating BI Beans Projects from Version
9.0.2 to 9.0.3, in this document.
Complete the post-installation tasks that are appropriate for your installation,
as described in the following section.
Important: Before you can connect to data in JDeveloper,
the database must have been installed and configured, either by you or by
someone else. Preparation includes installing the appropriate patch sets
and, for Release 2, updating or creating new application settings in JDeveloper.
Note the following:
During design with JDeveloper, your analyses are saved in your project.
However, if you or your end-users want to be able to share analyses and
objects with other developers and end-users, then you must install
and configure the BI Beans Catalog.
To test your applications, you must install your chosen deployment environment.
For more information, see the section Supported
Deployment Environments. You can also search for deployment in the Help
system.
If you want applications to use JDK 1.4 instead
of JDK 1.3, which is the default, then follow the instructions in the JDeveloper
Help topic "Setting the Target J2SE for a Project." Bear in mind
the following database considerations:
Your application must use JDK 1.3.1x if it connects
to Oracle9i Release 1.
Your application can use either JDK 1.4 or 1.3.1 if it connects to Oracle9i
Release 2.
Note: Oracle Corporation recommends that you use JDK 1.3.1
for the design environment. JDeveloper is configured for JDK 1.3.1 by default.
If you use assistive technologies such as screen readers, then to work
with Java-based applications, the Windows-based computer where you have
installed BI Beans must have Sun's Java Access Bridge installed in all the
Java virtual machine locations on the computer. Also, Oracle Corporation
recommends that you use JDK 1.3.1, which is better supported by screen readers.
In your deployment environment, if a different ORB will already be instantiated
before BI Beans begins to load, then you must change the ORB settings. You
can use methods of the connection bean (preferred) or those of the ORBUtils
class. The ORB must be of type org.omg.CORBA.ORB, and the method
must be called before you call the connect() method on the
connection bean. The following examples show how to use each of these methods.
They assume that you created an ORB named _orb before you created
BI Beans. Refer to the API Reference (available from the JDeveloper Help
menu) for a more detailed description of the methods.
Using connection bean methods (preferred)
oracle.dss.connection.client.Connection conn = new oracle.dss.connection.client.Connection();
conn.setProperty(oracle.dss.connection.common.CB.ORB, _orb)
BI Beans Catalog: If you plan to use the Oracle JDBC Thick
(OCI) driver to connect to the BI Beans Catalog, then you must edit the
jdev.conf file, as described in the JDeveloper Help topic "Reference:
Connection Requirements for Oracle's Type 2 JDBC Drivers (OCI)." The
jdev.conf file is in the <oracle_home>/jdev/bin
directory, where <oracle_home> is the directory where
you installed BI Beans. If a project that uses the Oracle JDBC Thick (OCI)
driver will run against Oracle9i Release 2, then you must ensure
that the versions of the Release 2 client and the JDBC driver match. That
is, when you follow the instructions in the Help topic, you must reference
an Oracle Home that contains the Release 2 client files.
Furthermore, in the design environment, if you want to use a version of
Oracle9i client other than the one that is certified for Oracle9i
Developer Suite, then you must change the path for two JavaLibFile entries
in jdev.conf by substituting $ORACLE_HOME for
../../. The modified entries should read as follows:
$ORACLE_HOME/jdbc/lib/classes12.jar
$ORACLE_HOME/jdbc/lib/nls_charset12.jar
Note: This change affects only the design environment
itself. It does not affect either your projects or the embedded OC4J instance.
Preparing the Oracle9i Release 2 Database to Use with BI Beans
If you want to run against Oracle9i Release 2, complete the following
tasks:
If you have not already done so, install the Enterprise Edition of the Oracle9i
database, Release 2. For instructions, download the Oracle9i installation
guide for the appropriate platform from Oracle
Technology Network ().
Important: When you install the database client, do not
install it into the Oracle9i Application Server home.
On the same server machine, download and install the appropriate Oracle9i
patch sets from Oracle MetaLink
(http://metalink.oracle.com). To locate the patch sets to download,
log onto MetaLink and click Patches, then
search for the following patch set numbers:
2632931 -- The Oracle9i 9.2.0.2 patch set. Choose the appropriate
platform, then download and install the patch set.
2529822 -- Best Practices for Tabular Cube Aggregation and Query
Operations. When you configure the database, you must follow these
configuration settings to ensure good performance of BI Beans.
Define the appropriate OLAP metadata, as described in the Oracle9i
OLAP Release 2 - User's Guide. This book is available on Oracle
Technology Network (/products/bi/9iolap.html).
You can also refer to the Help system for the OLAP management tool of Oracle
Enterprise Manager, which is the tool that you use to create the metadata.
If you do not define appropriate metadata, then you will not be able to
create OLAP queries.
For any existing BI Designers, you must either update the application settings
to specify the new OLAP data source (as described in the Help topic "Updating
BI Beans Application Settings") or create a new BI Designer (as described
in the Help topic "Creating a BI Designer Object").
Tip: Scripts are also available that allow you to switch
back to an Oracle9i Release 1 connection. For details, see the
Help topic "Switching Connections Between Database Versions."
Preparing the Oracle9i Release 1 Database to Use with BI Beans
If you want to run against Oracle9i Release 1 (OLAP), then complete
the following tasks:
If you have not already done so, install the Enterprise Edition of Oracle9i
Release 1 (9.0.1.3.x), including the OLAP option. To install the
OLAP option, simply perform a Data Warehouse type installation. The OLAP option
is available only on Sun Solaris (SPARC) and MS Windows NT/2000. For instructions,
download the Oracle9i installation guide for the appropriate platform
from Oracle Technology Network (/docs/products/oracle9i/index.html).
Note: If you have an existing installation of Release
1 that you wish to continue to use, be sure to upgrade it to the 9.0.1.3.x
version and install the patches described below.
Log onto Oracle MetaLink (http://metalink.oracle.com)
and download and install the latest patch sets (the number varies by platform)
for the Oracle9i Release 1 (9.0.1.3.x) database onto the
same server machine.
Still on the same server machine, download and install the Oracle9i
Release 1 (9.0.1.2.1) OLAP patch sets. Note that the OLAP option is available
only on Sun Solaris (SPARC) and MS Windows NT/2000. To locate the correct
patch sets to download, log on to Oracle
MetaLink (http://metalink.oracle.com) and click Patches.
On the Patch Download screen, search for the following patch set numbers:
Platform
Patch Set Number
Title and Notes
Sun Solaris (SPARC)
2280021
9.0.1.2.1 PATCH SET FIXES FOR ORACLE OLAP 9.0.1.0.0
Install this patch set first.
MS Windows NT/2000
2386663
9.0.1.2.1 PATCH SET FIXES FOR ORACLE OLAP 9.0.1.0.0
Install this patch set first.
Both
2076986
MV PL/SQL PACKAGE FOR ORACLE OLAP 9.0.1.X.X
Install this patch set second. Although it is listed under Solaris,
you should install this patch set under Windows as well. The
readme file describes the optimal configuration settings for the database,
which you should follow exactly.
Define the appropriate OLAP metadata, as described in the Oracle9i
OLAP Services Concepts and Administration Guide, which is part of the
documentation set for Oracle9i. There are two versions, one for
Windows and one for other platforms. This book is available on the documentation
CD that ships with the RDBMS as well as on Oracle
Technology Network (/docs/products/oracle9i/index.html).
You can also refer to the Help system for the OLAP management tool of Oracle
Enterprise Manager, which is the tool that you use to create the metadata.
If you do not define appropriate metadata, then you will not be able to
create OLAP queries.
Important tips:
Only JDK 1.3.1x is certified with Oracle9i Release 1.
JDeveloper is configured for JDK 1.3.1_02 by default.
If an existing application runs against Oracle9i Release 1 and
you want to change it to run against Oracle9i Release 2, then you
must complete the installation process for Release 2 and
complete the migration steps.
Migrating BI Beans Projects from JDeveloper Version 9.0.2 to 9.0.3
To migrate existing projects to BI Beans version 9.0.3, perform the following
tasks in the order shown:
1. (Projects that connect to Oracle9i Release 1) Configure JDeveloper
to use the default Java ORB
Borland® Enterprise Server VisiBroker® Edition is no longer required
to connect to either release of Oracle9i. However, if you are connecting
to Oracle9i Release 1, then you must migrate your projects from the
VisiBroker ORB to the default Java ORB. To do so, remove all ORB-related VM
options by following these steps:
In the JDeveloper System Navigator, right-click the project node and choose
Project Settings from the drop-down list.
This procedure describes how to specify a project's runtime database
connection.
In the system Navigator, right-click the project node and choose Project
Settings from the drop-down list.
Under Development, click Libraries.
Reference the appropriate database library for the project:
OLAP API 901 -- to connect to Oracle9i Release 1
OLAP API 92 -- to connect to Oracle9i Release 2
3. (Servlets only) Upgrade applications that contain BI Beans servlets
Note: BI Beans no longer supports Apache JServe.
In an application that contains a BI Beans servlet, you must update the servlet
to reference the new stylesheet. To do so, override the getStyleSheetName
method in your BIController# class to return biaddins.xss,
the name of the new style sheet.
Base classes for the BI Servlet have moved. You can address this change by
creating a new project and generating a new servlet or, if you prefer, you can
restore the base classes to their location in 9.0.2. If you choose to do this,
then you will see a number of deprecation warnings, which you can ignore. To
restore the 9.0.2 base classes, follow these steps:
Copy biservlet_902.zip from the bibeans/lib directory
into the project source directory.
In the JDeveloper System Navigator, select the project that contains the
servlet.
From the File menu, open biservlet_902.zip, which adds it
to that project.
In the System Navigator, right-click the project node and choose Project
Settings from the drop-down list.
Under Common, select Input Paths.
Click Edit to edit the Java Source Path field.
In the Edit Java Source Path dialog box, click Add
Entry.
Browse to the project source directory and select biservlet_902.zip.
Click Select.
4. (HTML-client applications only) Upgrade the cabo directory
When you create an HTML project in JDeveloper, the cabo directory
is created under the public_html directory. It contains the uiXML
and BI Beans images, style sheet, and javascript files, which can change between
releases. To upgrade this directory, follow these steps:
Navigate to the public_html directory of the project to be
upgraded.
Rename the cabo directory to cabo.9.0.2.
In JDeveloper, create a new project in the same workspace.
Select the project and, from the File menu, choose New.
In the Business Intelligence category, select Servlet
application. (Even if you are not upgrading a servlet, you must choose
Servlet application to ensure that you are getting
the latest images.)
Complete the screens in the Servlet Wizard. After you specify a BI Designer,
you can simply accept the defaults. When the servlet is generated, it creates
a new cabo directory for the project.
Navigate to the public_html directory for this new project
and copy the new cabo directoy to the public_html
directory of the project you are upgrading.
(Optional) You can safely delete the new project that was created.
5. Upgrade the BI Beans Catalog
Important: If your existing Catalog runs against version 8.1.7
of the Oracle database, then you must upgrade the database to Oracle9i
before performing the following steps. Oracle8i (8.1.7) is no longer
supported.
Note: You can upgrade the BI Beans Catalog at any time, not
only at this point in the process.
Ensure that the environment variable JDEV_ORACLE_HOME is set to the Oracle
Home directory.
Ensure that the environment variable JAVA_HOME is set to the directory
where the JDK is installed.
Use the upgrade utility to upgrade the catalog. The utility is located in
the <ORACLE_HOME>/bibeans/bin/ directory. Its syntax is
as follows:
The following resources will help you learn about the beans and begin to develop
applications quickly.
Introducing Oracle9i Business Intelligence Beans
In the Help system, read the overview topic Introducing Oracle9i Business
Intelligence Beans, which is listed in the table of contents under
Getting Started.
Tutorials
Tutorials provide step-by-step
instructions for building both Java-client and HTML-client applications.
You can access the tutorials from the Help system or download them from
Oracle Technology
Network (/products/bib/index.html).
Samples
Samples provide code for
common application tasks. In addition to demonstrating how to code particular
features, the samples provide code that you can cut and paste directly into
your application. You must download the samples from Oracle Technology Network.
New samples are added regularly. By default, samples connect to Oracle9i
Release 2.
Help System
The Help system contains topics that provide high-level information and
that explain how to use methods together to accomplish tasks. In JDeveloper,
you can access Help topics about the user interface by pressing F1. You
can also use the Help menu to display the entire Help system.
API Reference
The API Reference (also called Javadoc) provides information at the detail
level for each class, interface, and method. To access the API Reference,
choose BI Beans API Reference from the Help
menu in JDeveloper. You can also access the API Reference separately from
JDeveloper. To do so, locate the doc directory under your JDeveloper
home directory, unzip bibeans-doc.zip, and open index.html
in your preferred browser.
Using Hosted Help
In JDeveloper, you can access Help topics and the API Reference that are
stored on your PC or you can enable hosted Help, in which Help
topics and the API Reference are stored on a server that is maintained by
Oracle Corporation. Whether you view local or hosted topics depends on the
setting of the Help option. The initial setting of this option differs depending
on how you install JDeveloper. The JDeveloper Help system and API Reference
are not always installed locally.
Base installation -- If you download the base installation
of JDeveloper, then the Help option is set to hosted
and the JDeveloper Help files and API Reference are not installed
on your machine. When you access a topic, it comes from the server.
BI Beans Help topics are installed on your machine, although when the
Help option is set to hosted, they also
come from the server. The BI Beans API Reference always comes from the
local file system. In order to run Help and the JDeveloper API Reference
locally, you must download the JDeveloper documentation and change the
setting of the Help option, as described in Installing
Oracle9i JDeveloper Version 9.0.3 (/products/jdev/htdocs/install_903.html).
Complete installation -- If you download the complete
installation of JDeveloper, then Help is set to local
and the JDeveloper Help system and API Reference are installed on your
local machine. When you access a topic, it comes from your local file
system.
Supported Deployment Environments
Applications built with BI Beans require the following:
Data server -- Oracle9i Enterprise Edition Release
1 (9.0.1.3.x) with the OLAP Option or Oracle9i Enterprise
Edition Release 2 (9.2.0.x.x). You must also download and
install the appropriate patches, which differ depending on whether you are running
against Release 1 or Release 2.
Metadata -- The database administrator must define appropriate
metadata in the Oracle database to support business intelligence applications.
For information about defining OLAP metadata for Oracle9i Release 1,
see the Oracle9i OLAP Services Concepts and Administration Guide; for
information about defining OLAP metadata for Oracle9i Release 2, see
the Oracle9i OLAP Release 2 - User's Guide. You can also refer to the
Help system for the OLAP management tool in Oracle Enterprise Manager, which
is the tool that you use to create the metadata. You can also use Oracle Warehouse
Builder to create appropriate metadata.
Browser -- In an HTML-client application, the user's browser
must support cookies.
Image generation with JDK 1.3 on UNIX platforms -- Image generation
for JSP and servlet applications that use JDK 1.3 requires that X server 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 machines that
lack frame buffer hardware. For more information about X Server and XVFB, see
Chapter 20 (Advanced Topics) of the UIX Developer's Guide in the JDeveloper
Help system.
You can download XVFB for Sun Solaris from Oracle
Technology Network (/products/ias/ias_utilities.html).
XVFB for other platforms must be downloaded from the platform vendor's web site.
Because JDK 1.4 supports "headless" mode, X Server is not required
for applications that use JDK 1.4. However, you must explicitly
enable headless mode, as follows:
In the JDeveloper System Navigator, right-click the project node and choose
Project Settings from the drop-down list.
Under Development, click Runner.
Add the following Java Option:
-Djava.awt.headless=true.
Deploying applications to Oracle9i Application Server
BI Beans uses different JAR files from those that ship with Oracle9i
Application Server. If you want to deploy an application built with BI Beans
on the same machine as Oracle9i Application Server, you must create
a separate instance of OC4J, as described in Setting up a Separate OC4J
Instance for a BI Beans Application, which is available on Oracle
Technology Network (/products/bib/index.html).
Deploying applications to BEA WebLogic Server
Oracle Corporation supports deployment of BI Beans applications to BEA WebLogic
Server version 7.0 on NT. For detailed instructions, see Deploying Applications
to BEA WebLogic Server, which is available on
Oracle Technology Network (/products/bib/index.html).
Applications that use the BI Beans Catalog require the following:
Database -- Oracle9i, either Release 1 (9.0.1.3.x) or
Release 2 (9.2.0.x.x)
Client-side driver --
Oracle JDBC Thick (OCI) driver. Recommended for better performance, especially
in a multi-user environment. This driver is installed with Oracle9i
and requires configuration. To configure the driver, you must install the
Oracle9i client on your local machine. You can download the Oracle9i
client from Oracle Technology Network
(), where it is available as a separate
download on the main Oracle9i download page.
or
Oracle JDBC Thin (Pure Java) driver. Installed with JDeveloper9i;
recommended for use with JDeveloper.
Uninstalling BI Beans
Only products that were installed with Oracle Universal Installer can be uninstalled
with it. You can use Oracle Universal Installer to uninstall BI Beans, but you
must uninstall JDeveloper by hand.
If you chose Oracle9i Release 2 as your default database connection
when you installed BI Beans, then uninstalling BI Beans will not restore the
Release 1 libraries. If you want to restore these libraries and return JDeveloper
to its original configuration, then follow these steps:
Navigate to the jdbc directory.
Delete the /lib subdirectory under jdbc.
Still under the jdbc directory, rename the /lib_original
subdirectory to /lib.
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 (http://www.oracle.com/accessibility/).
Bookmark
