1 Understanding the OracleAS Reports Services Architecture

1.1 Overview of OracleAS Reports Services

OracleAS Reports Services is the reports publishing component of Oracle Application Server. It is an enterprise reporting service for producing high quality production reports that dynamically retrieve, format, and distribute any data, in any format, anywhere. You can use OracleAS Reports Services to publish in both Web-based and non-Web-based environments.

OracleAS Reports Services provides a scalable, flexible architecture for the distribution and automated management of report generation engines on the same server and across multiple servers. Additionally, it caches report output for reuse on similar requests. It integrates into standard Web environments with JSPs, Java servlets, Web Services, and CGI (maintained for backward compatibility). It enables you to run reports on both local and remote application servers and to implement a multitiered architecture for running your reports.

When used in conjunction with JSPs, Java servlets, Web Services, or CGI (maintained for backward compatibility), OracleAS Reports Services enables you to run reports on any platform from a Web browser using a standard URL syntax. For servlet implementations, the in-process server is available for faster response and easier administration. The in-process server cuts down on the communication expense between processes and consequently shortens response times.

OracleAS Reports Services handles client requests to run reports by entering all requests into a job queue. When one of the server's engines becomes available, the next job in the queue is dispatched to run. As the number of jobs in the queue increases, the server can start more engines until it reaches the maximum limit specified in your server configuration. Similarly, engines are shut down automatically after having been idle for a period of time that you specify (see Chapter 3, "Configuring OracleAS Reports Services").

OracleAS Reports Services keeps track of all jobs submitted to the server, including jobs that are running, scheduled to run, finished, or failed. The showjobs command (Web through rwservlet), the Web Services interface, the OracleAS Reports Services pages in Oracle Enterprise Manager 10g, the Reports Queue Manager (Windows), and the Reports Queue Viewer (UNIX) enable you to view information on when jobs are scheduled, queued, started, finished, and failed, as well as the job output and the final status of the report.

With OracleAS Reports Services, job information is persistent. This means that if the Reports Server is shut down then restarted, all jobs are recovered,^Foot 1  not just scheduled jobs.

When used in a Web environment, the OracleAS Reports Services architecture consists of four tiers:

• The client tier (a Web browser)

• The Web server tier

• The OracleAS Reports Services tier

• The data tier, including databases and all other data sources

When used in a non-Web environment, there are three tiers (a Web server being unnecessary):

• The client tier (a small, proprietary application on each client machine)

• OracleAS Reports Services tier

• The data tier, including databases and pluggable data sources

The way you set up these tiers can range from having all of them on one machine to having each of them on a separate machine. Additionally, you can have multiple Web servers on multiple machines as well as multiple application servers on multiple machines. Refer to the Oracle Application Server Installation Guide for more information on sample topologies.

If you choose to have your Web server on multiple machines, you can cluster and load balance multiple Oracle Application Server instances for a highly available, fail-safe environment. Refer to the Oracle Application Server Installation Guide for information on load balancing. Refer to the Oracle Application Server Enterprise Deployment Guide and Oracle Application Server High Availability Guide for information on enterprise deployment architectures and high availability.

OracleAS Reports Services provides event-based reporting. This uses database events to trigger the generation of a report. For example, you can define an event that signals a change in revenue levels above or below a particular watermark. If the change occurs in the database (the event), a report is automatically generated. This feature is discussed in detail in Chapter 17, "Using Event-Driven Publishing".

OracleAS Reports Services includes a distribution module that uses XML to define unique configurations for the distribution of reports. Call the desired XML file from the runtime command line or URL to generate one report, and let the server handle diverse outputs and destinations. Processing time is significantly reduced and configuration changes can all be handled within the XML file. This feature is discussed in detail in Chapter 15, "Creating Advanced Distributions".

1.2 OracleAS Reports Services Components

Figure 1-1 OracleAS Reports Services Components

Description of "Figure 1-1 OracleAS Reports Services Components"

Figure 1-1 illustrates the components of a working OracleAS Reports Services environment. This includes:

1. The Oracle HTTP Server, a Web server provided by Oracle Application Server. It incorporates an OpenSSL module to provide support for Secure Sockets Layer (SSL) and HTTP Secure Sockets Layer (HTTPS). It also provides a servlet engine to support the running of Java Servlet applications.

2. The module mod_oc4j, used by the Oracle HTTP Server to redirect requests from servlets and JSPs to Oracle Application Server Containers for J2EE (OC4J). OC4J provides a complete J2EE environment that includes a JSP translator, a JSP servlet engine (OJSP), and an Enterprise JavaBeans (EJB) container. It provides a fast, lightweight, highly scalable, easy-to-use, complete J2EE environment. It is written entirely in Java and executes on the standard Java Development Kit (JDK) Virtual Machine (JVM).

