Skip Headers

Oracle® Application Server Reports Services Publishing Reports to the Web 10g Release 2 (10.1.2) B14048-02 |
| Library | Product | Contents | Index

Previous | Next |

# 14 Using the Oracle Reports Web Service

A Web service is an application that is built on standard Internet and XML technologies and has the following characteristics :

- Includes public interfaces and bindings defined and described using XML.

- Publishes these public interfaces and bindings across the network for use by other programs.

A Web service accepts a request, performs its function based on the request, and returns a response. The request and the response can be part of the same operation, or they can occur separately, in which case the consumer does not need to wait for a response. Both the request and the response usually take the form of XML, a portable data-interchange format, and are delivered over a wire protocol, such as HTTP.

Web service transactions are usually conducted between businesses. A business that is a provider of one service can also be a consumer of another service. A Web service consumer can also be a client device, such as a thin client connecting to the Web service provider over a lightweight protocol.

This chapter discusses the Oracle Reports Web service and contains the following sections:

- Overview

- Getting Started

- Oracle Reports Web Service Operations

- Installing and Using the Sample Proxy and Java Client

## 14.1 Overview

Oracle Reports provides several ways of submitting a job request to the server-infrastructure for processing:

- `rwservlet`

  `rwservlet` translates and delivers a job request between HTTP and the Reports Server, such as when submitting from a Web browser or through the event-driven publishing API.

- `rwcgi`

  `rwcgi` translates and delivers a job request between HTTP and the Reports Server, such as when submitting from a Web browser or through the event-driven publishing API. `rwcgi` is maintained only for backward compatibility.

- `rwclient`

  `rwclient` parses and transfers a command line to run a a report on a remote Reports Server.

- Oracle Forms

  Oracle Forms is a rapid application development (RAD) tool, used to build highly scalable Internet database applications.

Integrating the Oracle Reports technology into custom applications, especially Java applications, requires the implementation of the mechanisms used by `rwservlet`, `rwcgi`, `rwclient`, and Oracle Forms to submit jobs to the server from within those applications.

The `RWWebService` servlet provides the necessary public interfaces and bindings, and is required to be exposed and to function as a Web service. This functionality enables any application developer to include Oracle Reports in their application.

## 14.2 Getting Started

This section outlines the steps necessary for:

- Invoking the RWWebService Servlet

- Viewing the WSDL

### 14.2.1 Invoking the RWWebService Servlet

To invoke the `RWWebService` servlet:

1. Start an Oracle Application Server Containers for J2EE (OC4J) instance where the Oracle Reports instance resides.

2. Enter the following URL in the address field of your browser:`http://``yourwebserver:port``/reports/rwwebservice`

   This takes you to the `RWWebService` endpoint. The `RWWebService` endpoint page enables you to do the following:

   1. View the Oracle Reports Web service WSDL.

   2. Run any `RWWebService` command using a Web based UI.

   3. Download the proxy JAR files and proxy sources to invoke the Oracle Reports Web service using the sample Java client.

### 14.2.2 Viewing the WSDL

The Web Service Description Language (WSDL) is an XML format for describing available services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint.

Note: Oracle Reports Web service does not support dynamic discovery of the WSDL by publishing to the universal description, discovery, and integration (UDDI) server.

1. Click the Service Description link on the `RWWebService` Web page to view the Oracle Reports Web service's WSDL document.

   Note: Use Internet Explorer to view the WSDL XML output. When you use Netscape (7.2 and above) you must save the page as a `.xml` file and use Internet Explorer to open the file, for example, `rwwebservice.xml`.

2. The last entry in the WSDL is the service description and contains the location of the WebService:

        <soap:address location="http://yourwebserver:8888/reports/rwwebservice" />

Figure 14-1 Viewing the WSDL

Description of "Figure 14-1 Viewing the WSDL"

Ensure that the URL and port number defined, `http://``yourwebserver``:``port`/`reports/rwwebservice`, is correct.

Note: The hostname specified should be the hostname where the OC4J instance is running and not where the Reports Server is running.

If the URL is not correct, you must do the following:

1. Shut down OC4J.

2. Delete the `__java_stateless_rpc` located under the `ORACLE_HOME``\j2ee\``OC4J_INSTANCE_NAME``\application-deployments\reports\web\temp\` directory.

3. Restart OC4J.

4. Verify that the URL defined reflects: `http://``yourwebserver``:``port``/reports/rwwebservice`

