Documentation

##### WSO2 WSAS 2.2-RC1

- Release Notes
- Contents
- Home

##### Downloads

- Releases

##### Documentation

- User Guide
- FAQs
- Installation Guide
- Source
- Running Behind a Proxy
- Data Services Guide
  - RDBMS Data Source
  - CSV Data Source
  - Excel Data Source
  - JNDI Data Source
- EJB Guide
- Clustering Guide
- JMX Guide
- XKMS Guide
- Changing Keys

##### Samples

- Chad
- Commodity Quote
- Data Services
- Flickr
- Javascript
- Jaxws
- JiBX
- Mtom
- STS
- Trader
- Tiny URL
- Metadata Exchange
- WS-Transfer
- XML Key Managment Specification
- Cluster Management

##### API Documentation

- Java Docs

##### Tools

- Code Generation
- Change Password
- Eclipse IDE Integration
- TCP Monitor
- WSDL2Code
- WSDL View
- Try It
- AAR Validation
- MAR Validation

##### Resources

- News

##### Get Involved

- Mailing Lists
- Integration

##### Project Information

- Project Team
- Issue Tracking
- License

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

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

###