3. The Reports Servlet (rwservlet), a component of OracleAS Reports Services that runs inside the Web server's servlet engine. The Reports Servlet translates and delivers information between HTTP and Reports Server. It includes:

   • The In-process Server, which reduces the maintenance and administration of the Reports Server by providing a means for starting the server automatically, whenever it receives the first request from the client through the Reports Servlet (rwservlet) or a Reports JSP.

4. The Custom Tag Handler, which processes custom Oracle Reports tags included in a JSP file. In a JSP file, Oracle Reports-related custom tags are identified by the prefix rw:; other custom tags using other prefixes may also be present.

5. The Reports CGI (rwcgi), a component of the Web server that translates and delivers information between either a Web server and the Reports Server, enabling you to run a report dynamically from your Web browser.

   
   

   Note: With Oracle Reports 10g, the Reports CGI (rwcgi) is deprecated (maintained only for backward compatibility); instead, use Reports JSPs, rwservlet (Reports Servlet), or Reports Web Services. rwservlet is strongly recommended over rwcgi for performance reasons. For each request, rwcgi starts a new process, initializing a JVM and resulting in slow performance when running a large number of report requests. On the other hand, rwservlet is deployed on an OC4J instance and leverages servlet functionality, thereby providing better performance over rwcgi.

   
   

6. The Reports Server (rwserver), which processes client requests, including ushering them through its various services, such as authentication and authorization checking, scheduling, caching, and distribution (including distribution to custom—or pluggable—output destinations). The Reports Server also spawns runtime engines for generating requested reports, fetches completed reports from the Reports Server cache, and notifies the client that the job is ready.

7. The Reports Server Cache, which securely stores completed job outputs.

8. The Reports Engine, which includes components for running SQL-based and pluggable data source-based reports. It fetches requested data from the data source, formats the report, sends the output to cache, and notifies the Reports Server that the job is complete.

9. The pluggable engines, which are custom engines that use Java APIs to pass jobs to the Reports Server, as well as leverage the server's other features, such as scheduling, distribution, notification, and caching. OracleAS Reports Services provides an out-of-the-box pluggable engine called the URL engine. The URL engine enables you to distribute content from any publicly available URL to destinations such as e-mail, OracleAS Portal, and WebDAV.

Additionally, the Oracle Reports bridge provides functionality for discovering a Reports Server across subnets. The Oracle Reports bridge acts as a gateway for packets that are broadcast by Reports Server/Reports Client across subnets. The bridge mechanism is not shown in Figure 1-1; for more information, see Section 1.4.1.2, "Server Discovery Across Subnets".

1.3 OracleAS Reports Services Runtime Process

The various components of OracleAS Reports Services contribute to the process of running a report as follows:

1. The client requests a report by contacting a server through either a URL (Web) or a non-Web, Oracle Reports-related command, such as rwclient.

   • The URL goes to JSP, rwservlet, or rwcgi, all associated with the Oracle HTTP Server. The JSP and rwservlet requests go to mod_oc4j. (For jobs that run as JSPs, mod_oc4j uses OJSP to translate the JSP into a servlet.) The rwcgi requests go to a CGI component.

     The URL may contain runtime parameters or a keyword that refers to a runtime parameter configuration section within cgicmd.dat, or it may contain both, though parameters explicitly named in the URL must not also be present in the relevant keyword section of cgicmd.dat.

   • rwclient goes directly to the Reports Server.

     The command line may contain runtime parameters. If you have a lot of runtime parameters, you can create a batch file or shell script that contains the rwclient command along with a string of parameters.

2. The rwservlet (or rwcgi, maintained only for backward compatibility) component translates and delivers information between either a Web server or a J2EE Container (for example, OC4J) and the Reports Server:

   • Server requests from Reports JSP or rwservlet can be run by the in-process server or as a standalone Reports Server process (recommended), whichever is specified in the servlet configuration file (ORACLE_HOME\reports\conf\rwservlet.properties). An in-process server requires less maintenance than a standalone Reports Server because, unlike the standalone Reports Server, it starts automatically in response to requests from the client. An in-process server cuts down on the communication between processes. A standalone server, on other hand, provides better control outside the rwservlet process with the ability to separate out server process from the OC4J instance. For information about specifying an in-process server and default naming, see Section 3.4.10, "Specifying an In-process Server" and Section 3.4.11, "Identifying the In-process Server".

   • Server requests using rwcgi go to the standalone server.

