4
Configuring Destinations for Oracle9iAS Reports Services

Two things to consider when you run a report are how the report should be output (destination) and who should receive it (distribution). Distribution is discussed in Chapter 9, "Creating Advanced Distributions". This chapter explores how Oracle9iAS Reports Services handles output processing to default and custom destinations. It provides an overview of output processing and information on registering destination types with the Oracle9iAS Reports Server.

It includes the following sections:

• Overview of Output Processing

• Registering Destination Types with the Server

4.1 Overview of Output Processing

How the report should be output is controlled by the destypes you specify at runtime, which, in turn, are determined by the destination output types you have registered in your server configuration file (<server_name>.conf). You can register no output types and simply use the default types provided by Oracle9iAS Reports Services:

• Cache (i.e., browser)

• SMTP-compliant e-mail

• File

• Printer

• Oracle9iAS Portal (this is an exception in that, for access to the portal, it requires the specification of a userid and password in the server configuration file)

You can also define a custom output types, such as fax, FTP, Oracle's Internet File System (iFS), or any type you care to define through the Oracle9iAS Reports Services Destinations API. This API enables you to define new destination types and build handlers to usher your reports to custom destinations.

Note: Build a custom destination type via the Oracle9iAS Reports Services Destinations API. Look for upcoming information about Reports APIs and destination types for download on the Oracle Technology Network: http://otn.oracle.com.

Oracle9iAS Reports Services architecture standardizes the way output is generated and delivered. It takes responsibility for delivering report output to the appropriate destination (via the Reports Server), yet generates output independent of its destination (via the Reports Engine). This provides a significant improvement in efficiency by allowing one run of a report to be used in a number of different ways. It also opens up the output processing architecture to allow for any number of destination types.

In the past, the Reports runtime engine was totally responsible for delivering the output. Consequently, it had to know how to communicate with output destinations. This resulted in a tight coupling between the engine and the supported destinations.

Oracle9iAS Reports Services eliminates this tight coupling and its attendant restrictions. The runtime engine now treats all destinations alike. It doesn't need to know the destination type for which the output is being produced. The server hands output off to destination handlers that prepare the material for delivery to their associated destination types. You can use predefined destination types (with predefined handlers) or create a handler for a custom destination type you intend to support. Almost any type of destination can be plugged into Reports.

Figure 4-1 illustrates the main components of the Oracle9iAS Reports Services output processing architecture.

Figure 4-1 Main components of destination/distribution architecture

Text description of the illustration dest_01.gif

Requests flow through the output processing architecture in the following sequence:

1. The user submits a request from a client or browser to the Reports Server.

2. The server passes it along to the runtime engine.

3. The runtime engine creates/processes the destination objects (which include file lists for specific destinations as well as any properties related to those destinations) and the report output; the runtime engine sends the destination objects to the Reports Server and the report output to cache.

4. The Reports Server sends the destination objects to the Reports Server's destination component.

5. The destination component of the Reports Server fetches the report output from cache.

6. The Reports Server destination component sends the report and the destination objects (which specify how the destination device should handle the output) to the appropriate destination handler.

4.2 Registering Destination Types with the Server

Before the Oracle9iAS Reports Server can send a report to a particular destination type, the type must be a default type (printer, e-mail, cache, or file) or a type registered in the server's configuration file, <server_name>.conf. The configuration file contains a destination element for registering destination types that are valid for your reports. You can register anywhere from zero to any number of destination types.

Registering a destination type with the server involves:

• Setting Up a Destination Section in the Server Configuration File

• Entering Valid Values for a Destination

These tasks are described in the following sections.

4.2.1 Setting Up a Destination Section in the Server Configuration File

To set up a destination section in the <server_name>.conf file:

1. Open the server configuration file with your preferred text editor.

   You'll find the server configuration file in the following directory (Windows and UNIX use the same path):

   ORACLE_HOME\reports\conf\<server_name>.conf
   

2. If the configuration file does not have a destination section, create one underneath the element that precedes it in the configuration file's data type definition file (rwserverconf.dtd) section.

   Note: The server configuration file follows the order of elements defined in the file's related document type definition file (ORACLE_HOME\reports\dtd\rwserverconf.dtd). Place destination after the elements that precede it, whichever are present in your server configuration file.

3. Use the following syntax to register all the destination types you will use for outputting reports:

   <destination destype="output_type_1" class="java_class_1">
   

   <property name="valid_destype_property" value="valid_value"/>
   <property name="valid_destype_property" value="valid_value"/>
   

   </destination>
   <destination destype="output_type_2" class="java_class_2">
   

   <property name="valid_destype_property" value="valid_value"/>
   

   </destination>
   

The valid values for these tags are discussed in the following sections.

4.2.2 Entering Valid Values for a Destination

4.2.2.1 Destination destypes and classes

The destype and class attributes are required for valid registration of a non-default output type. They specify the destination types and their associated Java classes. The predefined (default) destination types and classes that come with Oracle9iAS Reports Services are listed in Table 4-1:

Table 4-1 Standard destination types and classes

Destination	destype	class
Oracle9iAS Portal content area	oraclePortal	oracle.reports.server.DesOraclePortal
SMTP-compliant e-mail	mail	oracle.reports.server.DesMail
file	file	oracle.reports.server.DesFile
cache	cache	oracle.reports.serverDesCache
printer	printer	oracle.reports.server.DesPrint

Contrary to the other default types, you must register an oraclePortal destype. This is because the oraclePortal destype requires the specification of a userid and password for accessing the portal.

You are not limited to the predefined destypes and classes provided with the server. You can register custom destination types, such as a fax or FTP, once you have defined a custom handler (through the Destinations API).

Note: Look for upcoming information about Reports APIs on the Oracle Technology Network: http://otn.oracle.com.

4.2.2.2 Destination Property name/value Pairs

The server configuration file allows the association of an unlimited number of properties with a registered destination. Destination properties consist of name/value pairs that define some aspect of an output type's configuration. They are expressed in terminology recognized by the destination type. For example, a destination with a destype of oraclePortal would recognize the name/value pair:

<property name="portalUserid" value="portal_id/portal_password@portal_schema"
confidential="yes" encrypted="no"/>

This example defines the values to be associated with a portal user ID. It includes the attributes confidential and encrypted: confidential="yes" indicates that the values within this element should be encrypted; encrypted="no" indicates that the values are not yet encrypted. The next time the Reports Server starts, it will automatically encrypt the values and reset encrypted to yes.

Note: Elements and attributes allowable in server configuration file are determined by the syntax defined in the rwserverconf.dtd file (ORACLE_HOME\reports\dtd\rwserverconf.dtd). This is discussed in detail in Chapter 3, "Configuring Oracle9iAS Reports Services".

What is valid for a destination type's properties depends entirely on the destination type. These values do not come from Reports and are not put to use by the Reports Server. They come from the destination type itself and use terms the destination recognizes. It is up to the developer to understand the requirements of a custom destination and to know what properties to associate with a given custom output type.

When we begin to discuss distribution, you may note that within the distribution XML file, the destype element also allows for the use of property name/value pairs. It's important to make a distinction between properties entered for a destination element in the server configuration file and those entered for a destype element in the distribution XML file:

• Properties entered for a destination element in the server configuration file should deal only with configuring an output type, for example setting an allowable number of retries for a destination fax.

• Properties entered for a destype element in the distribution XML file should deal only with specifying a runtime parameter, for example the identity of the fax's intended recipient.