Oracle Reports WSDL

     <?xml version="1.0" encoding="UTF-8" ?>
     <definitions name="RWWebService"
    targetNamespace="http://oracle.reports.rwclient/RWWebService.wsdl"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://oracle.reports.rwclient/RWWebService.wsdl"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
      <documentation>WSDL for Service: RWWebService, generated by Oracle WSDL toolkit (version: 1.1)</documentation>
     <types>
      <schema targetNamespace="http://oracle.reports.rwclient/RWWebService.xsd"
    xmlns:tns="http://oracle.reports.rwclient/RWWebService.xsd"
    xmlns="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      </types>
      <message name="runJobInput">
      <part name="param0" type="xsd:string" />
      <part name="param1" type="xsd:boolean" />
      </message>
      <message name="getServerInfoOutput">
      <part name="output" type="xsd:string" />
      </message>
      <message name="getAPIVersionInput" />
      <message name="getAPIVersionOutput">
      <part name="output" type="xsd:string" />
      </message>
    ...
     <portType name="RWWebServicePortType">
     <operation name="getServerInfo">
      <input message="tns:getServerInfoInput" />
      <output message="tns:getServerInfoOutput" />
      </operation>
     <operation name="getJobInfo">
      <input message="tns:getJobInfoInput" />
      <output message="tns:getJobInfoOutput" />
      </operation>
    ...
     <service name="RWWebService">
     <port name="RWWebServicePort" binding="tns:RWWebServiceBinding">
      <soap:address location="http://localhost:8888/reports/rwwebservice" />
      </port>
      </service>
      </definitions>

## 14.3 Oracle Reports Web Service Operations

Oracle Reports exposes the `RWWebService` servlet as a Web service with its public interfaces and bindings defined and described using XML. These public interfaces and bindings are published across the network through the WSDL.

The operations supported by the `RWWebService` endpoint are:

- getAPIVersion

- getServerInfo

- getJobInfo

- killJob

- runJob

### 14.3.1 getAPIVersion

The `getAPIVersion()` operation returns the version details of the Reports Server in XML format. This operation takes no parameters.

Note: `getAPIVersion` is the only operation that returns the entire SOAP response along with the result (in a string). The other operations, for example, `runJob` return the response as an XML block embedded within the SOAP response.

To view the `getAPIVersion` response:

1. Click the `getAPIVersion` link. The Test page should display no parameters and include only a Invoke button to submit the request.

2. Click Invoke. The SOAP response is displayed in a new window.

The following is a sample response of a `getAPIVersion` operation:

    <?xml version="1.0" encoding="UTF-8" ?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SOAP-ENV:Body>
        <ns1:getAPIVersionResponse
          xmlns:ns1="http://oracle.reports.rwclient/RWWebService.wsdl"
          SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <return xsi:type="xsd:string">10.1.2.x.x</return>
        </ns1:getAPIVersionResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

### 14.3.2 getServerInfo

The `getServerInfo(String` `serverName``, String` `authId``)` operation takes two parameters and returns the Reports Server information in an XML format.

The valid parameters are :

- `serverName`: A valid non-null server name. This operation returns an error if the specified server is not running in the network.

- `authId`: A string in the form of username/password, must be specified for a secured server. This parameter is ignored for a non-secure server.

To view the `getServerInfo` response:

1. Click the `getServerInfo` link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.

2. Enter the Reports Server name (`param0`) and `authId` (`param1`).

3. Click Invoke. The SOAP response is displayed in a new window.

The following is a sample output of the `getServerInfo` operation:

    <?xml version = '1.0' encoding = 'ISO-8859-1' standalone = 'yes'?>
    <serverInfo name="repserv" version="10.1.2.x.x">
       <host>incq246bc</host>
       <processId>2588</processId>
       <startTime>27-May-2003 10:09:34</startTime>
       <queue maxQueueSize="1000"/>
       <engine id="rwEng" activeEngine="1" runningEngine="0"/>
       <engine id="rwURLEng" activeEngine="1" runningEngine="0"/>
       <performance>
          <property name="successfulJobs" value="6"/>
          <property name="currentJobs" value="0"/>
          <property name="futureJobs" value="0"/>
          <property name="transferredJobs" value="0"/>
          <property name="failedJobs" value="0"/>
          <property name="AverageResponseTime" value="2124"/>
          <property name="executionTimeToDate" value=""/>
       </performance>

</serverInfo>

### 14.3.3 getJobInfo

The `getJobInfo(``Integer` `jobId``, String` `serverName``, String` `authId``)` operation returns the job information in XML format.

The valid parameters are:

- `jobId:` JobId of the job for which information is required.

- `serverName`: A valid non-null Server name value must be supplied. This operation returns an error if the specified server is not running in the network.

- `authId`: A string in the form of username/password, must be specified for a secured server. For a non-secure server this parameter is ignored.

