Skip to main content
Jump to: navigation, search


Revision as of 21:59, 31 January 2007 by (Talk | contribs) (Web Services ODA Data Source Specification)

Web Services Data Source

This project aims to provide Web Services Data Source ODA implementation for BIRT

Specification Leads

Gary Xue, Actuate Corp.

Lin Zhu, Actuate Corp.


The BIRT Web Services Data Source is an ODA extension that enables BIRT (and other Eclipse DTP/ODA enabled application) to query SOAP-based web services and use the query response as a source of reporting data.

Revision History

2007-1-31 [Gary Xue]: Initial draft


The BIRT Web Services Data Source is an ODA extension that enables BIRT (and other Eclipse DTP/ODA enabled application) to query SOAP-based web services and use the query response as a source of reporting data.

The Web Services ODA (WS-ODA) extension is built on top of the DTP/XML data source (XML-ODA). The WS-ODA driver reuses XML-ODA driver’s XML to relational data mapping facility to handle the tabular conversion (“flattening”) of SOAP response data. The WS-ODA driver therefore has a dependency on the XML-ODA driver.

Features and Requirements

WSDL Support

WSDL is the most common service description language for Web Services. The WS-ODA design-time driver understands WSDL, and can use information contained therein to help the user define the following properties required by the runtime driver: the soap endpoint, the soap request template (by reading the request message schema) and the XML-relational mapping (by using the response message schema).

This driver supports WSDL 1.1.

Data Set Parameter Support

The WS-ODA driver supports data set parameters. User-defined data set parameters may be created, and any part of the SOAP request may be bound to the runtime value of a data set parameter.

User Editable SOAP Request

Where the WSDL descriptor of a web service is not available, the user may directly enter the template SOAP request message. Data set parameters may be added to the SOAP request using special syntactic markers. The user may also modify the SOAP message template initially generated from WSDL.

Java Code as XML Source

Java classes that implements a number of driver-defined connection and query methods may be used as the source of the XML data. This is useful in the case where the user already has client code to process the web service request, or when the web service uses a connection or authentication scheme that’s not supported by the WS-ODA driver.

SOAP over HTTP Support

The WS-ODA driver has native support for web services that uses SOAP over HTTP. The full SOAP message, including SOAP headers of the request and response messages, can be accessed by the data source consumer.

Full Range of XML to Relational Mapping

The entire XML to relational mapping facility of the DTP/XML ODA driver, including its drag-and-drop mapping UI and its advanced XPath expression support, is available to the WS-ODA driver to map a SOAP response message to a tabular result set.

Web Services ODA Data Source Specification

Data Source Name and Identifier

The ODA Data Source for the Web Services ODA driver is named “Web Services Data Source”. The ODA data source identifier and the data source runtime driver plugin name is “”. The data source designer plugin name is “”.

Data Source Public Properties

A Web Services Data Source defines properties for establishing a connection to a web services provider. The connection can be made by the driver via SOAP/HTTP, or through a user-provided Java class.

The following ODA public connection properties are exposed by this driver. The values of these public properties can be bound to report-scope Javascript expressions by using the property binding feature of BIRT reports.

Property Name Display Name Description
soapEndPoint SOAP End Point A URL for the SOAP/HTTP endpoint that the driver should connect to. E.g., ""
connectionClass Connection Class Name If this property is defined, connection is made through a user-provided Java class by this name. See Section 3.4 for specification of the custom connection class.
connectionTimeOut Connection Timeout (in seconds) Number of seconds allowed for establishing a connection. Default value is 60 if it is not defined.

Data Source Creation UI Mockup

The following UI mockups illustrate the workflow of creating a Web Services Data Source. Note that the actual implementation of these UI pages may differ from the mockups.

Selecting Data Source Type


WSDL Selection

The first wizard page asks the user to specify the WSDL descriptor of the Web Services to connect to. WSDL descriptor is an optional property. If it is specified, this dialog should verify that the specified URL or file is valid, and that the target is a well-formed WSDL document.

The designer should store the value of the WSDL URL/location as a data source private property, as the WSDL document will be accessed again during data set creation to help define SOAP request template and response mapping.


SOAP End Point and Connection Class

The second and final wizard page asks the user to specify the SOAP end point URL and the connection class name. One or both of these properties must be defined. If the Connection Class property is defined, the driver will use the custom connection class to connect and query the web service. The SOAP End Point property may be left empty in this case. If SOAP End Point is also specified, its value will be passed to the custom class’s connect method as a connection property (see Section 3.4 ) at runtime.

If the Connection Class property is left empty, the driver will use the SOAP End Point URL to establish a SOAP/HTTP connection. The SOAP End Point property must be defined.

If a valid WSDL descriptor is provided in the last wizard dialog, the SOAP End Point input box will be pre-populated with the first service port location read from the WSDL. The user may edit this value to override the port location defined in WSDL.

The Test Connection button attempts to validate the connection method specified by the user. If a Custom Connection Class is specified, the wizard will attempt to load the class and call its connect() method, passing in the Soap End Point value and an empty application context map. If a Customer Connection Class is not specified, the wizard will attempt to connect to the specified Soap End Point. Any exception incurred in this process will be reported to the user, but will not prevent the user from finishing the wizard.


Custom Connection Class

Web Services ODA Data Set Specification

Back to the top