1
Understanding the OracleAS Reports Services Architecture

When you're ready to publish your reports, all the Web server and application server tools you'll need are available in the Oracle Application Server. This chapter describes the architecture of relevant OracleAS Reports Services components in combination with its reports publishing component, OracleAS Reports Services. It also provides an overview of Reports Runtime processing and offers some things to consider when you set up your server environment.

This chapter includes the following sections:

• Overview of OracleAS Reports Services

• OracleAS Reports Services Components

• OracleAS Reports Services Runtime Process

• Things to Consider When You Set Up Your System

• Maintaining High Availability

1.1 Overview of OracleAS Reports Services

Oracle Application Server is a comprehensive and integrated application server that runs any Web site, portal, or Internet application. It enables you to make applications available from Web browsers, mobile devices, and command lines. 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, and CGI. It enables you to run reports on both local and remote application servers and to implement a multi-tiered architecture for running your reports.

When used in conjunction with servlet, JSP, or CGI (maintained only 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 increases 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 Reports Queue Manager (Windows), the Reports Queue Viewer (UNIX), the showjobs command (Web), and the OracleAS Reports Services pages in Oracle Enterprise Manager (OEM) 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 objects are persistent. This means that if the 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:

Note: The term tier refers to the logical location of the components that comprise the OracleAS Reports Services architecture. Each of the tiers, though, could reside on the same machine or different machines.

• 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.

If you choose to have your Web server on multiple machines, the Oracle HTTP Server provides a load balancing feature to allow sharing of the Web server load across multiple machines. If you choose to have your application server on multiple machines, OracleAS Reports Services provides peer-level clustering to allow sharing of the Reports Server load among multiple machines.

The difference between load balancing and peer clustering is that with load balancing, one machine manages the traffic across all machines; while with peer clustering, all machines are aware of the traffic on each machine, and each machine shares the task of monitoring and responding to requests. The advantage of peer-level clustering is the elimination of a single point of failure, further supporting the possibility of a fail-safe environment.

Note: Reports Server clustering is discussed in detail in Chapter 12, "Clustering Reports Servers".

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

Text description of the illustration arch_svccomp.gif

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, 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.

   • 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.

4. The Reports CGI, a component of the Web server that translates and delivers information between either a Web server or a J2EE Container (for example, OC4J) and the Reports Server, enabling you to run a report dynamically from your Web browser .

   Note: Reports CGI is maintained only for backward compatibility.

5. The Reports Server, 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.

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

7. 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.

8. 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 such destinations such as e-mail, OracleAS Portal, and WebDav.

1.3 OracleAS Reports Services Runtime Process

Here is how the various components of OracleAS Reports Services contribute to the process of running a report:

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 CGI, all associated with the Oracle HTTP Server. The JSP and rwservlet requests go to mod_oc4j. (For jobs run as JSPs, mod_oc4j uses OJSP to translate the JSP into a servlet.) The CGI 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 the Reports CGI (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 JSP or using rwservlet can by run by the in-process Reports Server or as a stand-alone Reports Server process, whichever is specified in the servlet configuration file, rwservlet.properties (ORACLE_HOME\reports\conf\). An in-process server requires less maintenance than a stand-alone server because, unlike the stand-alone server, it starts automatically in response to requests from the client. Additionally, an in-process server cuts down on the communication between processes, increasing the potential for faster performance.

   • Server requests using rwcgi go to the stand-alone server.

3. The Reports Server processes the request:

   If the request includes a TOLERANCE argument, 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 argument. 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 argument 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 Appendix A, "Command Line Options".

   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 the Reports Server processes the request:

   1. If configured, the Reports Server initiates an authentication and authorization check through mod_osso, part of the Oracle HTTP Server.

   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".

1.4 Things to Consider When You Set 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 set-up process.

The following subsections discuss some of the decisions involved in:

• Choosing the Types of Requests You Will Service

• Choosing Servlet, JSP, or CGI

• Choosing Single- Or Multiple-Machine Configurations

• Choosing Whether to Cluster Multiple Servers

1.4.1 Choosing the Types of Requests You Will Service

OracleAS Reports Services can be configured to accept both Web and non-Web job requests.

In the Web case, you can run reports by clicking or typing a URL in a Web browser. Depending on the URL, the report output is then served back to you in your browser or sent to a specified destination (for example, a printer). To enable users to launch reports from a browser, you will use either the Reports Servlet, a JSP, or Reports CGI components with your Web server. One or the other of these components must be present on the Web server to enable communications between it and the OracleAS Reports Services and to enable the processing of report requests from Web clients.

Note: For more information, refer to the Choosing Servlet, JSP, or CGI.

In the non-Web case, you can send job requests using the rwclient executable, installed on each of your user's machines.

From the perspective of configuration, these are the key differences between enabling Web and non-Web requests:

• Enabling Web requests requires that you choose between the Reports Servlet, a JSP, or Reports CGI (maintained only for backward compatibility) for the server side, but eliminates the need to install any client software beyond a standard Web browser.

• Enabling non-Web requests requires that you install client software on each machine that will be used to run requests. This introduces the need to administer client software on each client machine.

The Web case is clearly the most cost effective because it reduces client maintenance costs. But there might be cases where launching non-Web requests is a necessity. OracleAS Reports Services supports the implementation of both Web and non-Web requests in a single deployment environment.

1.4.2 Choosing Servlet, JSP, or CGI

To use OracleAS Reports Services in a Web environment, you must use a servlet, JSP, or CGI implementation. Our recommendation is that you choose servlet or JSP. The CGI implementation in OracleAS Reports Services is maintained only for backward compatibility.

Between servlet and JSP there are additional considerations. A JSP-only implementation means that you can publish a layout that is optimized for Web delivery. The servlet enables you to include paper layouts in your report publishing solution and fully leverage the distribution features of OracleAS Reports Services.

Using the servlet does not imply that you cannot also use JSP files because JSP files can contain both Web and paper layouts. When you run a report stored in a JSP, you specify the servlet in the URL and call the JSP with the command line argument: report=myreport.jsp.

For more information on running reports, see Chapter 13, "Running Report Requests".

1.4.3 Choosing Single- Or Multiple-Machine Configurations

You can place OracleAS Reports Services on the same machine as your Web server or on a different machine. Both scenarios have pros and cons.

For example, while it's true that having OracleAS Reports Services and the Web server on the same machine requires more of the machine's memory and disk space, it's also true that such an implementation reduces network traffic. This is because requests traveling between the Web server and the application server do not have to travel across a network, only incoming requests must do so.

If you are using the in-process server (available only with servlet implementations) you can further amplify the performance advantages of a single machine. The in-process server speeds up processing time by allowing for faster and more efficient communication between OracleAS Reports Services components. We recommend that you use the in-process server unless you will not use the Reports Servlet to deploy reports.

On the other hand, if you have a single machine configuration and that machine fails, everything fails.

While there is a greater amount of network traffic when the Web server and the application server are on different machines, you also benefit from the increase in system resources, in the form of additional CPUs, more disk space, and more available memory. Even in a multiple machine configuration, the in-process server will aid performance by speeding communication between OracleAS Reports Services components

Another possibility is placing your Web server and your application server each on multiple machines. This will require additional configuration, but it allows you to implement load balancing on the Web server.

If you will be deploying reports in multiple languages, you'll want to set up multiple Reports Servers--one or more for each language.

1.4.4 Choosing Whether to Cluster Multiple Servers

A cluster is a virtual grouping of servers into a community for the purpose of sharing request processing efficiently across members of the cluster. Unlike in previous versions, clustering in OracleAS Reports Services is peer-level, rather than master/slave. Peer-level clustering means that all members of the cluster take equal responsibility for sharing and processing incoming requests. Incoming requests are sent to the cluster as a whole rather than any one Reports Server in the cluster. Thus, if one member is shut down, the other members carry on managing the request load. There is no single-point-of-failure, where one machine's malfunction brings the whole system down.

Each cluster member machine must be configured in more or less the same way to allow a report to run on each server member in the same way. This means that configuration files should have most of the same settings: a distinction can be drawn between job-related settings and machine-related settings. Job-related settings must be the same from cluster member to cluster member. Job-related settings include settings related to security, data sources, and destination types. Machine-related settings include such attributes as maxEngine, minEngine, maxIdle, initEngine, and the like--these can be different from member to member.

Additionally, for cluster members:

• Server-related environment variables should be set to the same values.

• TNS settings should point to the same databases in the same way.

For servers to be members of the same cluster, they must share a cluster name (appended to each server's server name) and have the same public and private keys.

If your machines require different job-related configuration settings, you will not benefit from clustering.

If you must set your servers up for different languages, you'll want to set up multiple clusters: one or more for each language.

1.5 Maintaining High Availability

Oracle Application Server provides a number of high availability features to keep its middle tier running even when particular servers or components fail. To take advantage of these high availability features, OracleAS Reports Services takes the following actions when its infrastructure dependencies fail:

• Retrying the OracleAS Portal database connection. If the connection from the Reports Server to the OracleAS Portal database schema is dropped for some reason, then the Reports Server tries to re-establish the connection before generating an error. First, it retrieves the OracleAS Portal connection string from the repository. With the OracleAS Portal connection string, the Reports Server can attempt to reconnect. If reconnection is successful, you need not restart the Reports Server. OracleAS Reports Services also supports cold failover and RAC on the infrastructure and disaster recovery on the middle tier.

• Retrying the Oracle Internet Directory connection. If the Oracle Internet Directory connection becomes stale for some reason, the Reports Servlet and the Reports Server try to re-establish the connection before generating errors. If reconnection is successful, you need not restart the Reports Server.

  See Also: For more information about high availability: Oracle Application Server 10g High Availability Guide

---

¹ Only synchronous jobs and jobs that are currently running are lost in this case.