[Download]
| [Documentation Home] | [Release Note]
WSO2 Web Services Application Server (WSO2 WSAS), v2.1-RC1-
Data Services
This document provides information and instructions on hosting
Data Services on WSO2 WSAS .
For additional information, please refer to the Data
Services Specification
Your feedback on WSO2 WSAS is most appreciated. Please send them to our mailing lists.
Introduction
WSO2 WSAS Data Service allows you to expose data in your relational databases through web services as XML.
The database query to XML mapping is done declaratively using an XML configuration file by the user, without doing any coding.
You can write the XML configuration yourself, or use the Data Service Wizard in the WSAS management console
to create Data Service configurations. You can use insert, select, update and delete (CRUD) statements,
stored procedures and most of the DDL statements in SQL statements.
The result of the query is transformed in to XML format with the user specified structure and is
accessible through a Web service operation. A Data service configuration is stored as an XML file
with the extension .dbs in the WSAS_HOME/repository/dataservices directory.
Creating a Data Service
The following instructions show you how to create a Data Service using the wizard in WSO2 WSAS.
- Log in to WSO2 WSAS Management Console.
- Go to Manage -> Services
- Click on 'Define Data Service'
- Data Service wizard will appear.
Right side of the screen will show a preview of the generated Data Service configuration XML.
Data Service Step 1
Configuration
Enter Database connection details including driver class, JDBC URL, username and password.
The JDBC driver should be available in the WSAS_HOME/lib directory.
Data Service Management - Add Configuration Parameter
Enter additional database connection parameters specific to the database server if required.
Data Service - Step 2
Queries
Displays already defined queries
SQL Query/Stored Procedure Configuration
Enter the SQL statement with a unique query ID. Query ID is used to bind the query with Web service operations.
Input Mappings
Enter input parameters with their types. Parameters can be given at runtime to customize the query results.
For example, the SQL query can be given as 'select customer_id, name, city from customers where customer_id = ?'
Then Input Mapping 'Name' parameter can be sent as an argument when calling the Web service operation.
Result to Output Mapping
This section defines the output query results to XML mapping details. For example database query result column 'column_name' should be mapped in to an element 'element-name' in the XML. This is done by element name to column name mapping pairs.
Grouping element name is the parent element of the results XML. Row name is the parent element of each query result row.
Output mapping syntax:
<grouping-element-name>
? ?
? <row-name>
? ?
? ? ?
? <element-name-1>column 1
value</element-name-1>
? ?
? ? ?
? <element-name-2>column 2
value</element-name-2>
? ?
? <row-name>
? ?
? <row-name>
? ?
? ? ?
? <element-name-1>column 1
value</element-name-1>
? ?
? ? ?
? <element-name-2>column 2
value</element-name-2>
? ?
? <row-name>
</grouping-element-name>
Data Service - Step 3
Operations
Displays already defined Web service operation to query mappings
Add/Edit Operation
Enter mappings between Web service operations and queries. This will bind the Web service operations with previously defined SQL queries.
You can navigate back and forth between the wizard pages by clicking on 'Back' and 'Next' respectively. Right side of the screen will show a preview of the Data Service configuration XML.
Modifying a Data Service
- Log in to WSO2 WSAS Management Console.
- Go to Manage -> Services
- The page will list all the available services below 'Add New Service' section.
- Click on 'Services' column of the relevant Data Service.
- Click on 'Configure Data Service' in the option list below.
- Data Service wizard will appear.
Deleting a Data Service
- Log in to WSO2 WSAS Management Console.
- Go to Manage -> Services
- The page will list all the available services below 'Add New Service' section.
- Click on remove button on the relevant service.
Sample Data Service configuration
A sample Data Service configuration XML is shown below.
<data
name="sales">
? ? ?
<config>
? ? ? ? ? ? ?
<property
name="org.wso2.ws.dataservice.driver">com.mysql.jdbc.Driver</property>
? ? ? ? ? ? ?
<property
name="org.wso2.ws.dataservice.protocol">jdbc:mysql://server1:3306/sales</property>
? ? ? ? ? ? ?
<property
name="org.wso2.ws.dataservice.user">wsas</property>
? ? ? ? ? ? ?
<property
name="org.wso2.ws.dataservice.password">wsas</property>
? ? ?
</config>
? ? ?
<operation
name="getCustomers">
? ? ? ? ? ? ?
<call-query
href="getCustomersQuery"/>
? ? ?
</operation>
? ? ?
<operation
name="getCustomerById">
? ? ? ? ? ? ?
<call-query href="getCustomerByIdQuery">
? ? ?
? ? ? ? <with-param
name="customer_id"
query-param="customer_id"/>
? ?
? ? </call-query>
? ? ?
</operation>
? ? ?
<query
id="getCustomersQuery">
? ? ? ? ? ? ?
<sql>select customer_id, name, city from
customers</sql>
? ? ? ? ? ? ?
<result element="customers" rowName="customer">
? ? ? ? ? ? ? ? ? ? ?
<element name="customer_id"
column="customer_id"/>
? ? ? ? ? ? ? ? ? ? ?
<element name="name"
column="name"/>
? ? ? ? ? ? ? ? ? ? ?
<element name="city"
column="city"/>
? ? ? ? ? ? ?
</result>
? ? ?
</query>
? ? ?
<query id="getCustomerByIdQuery">
? ? ? ? ? ? ?
<param name="customer_id"
sqlType="INTEGER"/>
? ? ? ? ? ? ?
<sql>select customer_id, name, city from customers where
customer_id =
?</sql>
? ? ? ? ? ? ?
<result element="customers" rowName="customer">
? ? ? ? ? ? ? ? ? ? ?
<element name="customer_id"
column="customer_id"/>
? ? ? ? ? ? ? ? ? ? ?
<element name="name"
column="name"/>
? ? ? ? ? ? ? ? ? ? ?
<element name="city"
column="city"/>
? ? ? ? ? ? ?
</result>
? ? ?
</query>
</data>
Sample output XML
After deploying this Data Service, 'sales' Web service will have 'getCustomers' and 'getCustomerById' operations. 'getCustomers' operation will return query results as shown below.
<customers>
? ?
? <customer>
? ?
? ? ?
? <customer_id>10<customer_id>
? ?
? ? ?
? <name>Peter</name>
? ?
? ? ?
? <city>London</city>
? ?
? </customer>
? ?
? <customer>
? ?
? ? ?
? <customer_id>11<customer_id>
? ?
? ? ?
? <name>Mark</name>
? ?
? ? ? ? <city>New
York</city>
? ?
? </customer>
? ?
? <customer>
? ?
? ? ?
? <customer_id>12<customer_id>
? ?
? ? ?
? <name>Jane</name>
? ?
? ? ? ? <city>San
Jose</city>
? ?
? </customer>
</customers>