BPS50

Web Services Data Source

This project aims to provide Web Services Data Source ODA implementation for BIRT and other ODA consumer applications.

Specification Leads

Gary Xue, Actuate Corp.

Lin Zhu, Actuate Corp.

Description

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

Introduction

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 “org.eclipse.datatools.enablement.oda.ws”. The data source designer plugin name is “org.eclipse.datatools.enablement.oda.ws.ui”.

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., "http://www.classicmodelsinc.com:5670/products"
driverClass	Custom Driver Class Name	If this property is defined, connection and query are made through a user-provided Java class by this name. See Section 1.3.4 Custom Driver Class for specification of the custom driver class.
driverClassPath	Custom Driver Class Path	A semicolon(;)-separated list of additional JAR files and directories to search for the custom driver class. If the driverClass property is set, BIRT first searches this list for the custom driver class. It will then use the application class path if the driver class is not found.
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 Driver Class

The second and final wizard page asks the user to specify the SOAP end point URL and the driver class specification. One or both of these two sets of properties must be defined. If the Customer Driver Class property is defined, the driver will use the custom driver 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 at runtime(see Section 1.3.4 Custom Driver Class ).

If the Custom Driver 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 Driver 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 Driver 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.

TODO: update mockup to include driverClassPath property. Rename "Connection Class" to "Driver Class".

Custom Driver Class

The Driver Class

If the data source’s driverClass public property is set to a non-empty string, the runtime driver will use a custom driver class to create connections to the web service. The custom driver class will also be responsible for executing the web services queries for Web Services Data Sets associated with this data source.

The driverClass property is the fully qualified name of a Java class which must implement the following class method to establish a web services connection. The Java class must be in the application class path or the class path defined by the driverClassPath property.

public static Object connect(
      java.util.Map connectionProperties,
      java.util.Map appContext);

The connectionProperties parameter specifies the runtime values of all public connection properties available to the driver as a (String, String) map keyed by connection property name. The map may contain any or all of the following map keys: soapEndPoint, connectionTimeOut, driverClass and driverClassPath.

The appContext parameter provides all the application context values as (String, Object) pairs. Its value is never null, but its collection may be empty.

The connection Instance

The connect method of the custom driver class, upon establishing a successful connection, will return a non-null object which implements the following two methods.

public Object executeQuery(
     java.lang.String queryText,
     java.util.Map parameterValues,
     java.util.Map queryProperties);

public void close();

The executeQuery Method

The queryText parameter specifies the query text. It can be null if the connection class does not require the report design to provide a query text.

The parameterValues parameter specifies values of all the data set parameters as a (String, Object) map keyed by parameter name. It may be null if the data set does not define any parameters.

The queryProperties parameter specifies values of all the data set public properties as a (String, String) map keyed by property name. The map may contain any or all of the following map keys: queryTimeOut.

The query method must return a value of any of these data types:

• java.lang.String: the returned String is the complete SOAP response.

• java.io.InputStream: the returned stream is SOAP response stream.

The close Method

This method closes the connection. Driver's implementation of the close method is optional. If it is implemented, BIRT will call this method when the associated data source is closed.

Method Calling and Error Handling

The driver calls the custom driver class using Java reflection. Therefore the class and its connection object do not need to implement any predefined interface. Any exception thrown by any of the methods defined above will be treated as error and will result in a failure and an ODAException being thrown.

Web Services ODA Data Set Specification

Data Set Name and Identifier

The Web Services Data Source supports a single data set type. It is named “Web Services Data Set”, and its ODA data set identifier is “org.eclipse.datatools.enablement.oda.ws.WSDataSet”

Data Set Public Properties

A Web Services Data Set defines properties for querying a connected web service. In addition to the queryText property (which applies to all ODA data sets), the data set defines the following public properties, the value of which can be specified as a static value in the data set editor, or it may be bound to a Javascript expression through property binding.

Property Name	Display Name	Description
queryTimeOut	Query Timeout (in seconds)	Number of seconds allowed for executing a Web Services query. A timeout error will be reported if the query does not return its complete result within this time limit. Default value is 300.

Query Text and Input Parameters

The Web Services Data Set supports input parameters. Input parameters are defined by the report designer, and may be edited in either the Data Set Editor’s Parameters tab, or in the query editor UI of the data set designer (see UI mockup in the following sections).

SOAP Request Template

The Query Text of a Web Services Data Set defines the SOAP request template. Any part of the SOAP request template (including tag names, attribute values and element value) may refer to a data set input parameter. Such references are replaced by the value of input parameters at report runtime to create the actual SOAP request. Reference to data set input parameter in the request template is enclosed in the following markers:

&?parameter_name?&

NOTE: The &? delimiters are chosen because they never appear in sequence in a well-formed XML document (except in CDATA sections). Use of these delimiters minimizes the possibility that they be erroneously recognized in a normal SOAP message.

The “&?...?&” markers must appear in pairs, and the opening markers must occur in the same text line as the closing markers. Otherwise they are not recognized as a parameter reference, and will be treated as part of the SOAP request.

Request Template Example

