Installation requirements

The following requirements have to be met, in order to use the software:

  • Oracle Database Release: The minimum requirement is the availability of the package UTL_HTTP. Thus the integration will work with all Oracle versions, in which Oracle APEX can be installed. Thus, the integration will work with Oracle XE (10g), too.
  • Oracle APEX Release: There is no dependency on a specific APEX release, it should work with all of them.
  • J2EE server: The integration has been tested with Apache Tomcat 5.5.20, 6.0.20 and 7.0.8. Should work with other J2EE containers, but the configuration of the data sources will be different.
  • JasperReports: The current J2EE application supports the JasperReports engine 4.6.0. Reports created with a higher version will not work.But you can upgrade the JasperReports engine separately later using the instructions in the FAQ.

When upgrading from a previous version (of the JasperReportsIntegration)

Upgrade the J2EE application using the following steps: 

  1. Make a backup from the following files:
    • [Tomcat directory]\conf\Catalina\localhost\JasperReportsIntegration.xml
    • Backup the deployed files from  [Tomcat directory]\webapps\JasperReportsIntegration\reports
    • Backup the configuration file  [Tomcat directory]\webapps\JasperReportsIntegration\WEB-INF\classes\jasperreports.properties if modified.
  2. Copy the new file webapp\JasperReportsIntegration.war into the directory [Tomcat directory]\webapps.
  3. Restore the files from step 1 to their original locations.

Installation instructions

The database objects required for the integration will be installed into each application schema that you want to use with the integration. Currently, there are no scripts supplied to install the integration into a central Oracle schema. It should work to have a single installation per instance using synonms and grants to all application schemas that want to use the integration.

The installation instructions will refer to the application schema (in which you install the software) as [application schema]. The password for the application schema will be referred to as [application schema password].

Thus when I use an instruction like sqlplus [application schema]/[application schema password]@[database] please replace that with the actual values of your local installation. For example, if you want to install the integration kit into the schema HR with the password hr1 into your local XE instance (having a TNS entry named xe) then this instruction translates to:

sqlplus hr/hr1@xe


Database installation (SYS)

First of all we need to grant the required privileges to the Oracle user who will own the packages for the integration.

  1. Extract the downloaded zip file.
  2. Open a command shell:
    • e.g. on Windows: Start > Execute : cmd
  3. Go to the subdirectory sql (of where you extracted the file):
    • cd sql
  4. Connect as SYS to the local instance (using sqlplus)
    • sqlplus "sys/[sys password]@[database] as sysdba"
  5. Run the installation script (and pass the name of the target application schema as a parameter)
    • @sys_install.sql [application schema]
  6. [optional] If you are installing on an Oracle Release 11.0 and higher, you have to grant the required network privileges to the application schema. 
    • The  script sys_install_acl.sql allows access to the local machine on port 80 to port 10000. Please adapt the script to suit your needs, especially if the J2EE server is running on a different machine.
    • @sys_install_acl.sql [application schema]

Database installation (Application Schema)

  1. Open a command shell:
    • e.g. on Windows: Start > Execute : cmd
  2. Go to the subdirectory sql (of where you extracted the file):
    • cd sql
  3. Connect as the application schema to the local instance (using sqlplus)
    • sqlplus [application schema]/[application schema password]@[database]
  4. Run the installation script
    • @user_install.sql

Tomcat Installation

  1. Download the Apache Tomcat from here: http://tomcat.apache.org/
  2. Install Apache Tomcat by following the installation instructions for your operating system. I assume the Tomcat URL is http://[server]:[port], according to a default installation on your local box this will be http://127.0.0.1:8080.
  3. Once the basic Apache Tomcat installation works, stop the Apache Tomcat server.
  4. Install the oracle JDBC driver, so that the Tomcat can use its internal connection pooling with Oracle
    • Copy the files lib\ojdbc6.jar and lib\orai18n.jar into one of the following directories (only if required! If you are also running the APEX Listener on this tomcat instance then you already find the odjbc6.jar in this directory):
      • Tomcat 6.x: [Tomcat directory]\lib
      • Tomcat 5.5.x: [Tomcat directory]\common\lib
  5. Copy the file webapp\JasperReportsIntegration.war into the directory [Tomcat directory]\webapps.
  6. Start the Apache Tomcat server
    • During startup, Tomcat will detect the new application and deploy the file automatically into the directoy [Tomcat directory]\webapps\JasperReportsIntegration.
  7. Configure the JNDI datasources:
    Here we configure all data sources that can be used with all applications using the integration. These have to be registered within Tomcat. These JNDI (Java Naming and Directory Interface) data sources are internally managed by Apache Tomcat and are optimized for performance. Edit the file [Tomcat directory]\conf\Catalina\localhost\JasperReportsIntegration.xml. After the automatic deployment of the WAR file, this configuration file is created automatically.
    • <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE web-app PUBLIC
      "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
      "http://java.sun.com/dtd/web-app_2_3.dtd" >

      <Context path="/JasperReportsIntegration" debug="5" reloadable="true"
      crossContext="true">

      <Resource name="jdbc/default" auth="Container" type="javax.sql.DataSource"
      driverClassName="oracle.jdbc.OracleDriver"
      maxActive="20" maxIdle="10" maxWait="-1"
      initialSize="4" minIdle="3" validationQuery="select user from dual"
      testWhileIdle="true" testOnBorrow="true" timeBetweenEvictionRunsMillis="300000"
      numTestsPerEvictionRun="100" minEvictableIdleTimeMillis="10000"

      url="jdbc:oracle:thin:@localhost:1521:XE"
      username="apex_test"
      password="apex_test"
      />

      <Resource name="jdbc/test" auth="Container" type="javax.sql.DataSource"
      driverClassName="oracle.jdbc.OracleDriver"
      maxActive="20" maxIdle="10" maxWait="-1"
      initialSize="4" minIdle="3" validationQuery="select user from dual"
      testWhileIdle="true" testOnBorrow="true" timeBetweenEvictionRunsMillis="300000"
      numTestsPerEvictionRun="100" minEvictableIdleTimeMillis="10000"

      url="jdbc:oracle:thin:@localhost:1521:XE"
      username="apex_test"
      password="apex_test"
      />
      </Context>

    • For each data source you can give it a name (<Resource name="...") and set the connection parameters for your target Oracle database and user. The url is a typical JDBC url: jdbc:oracle:thin:@[server]:[port]:[SID].
    • TEST: http://[server]:[port]/JasperReportsIntegration , now you should see the basic start page for the integration
    • TEST: http://[server]:[port]/JasperReportsIntegration/test?_dataSource=default, now you should see the list of all user objects from the Oracle schema defined in the data source default.

Installation of the test application

The test application will allow for basic testing of the integration with all relevant parts. Install the application file apex\f860_JasperIntegrationTest_x.x.x.x.sql into your workspace.