To view the `getJobInfo` response:

1. Click the `getJobInfo` link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.

2. Enter the `jobId` (`param0`), Reports Server name (`param1`), and `authId` (`param2`).

3. Click Invoke. The SOAP response is displayed in a new window.

The following is a sample output of a `getJobInfo` operation for `job id=3`:

    <?xml version = '1.0' encoding = 'ISO-8859-1' standalone = 'yes'?>
    <serverQueues>
       <job id="3" queueType="past">
          <name>test.rdf</name>
          <type>report</type>
          <status code="4">Finished successfully</status>
          <owner>RWUser</owner>
          <server>repserv</server>
          <destination>
             <desType>cache</desType>
             <desFormat>html</desFormat>
             <file>21748116.htm</file>
             <file>217481161.jpg</file>
             <file>217481160.jpg</file>
          </destination>
          <timingInfo>
             <queued>27-May-2003 10:21:50</queued>
             <started>27-May-2003 10:21:50</started>
             <finished>27-May-2003 10:21:51</finished>
          </timingInfo>
       </job>

</serverQueues>

### 14.3.4 killJob

The `killJob(``Integer` `jobId``, String` `serverName``, String` `authId``)` operation kills the job based on the job id specified and returns the status of the operation in XML format.

The valid parameters are:

- `jobId:` JobId of the job for which information is required.

- `serverName`: A valid non-null Server name value must be supplied. This operation returns an error if the specified server is not running in the network.

- `authId`: A string in the form of username/password, must be specified for a secured server. For a non-secure server this parameter is ignored.

To view the `killJob` response:

1. Click the `killJob` link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.

2. Enter the `jobId` (`param0`), Reports Server name (`param1`), and `authId` (`param2`).

3. Click Invoke. The SOAP response is displayed in a new window.

The following is a sample output of a `killJob` operation for Job ID=3:

    <?xml version = '1.0' encoding = 'ISO-8859-1' standalone = 'yes'?>
    <serverQueues>
       <job id="3" queueType="past">
          <name>test.rdf</name>
          <type>report</type>
          <status code="7">Canceled upon user request</status>
          <owner>RWUser</owner>
          <server>repserv</server>
          <destination>
             <desType>cache</desType>
             <desFormat>html</desFormat>
          </destination>
          <timingInfo>
             <queued>27-May-2003 10:21:50</queued>
             <started>27-May-2003 10:21:50</started>
             <finished>27-May-2003 10:22:00</finished>
          </timingInfo>
       </job>

</serverQueues>

### 14.3.5 runJob

The `runJob(``````String` `commandLine``, Boolean` `synchronous``)` operation runs a job to the Reports Server specified as part of the `commandLine` parameter.

Note: Oracle Reports Web service does not return the job output or the actual report.

The valid parameters are:

- `commandLine`: The complete command line syntax for submitting a job. For example:

      server=repserv report=test.rdf destype=file desname=output.pdf desformat=pdf         userid=scott/tiger@oraDB

  Note: The command line parameter cannot include `paramform=yes`. You have to pass the actual values for the parameter as part of the `commandLine` argument.

- `synchronous`: A Boolean object to indicate if the job should be run synchronously.

To view the `runJob` response:

1. Click the `runJob` link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.

2. Enter the command line syntax (`param0`), whether the job should run synchronously (T/F, Y/N) (`param1`).

3. Click Invoke. The SOAP response is displayed in a new window.

The following is a sample output of a `runJob` operation:

    <?xml version = '1.0' encoding = 'ISO-8859-1' standalone = 'yes'?>
    <serverQueues>
       <job id="7" queueType="current">
          <name>test.rdf</name>
          <type>report</type>
          <status code="1">Waiting in the queue</status>
          <owner>RWUser</owner>
          <server>repserv</server>
          <destination>
             <desType>file</desType>
             <desName>output.pdf</desName>
             <desFormat>pdf</desFormat>
          </destination>
          <timingInfo>
             <queued>27-May-2003 10:22:00</queued>
             <started>27-May-2003 10:22:00</started>
             <finished>27-May-2003 10:22:00</finished>
          </timingInfo>
       </job>

</serverQueues>

## 14.4 Installing and Using the Sample Proxy and Java Client

The `RWWebService` Web page contains a link to a sample proxy. This sample proxy invokes the Web service internally using the appropriate SOAP messages. Thus, the proxy accesses the various operations performed by the Web service and invokes them using the appropriate parameters.

The following procedure outlines the necessary steps involved in installing the proxy:

1. Download the `rwwebservice.zip` file from the Proxy Jar link displayed on the RWWebService Web page.

2. Include the path to the `rwwebservice.zip` file in your system classpath.