3. The Reports Server processes the request:

   If the request includes a TOLERANCE option, then the Reports Server checks its cache to determine whether it already has output that satisfies the request. If it finds acceptable output in its cache, then it immediately returns that output rather than rerunning the report.

   
   

   Note: For any job request that you send to the Reports Server, you can include a TOLERANCE option. TOLERANCE defines the oldest output that the requester would consider acceptable. For example, if the requester specified five minutes as the TOLERANCE, the Reports Server would check its cache for the last duplicate report output that had been generated within the last five minutes. An EXPIRATION option defines the point in time when the report output should be deleted from the cache (for example, EXPIRATION might equal a specific date and time for when the output should expire). For more information, see Section A.3.113, "TOLERANCE" and Section A.3.35, "EXPIRATION".

   
   

   If the request is the same as a currently running job, then the request will reuse the output from the current job rather than rerunning the report.

   If neither of these conditions is met, then:

   1. If Reports Servlet is SSO-enabled, it checks for authentication. A secure Reports Server then authorizes the user using Oracle Internet Directory. If Reports Servlet is not SSO-enabled, a secure Reports Server authorizes and authenticates the user.

   2. If the report is scheduled, the Reports Server stores the request in the scheduled job queue, and the report is run according to schedule. If the report is not scheduled, it is queued in the current job queue for execution when a Reports Engine becomes available.

      
      

      Note: When you configure the Reports Server (in server_name.conf), you can specify the maximum number of the Report Engines it can use. If the Reports Server is under this maximum, then it can send the job to an idle engine or start a new engine to handle the request. Otherwise, the request must wait until one of the current Oracle Reports Engines completes its current job.

      
      

   3. At runtime, the Reports Server spawns a Reports Engine and sends the request to that engine to be run.

4. The Reports Engine retrieves and formats the data.

5. The Reports Engine populates the Reports Server cache.

6. The Reports Engine notifies the Reports Server that the report is ready.

7. The Reports Server accesses the cache and sends the report to output according to the runtime parameters specified in either the URL, the command line, or the keyword section in the cgicmd.dat file (URL requests only).

Another way to create a report is through event-driven publishing. With event-driven publishing, the client is the database (rather than the end user). Events are defined through the Event-Driven Publishing API. The event invokes a database trigger, an advanced queuing application, or a PL/SQL package that calls the Event-Driven Publishing API to submit jobs to the Reports Server. Event-driven publishing is discussed in detail in Chapter 17, "Using Event-Driven Publishing".

