<!--
  ~ Copyright 2005-2007 WSO2, Inc. (http://wso2.com)
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
       "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<body>
<p>[<a
href="http://dist.wso2.org/products/wsas/java/@wso2wsas_version@">Download</a>]
| [<a href="index_docs.html">Documentation Home</a>] | [<a
href="release_notes.html">Release Note</a>]</p>

<h1>Data Services</h1>

<p>This document provides information and instructions on hosting
Data Services on WSO2 WSAS .</p>

<p><strong>For additional information, please refer to the <a href="http://wso2.org/wiki/display/wsf/Data+Services+and+Resources">Data
Services Specification</a></strong></p>

<p>Your feedback on WSO2 WSAS is most appreciated. Please send them to our <a
href="mail-lists.html">mailing lists</a>.</p>

<h3>Introduction</h3>

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


</p>

<h3>Creating a Data Service</h3>

<p>
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.
 
</p>
<ul>
	<li>Log in to WSO2 WSAS Management Console.</li>
	<li>Go to Manage -> Services</li>
	<li>Click on 'Define Data Service'</li>
	<li>Data Service wizard will appear.</li>
</ul>

<p>Right side of the screen will show a preview of the generated Data Service configuration XML.</p>



<h4>Data Service Step 1</h4>

<h5>Configuration</h5>
Enter Database connection details including driver class, JDBC URL, username and password.
The JDBC driver should be available in the WSAS_HOME/lib directory.



<h4>Data Service - Step 2</h4>
<h5>Queries</h5>
Displays already defined queries

<h5>SQL Query/Stored Procedure Configuration</h5>
Enter the SQL statement  with a unique query ID. Query ID is used to bind the query with Web service operations.

<h5>Input Mappings</h5>
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.

<h5>Result to Output Mapping</h5>
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.

<p>Output mapping syntax:</p>   <br/>
<pre>
    <![CDATA[
<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>
]]>
</pre>



<h4>Data Service - Step 3</h4>

<h5>Operations</h5>
Displays already defined Web service operation to query mappings

<h5>Add/Edit Operation</h5>

<p>Enter mappings between Web service operations and queries. This will bind the Web service operations with previously defined SQL queries.
</p>




<p>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.
</p>

<h3>Modifying a Data Service</h3>

<ul>
	<li>Log in to  WSO2 WSAS Management Console.</li>
	<li>Go to Manage -> Services</li>
	<li>The page will list all the available services  below 'Add New Service' section.</li>
	<li>Click on 'Services' column of the relevant Data Service.</li>
	<li>Click on 'Configure Data Service' in the option list below.</li>
	<li>Data Service wizard will appear.</li>
</ul>

<h3>Deleting a Data Service</h3>

<ul>
	<li>Log in to  WSO2 WSAS Management Console.</li>
	<li>Go to Manage -> Services</li>
	<li>The page will list all the available services  below 'Add New Service' section.</li>
	<li>Click on remove button on the relevant service.</li>
</ul>

<h3>Sample Data Service configuration</h3>

<p>A sample Data Service configuration XML is shown below.
</p>


    <pre>
    <![CDATA[
<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>
]]>
    </pre>


<h3>Sample output XML</h3>
<p>After deploying this Data Service, 'sales' Web service will have 'getCustomers' and 'getCustomerById' operations.  'getCustomers' operation will return query results as shown below.
</p>
    <pre>
    <![CDATA[
<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>
]]>
    </pre>

<h3></h3>
</body>
</html>
