|
Oracle® Application Server Reports Services Publishing Reports to the Web
10g Release 2 (10.1.2) B14048-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Reports Services Publishing Reports to the Web
10g Release 2 (10.1.2) B14048-02 |
|
|
Previous |
Next |
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:
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.
This section outlines the steps necessary for:
To invoke the RWWebService servlet:
Start an Oracle Application Server Containers for J2EE (OC4J) instance where the Oracle Reports instance resides.
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:
View the Oracle Reports Web service WSDL.
Run any RWWebService command using a Web based UI.
Download the proxy JAR files and proxy sources to invoke the Oracle Reports Web service using the sample Java client.
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. |
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.
|
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" />
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:
Shut down OC4J.
Delete the __java_stateless_rpc located under the ORACLE_HOME\j2ee\OC4J_INSTANCE_NAME\application-deployments\reports\web\temp\ directory.
Restart OC4J.
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>
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:
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:
Click the getAPIVersion link. The Test page should display no parameters and include only a Invoke button to submit the request.
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>
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:
Click the getServerInfo link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.
Enter the Reports Server name (param0) and authId (param1).
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>
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:
Click the getJobInfo link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.
Enter the jobId (param0), Reports Server name (param1), and authId (param2).
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>
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:
Click the killJob link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.
Enter the jobId (param0), Reports Server name (param1), and authId (param2).
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>
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 includeparamform=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:
Click the runJob link. The Test page should display the relevant parameter fields and an Invoke button to submit the request.
Enter the command line syntax (param0), whether the job should run synchronously (T/F, Y/N) (param1).
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>
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:
Download the rwwebservice.zip file from the Proxy Jar link displayed on the RWWebService Web page.
Include the path to the rwwebservice.zip file in your system classpath.
Include the ORACLE_HOME\soap\lib\soap.jar, ORACLE_HOME\j2ee\home\lib\http_client.jar; entries in your system classpath.
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. |
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: Theauthid for non-secured Reports Server is null.
|
Compile and run the RWWebServiceTest.java file.
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();
}
}
}