3. Include the `ORACLE_HOME``\soap\lib\soap.jar,` `ORACLE_HOME``\j2ee\home\lib\http_client.jar;` entries in your system classpath.

4. Include either one of the following in your system classpath:

   - The `xmlparserv2.jar` located in the`` `ORACLE_HOME\``lib\xmlparserv2.jar` directory.

   - The Xerces 1.4.4 parser, `xerces.jar`.

     Note: You must specify the location of the xmlparser in the system classpath. If you do not specify the location, the SOAP response will be displayed minus the <> symbols.

5. Modify the `RWWebServiceTest.java` to reflect your Reports Server name and the `authid`. For more information on constructing a Java client, refer to Example 14-1.

   Note: The `authid` for non-secured Reports Server is `null`.

6. Compile and run the `RWWebServiceTest.java` file.

7. Run the various operations using the sample Java client. For example, get the API Version (getAPIVersion), run a job(runJob), check the status of any job (getJobInfo), or get the Reports Server information (getServerInfo).

   Note: You can submit many jobs concurrently from multiple windows using the sample Java client.

Example 14-1 illustrates the contents of the `RWWebServiceTest.java` file.

Example 14-1 RWWebServiceTest.java

    /*
     * $Id: RWWebServiceTest.java
     * @author Anil Sharma
     *
     * Copyright (c) Oracle Corporation 2003.  All Rights Reserved
     *
     * FUNCTION
     * This is a sample class to demonstrate how the Oracle Reports WebService
     * Proxy class(oracle.reports.rwclient.proxy.RWWebServiceProxy) can be used
     * to invoke the Reports WebService from Java Clients. Java based Reports
     * Clients will use the demonstrated mechanism for invoking & parsing the
     * results using
     *
     * NOTES
     * 'oracle.reports.rwclient.proxy.RWWebServiceProxy' class is supplied as part
     * of rwwebservice.zip file which can be downloaded by invoking the Reports
     * WebService from a browser. Please consult Chapter 14 of
    Oracle Application Server Reports Services Publishing Reports to the Web manual,
    available on
     * the Oracle Technology Network Oracle Reports Documentation page
     * (http://www.oracle.com/technology/documentation/reports.html) for details.
     *
     * CREATED   Anil Sharma    06/13/03
     */

    import oracle.reports.rwclient.proxy.RWWebServiceProxy;

    /**
     * This class creates an instance of RWWebServiceProxy and makes API
     * calls on it to interact with Reports Server WebService. The result from
     * the webservice is usually an XML object which is printed as-is to the
     * Standdard output stream. Java based Reports Clients making use of this
     * WebService class might need to parse the XML to extract meaningful
     * information.
     *
     */

    public class RWWebServiceTest
    {

      public static void main(String[] args)
      {

        String serverName = "repserv";          //Name of the Reports Server
        String authid     = "portal/welcome1";  //authid, should be null if
                                                //server is not secured.
        String cmdline    = "server=repserv report=test.rdf "+
              "destype=file desname=output.pdf desformat=pdf "+
              "userid=scott/tiger@orcl";
        try
        {
          RWWebServiceProxy proxy = new RWWebServiceProxy();

          /**
           * The following piece of code invokes proxy class' getAPIVersion()
           * to get the Reports Server version information.
           */
          System.out.println("Get Reports Server Version:");
          System.out.println("RESULT:"+proxy.getAPIVersion());

          /**
           * Get the Reports Server Information in XML format. This will contain
           * some server runtime as well as configuration information.
           */
          System.out.println("Get Server Info:");
          System.out.println("RESULT:\n"+proxy.getServerInfo(serverName, authid));

          /**
           * Get information about a particular job (the job ID needs to be
           * specified.
           */
          System.out.println("Get JobInfo for Job Id=3:");;
          System.out.println("RESULT:\n"+proxy.getJobInfo(new Integer(3), serverName, authid));

          /**
           * Kill a job with a given job ID.
           */
          System.out.println("Kill job with Job Id=3:");
          System.out.println("RESULT:\n"+proxy.killJob(new Integer(3), serverName, authid));

          /**
           * Submit a job to the server. The command string takes the same form
           * as the one used for rwclient or any other Oracle Reports client.
           * You can specify whether to run the job synchronously or not. The
           * returned string is in XML format indicating the job status. Please
           * note that with Oracle Reports 10g, you can not get the
           * job output.
           */
          System.out.println("Run a job on server");
          System.out.println("RESULT:\n"+proxy.runJob(cmdline, new Boolean(true)));

        }
        catch (Exception e)
        {
          e.printStackTrace();
        }
      }
    }