The following query text for a Web Services Data Set defines the template for a SOAP SearchProducts request. It refers to a data set input parameters, ProductName, which must be defined on the data set.

  <?xml version="1.0" encoding="UTF-8" ?> 
  <soapenv:Envelope   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:q0="http://classicmodelsinc.com/schemas/ClassModelsWebAPI" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <q0:SearchProducts>
       <q0:ProductName>&?ProductName?&</q0:ProductName> 
    </q0:SearchProducts>
  </soapenv:Body>
  </soapenv:Envelope>

At report execution time, assuming that data set parameter ProductName is resovled to string value “Ford Model T”, the actual SOAP request is issued as:

  <?xml version="1.0" encoding="UTF-8" ?> 
  <soapenv:Envelope   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:q0="http://classicmodelsinc.com/schemas/ClassModelsWebAPI" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <q0:SearchProducts>
       <q0:ProductName>Ford Model T</q0:ProductName> 
    </q0:SearchProducts>
  </soapenv:Body>
  </soapenv:Envelope>

Data Set Input Parameter Types

A data set input parameter can be of any data type supported by ODA. The WS-ODA runtime driver converts the input parameter value to String before inserting them into the SOAP request. The conversion follows the XML Schema 1.1 Specification with regard to the rules of representing primitive data type values: [[1]]

Example: Date/time parameter value of “4:05 PM, January 13, 2006” (US English format), is converted to string “2006-01-13T16:05:00”.

If non-conforming conversion of values is needed, the user should define the data set parameter as String type, and perform the custom conversion in the data set parameter binding expression.

Web Services Data Set Creation UI Mockup

Creating a Web Services Data Set

When a Web Services Data Source is selected in the New Data Set Dialog, a single Data Set Type, “Web Services Data Set”, is available in the Data Set Type dropdown list.

Selecting a WSDL Service

This dialog is displayed only if the data source has specified a valid WSDL descriptor. If no WSDL is available for the data source, the wizard will skip this dialog and will bring the user to the dialog in Section Edit Soap Request , where he can enter the query text without the help of WSDL.

The dialog will displays, in a tree structure, all the SOAP bindings and services defined in the WSDL. The user should select a SOAP operation (from a tree leaf node) and continue to the next dialog to create a SOAP request template based on the selected operation’s schema.

If the “Skip>” button is selected, the WSDL document is not used to create the SOAP request template, and the next wizard dialog is skipped. The user will be brought to the dialog in Section Edit Soap Request.

NOTE: This dialog is modeled after part of the Web Services Explorer View of the Eclipse Web Tools project.

Generating SOAP Request Template From WSDL

This dialog is displayed only if the user has selected a WSDL operation in the dialog in Section Selecting a WSDL Service, and selects “Next>”. The dialog displays a form which helps the user to create a SOAP request template based on the WSDL definition of the selected operation.

NOTE: This dialog is modeled after part of the Web Services Explorer View of the Eclipse Web Tools project. The Add and Remove hyperlinks, the checkboxes and the textboxes shall behave the same as they do in that view.

The Insert Parameter hyperlink, when clicked, will cause a Parameter Selection Dialog to be shown. The user can select an existing data set parameter, or create a new one, to be associated with the SOAP request parameter. The wizard will then insert the parameter reference marker (&?param_name?&) into the textbox for that request parameter.

Parameter Selection Dialog

In dialogs in Section Generating SOAP Request Template From WSDL and the dialog in Section Edit SOAP Request, choosing "Insert Parameter" will cause the wizard to show the following popup dialog. The user can select an existing data set parameter from this dialog, or create a new one. He may also edit or remove existing data set parameter. When the OK button is clicked, the selected data set parameter from the list is inserted into the SOAP request template.

Edit SOAP Request

This dialog allows the user to view and edit the SOAP request template (the query text of the data set). This is the first dialog of the wizard if no WSDL descriptor is available for the data source. If the WSDL descriptor is available and the user has completed dialog in Section Generating SOAP Request Template From WSDL to define the SOAP request, this dialog shows the generated SOAP request.

If no SOAP request template has been defined when this dialog is initially shown, the dialog will create an SOAP request that includes empty header and body sections.

The "Insert Parameter …" button will cause the Parameter Selection Dialog to be shown.

The "Clear" button clears the entire text area. Note that not all Web Services data sets require a query text. In the case that the data source uses custom Java driver class, the driver may not use the query text defined in the data set for its query. Therefore this dialog permits an empty query text to be defined.

Define SOAP Response

This dialog defines the SOAP response schema and selects a sample SOAP response message. This is the prerequisite for mapping the SOAP response to a tabular result set. If the WSDL descriptor for the data source is available, the user may choose to use the response schema defined in the WSDL. This is the default option. If WSDL is not available, this checkbox is disabled. The user may select an external XML Schema (XSD) file for the response.

The user may choose to issues a Web Services query to obtain a response message. If this option is selected, he may enter a SOAP endpoint to connect to (the data source’s SOAP end point property is used by default), and then select “Connect Now” to issue the SOAP request.

The user may also choose to use an external file to supply a sample response message.

Either a SOAP response schema, or a SOAP response message, or both, must be provided before the wizard can proceed to the next step.

Define Relational Mapping of SOAP Response

The subsequent dialogs duplicate the XML to relational mapping dialogs of the DTP-XML ODA data source.