For information about running reports from Oracle Workflow, refer to Section 3.8, "Configuring Oracle Reports to Communicate with Oracle Workflow", which points to the Integrating Oracle Workflow with Oracle Reports white paper on OTN (http://www.oracle.com/technology/products/reports/features/workflow) for complete information.

1.4 OracleAS Reports Services Communication Architecture

Oracle9i Reports and Oracle Reports 10g Release 1 (9.0.4) use Borland VisiBroker's osagent executable to dynamically discover Reports Servers in the network.

Oracle Reports 10g Release 2 (10.1.2) replaces the use of Borland's VisiBroker with Sun Microsystems' industry-standard Java Developer's Kit Object Request Broker (JDK ORB), providing support for Reports Server requests from clients across subnets, and using the broadcast mechanism for dynamic Reports Server discovery both within a subnet and across subnets.With Oracle Reports 10g Release 2 (10.1.2), you can use the built-in broadcast mechanism, available out-of-the-box, for dynamic discovery of Reports Servers. You can also choose to use the Common Object Service (COS) naming service orbd, provided by Sun Microsystem's JDK ORB, for Reports Server discovery.

This section discusses the two methods of Reports Server discovery:

• Server Discovery Using the Broadcast Mechanism

• Server Discovery Using the COS Naming Service

1.4.1 Server Discovery Using the Broadcast Mechanism

With the broadcast mechanism, Reports Server discovery can occur within a subnet or across subnets:

• Server Discovery Within a Subnet

• Server Discovery Across Subnets

Note: The Oracle Reports built-in broadcast mechanism requires the host machine to be inside a network. Thus, following are two scenarios in which the broadcast mechanism may not work, including the solutions for each scenario: If the host machine is not in a network (that is, it is a standalone machine). Solution for Windows platform: Install the MS loopback adapter, as described on the Miscrosoft Web site (http://microsoft.support.com). Then, specify an IP address for your machine (either XP or Windows 2000), as follows: On your desktop, right-click My Network Places, and choose Properties. Right-click the MS loopback adapter, and choose Properties. In the Properties dialog box, select Internet Protocol (TCP/IP), and click Properties. Select Use the following IP address, and enter a valid IP address. The subnet mask field will automatically populate. Do not use the local host IP (that is, 127.0.0.1). For example, enter: 198.162.1.1. Click OK, and follow the instructions displayed. Solution for UNIX platform: Configure the discovery mechanism to disable the built-in broadcast mechanism and enable the COS naming service instead, by replacing the multicast element with the namingService element in the network configuration file (rwnetwork.conf), as described in Section 3.3.1.3, "namingService". If the host machine is connected to a network through VPN. Solution for both Windows and UNIX platform: Configure the discovery mechanism to disable the built-in broadcast mechanism and enable the COS naming service instead, by replacing the multicast element with the namingService element in the network configuration file (rwnetwork.conf), as described in Section 3.3.1.3, "namingService".

1.4.1.1 Server Discovery Within a Subnet

Within a subnet, the client broadcasts a packet with the name of the Reports Server to which it wants to connect. A Reports Server with that name will respond if it exists in the network. The client then connects to the Reports Server to run the report request.

Figure 1-2 Server Discovery within a Subnet

Description of "Figure 1-2 Server Discovery within a Subnet"

Using the example of running a report request with server=rep_server, the following numbered steps map to the numbers in Figure 1-2:

1. getServerRef

   • The Oracle Reports client (for example, rwclient, rwservlet, or rwrqm) broadcasts a packet containing the name of the server to which it wants to connect. In this case, the packet contains the name rep_server.

   • The server with name rep_server in the network responds back with its Interoperable Object Reference (IOR).

   • The client converts the IOR to an object reference.

2. runReport

   • The Oracle Reports client sends a request to the remote object reference to run the report (IIOP call).

3. executeReport

   • Reports Server executes the report and returns either report or status.

1.4.1.2 Server Discovery Across Subnets

Oracle Reports provides the bridge mechanism for connecting two or more non-secured subnets. An Oracle Reports bridge running in one subnet will contact the Oracle Reports bridge running in another subnet to obtain Reports Server references. For configuration details, refer to Section 3.3.2, "Bridge Configuration Elements (bridgeconf.dtd)".

For troubleshooting scenarios and diagnosis, see Section D.8, "Diagnosing Oracle Reports Bridge Problems".

Figure 1-3 Server Discovery Across Subnets

Description of "Figure 1-3 Server Discovery Across Subnets"

Using the example of running a report request with server=rep_server, the following numbered steps map to the numbers in Figure 1-3:

1. getServerRef

   • The Oracle Reports client (for example, rwclient, rwservlet, or rwrqm) broadcasts a packet containing the name of the server to which it wants to connect. In this case, the packet contains the name rep_server.

2. bridge1 intercepts the packet and passes it to bridge2.

3. registerServerRef

   • bridge2 broadcasts the packet in dom2, and rep_server in dom2 responds back with the Interoperable Object Reference (IOR).

   • bridge2 passes the IOR back to bridge1, and bridge1 passes it to the client using the broadcast mechanism.

   • The Oracle Reports client converts the IOR to an object reference.

4. runReport

   • The Oracle Reports client sends a request to the remote object reference to run the report (IIOP call).

5. executeReport

   • Reports Server executes the report and returns either report or status.

Note: Numbers in blue color in Figure 1-3 are shown for the case where the Oracle Reports client is in dom2 and Reports Server is in dom1.

1.4.2 Server Discovery Using the COS Naming Service

Alternatively, you can use the JDK-provided Common Object Service (COS) naming service to access a Reports Server in the same subnet, as well as across a non-secured subnet. To configure the naming service, refer to Section 3.3.1, "Network Configuration Elements (rwnetworkconf.dtd)".

Note: It is recommended that you use the built-in broadcast mechanism for dynamic discovery of Reports Servers. Use the Common Object Service (COS) naming service for Reports Server discovery only when the built-in broadcast mechanism is not suitable for your environment, as in the following scenarios: You plan to install OracleAS Reports Services on a machine that is connected to a network using VPN. You want to avoid broadcast traffic on your network.

To control the COS naming service through OPMN, refer to Section 3.7.1.5, "COS Naming Service Specification".

Figure 1-4 Server Discovery Using the COS Naming Service

Description of "Figure 1-4 Server Discovery Using the COS Naming Service"

Using the example of running a report request with server=rep_server, the following numbered steps map to the numbers in Figure 1-4:

1. registerServer

   • When rep_server is started, it registers itself with the naming service, which must be up and running for the server to start. Now a request is run with server=rep_server.

2. getServerRef

   • The Oracle Reports client contacts the naming service and requests a reference to server rep_server.

   • The naming service returns the reference to server rep_server.

3. runReport

   • The Oracle Reports client sends a request to the remote object reference to run the report (IIOP call).

4. executeReport

   • Reports Server executes the report and returns either report or status.

Note: Numbers in blue color in Figure 1-4 are shown for the case where the Oracle Reports client is in dom2 and Reports Server is in dom1.

1.5 Setting Up Your System

The way you set up OracleAS Reports Services can vary widely depending upon the requirements of your system. Before you set up OracleAS Reports Services, you must make some decisions based upon your requirements. By making these decisions beforehand, you can greatly simplify the setup process.

The following subsections discuss some of the decisions involved in:

• Choosing the Types of Requests You Will Service

• Choosing Reports Servlet, JSP, Web Services, or CGI

• Choosing Single or Multiple-Machine Configurations

• Choosing a High Availability Environment