Data Services

This document provides information and instructions on creating data services on the WSO2 Mashup Server.

Data Services 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 Mashup Server 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 your scripts directory.

Creating a Data Service

The following instructions show you how to create a RDMBS Data Service using the wizard in the WSO2 Mashup Server. Please refer to the links in the 'further reading' section for details on creating other type of data services.

Log in to the WSO2 Mashup Server
Go to Management Tasks -> Create a new 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 - 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 the WSO2 Mashup Server
Select the data service from the list of mashups
Click on 'Edit this mashup (Data Service)'
Data Service wizard will appear.

Deleting a Data Service

Log in to the WSO2 Mashup Server
Select the data service from the list of mashups
Click on the 'Delete this mashup' link and confirm deletion.

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>