Introduction to BIRT Web Services Data Source

balecomputerΑσφάλεια

3 Νοε 2013 (πριν από 3 χρόνια και 7 μήνες)

102 εμφανίσεις


-

1

-


Introduction to BIRT Web Services Data Source

Keywords

Actuate, BIRT

XML

Web Services

SOAP

Data Source

Version Control

Version

Date

Description of Changes

Draft 1

Jun 06 2008

First draft

















www.actuatechina.com




-

2

-


Table of Contents

1. Introduction

................................
................................
................................
................................
.............

3

2. Features and Requirements

................................
................................
................................
...................

3

3.

Create BIRT Web Services Data Source

................................
................................
...............................

4

3.1 Select a Data Source Type

................................
................................
................................
..............

4

3.2 New a Web service Data Sour
ce

................................
................................
................................
.....

5

4. Create BIRT Web Services Data Set

................................
................................
................................
......

8

4.1 New a Web Services Data Set

................................
................................
................................
........

8

4.2 Select an operation

................................
................................
................................
..........................

9

4.3 Enter the parameters of chos
en WSDL operation

................................
................................
.........

10

4.4 Edit the SOAP request template

................................
................................
................................
....

11

4.5 Edit the SOAP response

................................
................................
................................
................

12

4.6 Table Mapping

................................
................................
................................
...............................

13

5.

References

................................
................................
................................
................................
.............

13



























www.actuatechina.com




-

3

-


1.

Introduction

Web
S
ervices are a new breed of Web application. They are self
-
contained,
self
-
describing, modular applications that can be published, locat
ed, and invoked
across the Web.

The BIRT Web Services Data S
ource 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.

This article serves as an introduction to BIRT

Web Services

Data Source.

2.

Features and Requirements



WSDL is the most common service description language for Web Services. The
BIRT WS driver understands WSDL, and can use information contained therein
to help the user define the following properties

required by the runtime driver.



The WS 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



Where the WSDL descriptor of a web service is not available, the user m
ay
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 classes that implements a numb
er 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 s
cheme that’s not
supported by the WS driver.



The entire XML to relational mapping facility including its drag
-
and
-
drop mapping
UI and its advanced XPath expression support, is available to the BIRT WS driver
to map a SOAP response message to a tabular resu
lt set







www.actuatechina.com




-

4

-


3.

Create

BIRT Web Services
Data Source

3.1

Select a Data Source Type








www.actuatechina.com




-

5

-


3.2
New a
Web service

Data Source


WSDL URL or Location

The user need specify the WSDL descriptor of the Web Services to connect to.

The
example
used
in this
article
is
the
W
eb
S
ervice
s

provided by Google.

SOAP En
d Point and Custom Driver Class

SOAP end point
is
a
receive
d

servlet.
The two texts
ask 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 d
efined. 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 p
assed to the custom class’s
connect

method as a
connection property at runtime

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.







www.actuatechina.com




-

6

-


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.


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
c
onnect 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 Driver Class

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 conn
ectionProperties,


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 emp
ty.

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.






www.actuatechina.com




-

7

-


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.

The Test Connection button
attempts to validate the connection method specified
by the user.







www.actuatechina.com




-

8

-


4.

Create
BIRT Web Services
Data Set

4.1

New

a
Web Services
D
ata
S
et








www.actuatechina.com




-

9

-


4.2

Select an operation


T
his 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 of
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 lea
f
node) and continue to the next dialog to create a SOAP request template based on
the selected operation’s schema.








www.actuatechina.com




-

10

-


4.3

Enter

the parameters of chosen WSDL operation


The user can select existing data set parameters from this dialog, The parameters is
d
efined in WSDL file. When the OK button is clicked, the selected data set parameter
from the list is inserted into the SOAP request template






www.actuatechina.com




-

11

-


4.4
Edit the SOAP request template


This dialog allows the user to view and edit the SOAP request template (the qu
ery
text of the data set).

The SOAP request
SOAP

is
XML
document.

&?parameter_name?&

The parameter in the request template is enclosed in the following markers

The &? delimiters are chosen because they never appear in sequence in a
well
-
formed XML document
(except in CDATA sections).

The
"
insert parameter button
"

can be used to set default value to the parameters

The "
Clear
" button clears the entire text area.








www.actuatechina.com




-

12

-


4.5
Edit the SOAP response



This dialog defines the SOAP response schema and selects a sample S
OAP
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. I
f 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 en
dpoint 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.






www.actuatechina.com




-

13

-


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


4.6

Table Mapping


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


5.

References

BIRT Official

Site:
www.eclipse.org/BIRT

W3C Web Services
http://www.w3.org/2002/ws/

W3C XML

http://www.w3.org/XML/






www.actuatechina.com




-

14

-


BIRT
Exchange

website

www.
birt
-
exchange
.com

Introduction to BIRT XML Data Source