[Download] | [Documentation Home] | [Release Note]

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 RDMBS Data Service using the wizard in WSO2 WSAS. Please refer sub links on your left menu to learn how to create other type of data services.

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

Deleting a Data 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>