Creating a web services data source using a custom connection class
You can use a custom connection or driver class to create a web services data source. The custom driver class is responsible for returning an input stream that contains a SOAP XML response. This class must implement a connect( ) method. This method has to return an Object, that implements an executeQuery( ) and an optional disconnect( ) method.
The connect( ) method accepts two parameters, which contain the connection properties and application context.
BIRT uses an application context map to store values and objects for use in all phases of report generation and presentation. You can reference objects in the application context from Script, the expression builder, in the ODA layer, and so forth. The application context map contains specific name-value pairs that are passed to all generation and rendering processes.
You can use the application context to pass a security identifier that can be validated in the connection class and passed in as part of the SOAP request. In many cases the web services require such identifiers.
The custom driver class
If you specify a custom driver class when defining your web services data source, the run-time driver uses that class to create connections to the web service. The custom driver class is also responsible for executing the web services queries for web services data sets associated with this data source.
The custom driver class you provide must be the fully qualified name of a Java class. The class must implement the following method to establish a web services connection. Specify the location of the JAR containing the custom driver class in Driver Class Path.
public static Object connect(
java.util.Map<String, String> connectionProperties,
java.util.Map<String, Object> appContext );
The connectionProperties parameter specifies the run-time values of all public connection properties available to the driver as a (String, String) map keyed by the connection property name. The map may contain any or all of the following map keys: soapEndPoint, connectionTimeOut, connectionClass, OdaConnProfileName, and OdaConnProfileStorePath.
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, after establishing a successful connection, returns a non‑null object that implements the following two methods:
public Object executeQuery(
java.lang.String queryText,
java.util.Map<String, Object> parameterValues,
java.util.Map<String, String> queryProperties );
public void disconnect( );
The executeQuery( ) method
The queryText parameter specifies the query text, which 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 can 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 can contain the queryTimeOut map key.
The query method must return a value of either of the following data types:
The returned String is the complete SOAP response.
The returned stream is a SOAP response stream.
The disconnect( ) method
This method closes the connection. The driver implementation of the disconnect method is optional. If it is implemented, BIRT calls this method when the associated data source closes. You can use it to close file streams and clean up other resources.
Method calling and error handling
The driver calls the custom driver class using Java reflection. The class and connection object do not need to implement any predefined interface. Any exception thrown by any of the defined methods is treated as an error and results in a failure and a thrown ODA exception.
Custom connection class example
Listing 40‑2 is an example of a custom class that accesses a set of connection properties, then instantiates a query object. In this example, the connection properties and the application context are not used.
Listing 40‑2 Custom driver class
import java.util.Iterator;
import java.util.Map;
public class MyConnectionClass {
public static Object connect(
Map<String, String> connProperties,
Map<String, Object> appContext ) {
Iterator<String> it = connProperties.keySet( ).iterator( );
while ( it.hasNext( ) ) {
String key = );
it = connProperties.values( ).iterator( );
while ( it.hasNext( ) ) {
// Get value
String value = );
MyWSQuery msq = new MyWSQuery( );
return msq;
Listing 40‑3 is an example of a query class implementation that executes a query by opening a file input stream and disconnects, closing the file.
Listing 40‑3 Query class implementation
import java.util.Map;
public class MyWSQuery {
FileInputStream fis = null;
Object executeQuery( String queryText,
Map<String, Object> parameterValues,
Map<String, String> queryProperties ) {
try {
fis = new FileInputStream(
"c:/temp/ExchangeRates.xml" );
} catch ( IOException e ) {
return fis;
public void disconnect( ) {
if( fis != null ) {
try {
fis.close( );
} catch (IOException e) {
fis = null;
Setting up a report that uses a custom driver class
After you have defined the custom driver and query classes for the data source, use Test Connection to confirm that the class loader can find your custom classes. A completed custom web services data source is shown in Figure 40‑9.
Figure 40‑9 Defining a web services data source with a custom driver
Note that a WSDL descriptor is provided as a placeholder even when it is not used by your custom driver class.
Next, define a data set from this custom data source. The New Web Services Data Set wizard helps you define the access to your web services data.
How to define a web services data set with a custom driver
1 In your report design, open Data Explorer.
2 Right-click Data Sets and choose New Data Set. Provide a name for your data set and choose Next.
3 In New Web Services Data Set, perform the following actions:
1 In WSDL Operation, select an operation, as shown in Figure 40‑10, and choose Next.
Figure 40‑10 Bypassing the WSDL operation
2 In SOAP Parameters, choose Next.
3 In SOAP Request, choose Next.
4 In SOAP Response, in Select SOAP Response Schema, select Use schema from response.
5 In Select Sample SOAP Response message, select Use external sample data file and specify a file matching the XML you are accessing with your custom driver class. The complete SOAP response definition is shown in Figure 40‑11. Choose Next.
Figure 40‑11 Defining the SOAP response
6 In Row Mapping, choose an area of the XML file that contains repeating nodes. Choose the arrow to populate the XPath expression.
7 In Select or edit the XPath Expression, choose XML elements name “<element-name>” at any location. Choose OK. Choose Next.
8 In Column Mapping, select all of the elements that you want to appear in your report. Choose the arrow to populate the column mappings, as shown in Figure 40‑12.
Figure 40‑12 Defining column mapping
9 Choose Show Sample Data to preview the data from the XML source. Choose Finish.
Test your report by dragging the new data set into the report design to create a table, then choose RunView ReportIn Web Viewer.