Author: channa Date: Mon Jul 21 03:03:38 2008 New Revision: 19773 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=19773
Log: Added DataServices basic documentation. Added: trunk/mashup/java/xdocs/dataservices.html Added: trunk/mashup/java/xdocs/dataservices.html URL: http://wso2.org/svn/browse/wso2/trunk/mashup/java/xdocs/dataservices.html?pathrev=19773 ============================================================================== --- (empty file) +++ trunk/mashup/java/xdocs/dataservices.html Mon Jul 21 03:03:38 2008 @@ -0,0 +1,197 @@ +<!-- +~ Copyright 2005-2008 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. +--> +<html> +<head> + <meta http-equiv="content-type" content=""> + <title>Data Services</title> + <link href="css/mashup-docs.css" rel="stylesheet" type="text/css" + media="all"> +</head> + +<body> + +<div id="main-content"> +<h1>Data Services</h1> + +<p>This document provides information and instructions on creating data +services on the WSO2 Mashup Server.</p> + +<p>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.</p> + +<h1>Creating a Data Service</h1> +The following instructions show you how to create a RDMBS Data Service using +the wizard in the WSO2 Mashup Server. Please refer sub links on your left +menu to learn how to create other type of data services. +<ul> + <li>Log in to the WSO2 Mashup Server</li> + <li>Go to Management Tasks -> Create a new Data Service</li> + <li>Data Service wizard will appear.</li> +</ul> +Right side of the screen will show a preview of the generated Data Service +configuration XML. + +<h2>Data Service Step 1</h2> + +<h3>Configuration</h3> +Enter Database connection details including driver class, JDBC URL, username +and password. The JDBC driver should be available in the WSAS_HOME/lib +directory. + +<h2>Data Service - Step 2</h2> + +<h3>Queries</h3> +Displays already defined queries + +<h3>SQL Query/Stored Procedure Configuration</h3> +Enter the SQL statement with a unique query ID. Query ID is used to bind the +query with Web service operations. + +<h3>Input Mappings</h3> +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. + +<h3>Result to Output Mapping</h3> +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.<br> +<strong>Output mapping syntax:</strong> + +<p class="Code"><grouping-element-name><br> + <row-name><br> + <element-name-1>column 1 value</element-name-1><br> + <element-name-2>column 2 value</element-name-2><br> + </row-name><br> + <row-name><br> + <element-name-1>column 1 value</element-name-1><br> + <element-name-2>column 2 value</element-name-2><br> + <row-name><br> +</grouping-element-name><br> +</p> +<br> + + +<h2>Data Service - Step 3</h2> + +<h3>Operations</h3> +Displays already defined Web service operation to query mappings + +<h3>Add/Edit Operation</h3> +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. <br> + + +<h1>Modifying a Data Service</h1> +<ul> + <li>Log in to the WSO2 Mashup Server</li> + <li>Select the data service from the list of mashups</li> + <li>Click on 'Edit this mashup (Data Service)'</li> + <li>Data Service wizard will appear.</li> +</ul> + +<h1>Deleting a Data Service</h1> +<ul> + <li>Log in to the WSO2 Mashup Server</li> + <li>Select the data service from the list of mashups</li> + <li>Click on Delete this mashup and confirm deletion.</li> +</ul> + +<h2>Sample Data Service configuration</h2> +A sample Data Service configuration XML is shown below. + +<p class="Code"><data name="sales"><br> + <config><br> + <property +name="org.wso2.ws.dataservice.driver">com.mysql.jdbc.Driver</property><br> + <property +name="org.wso2.ws.dataservice.protocol">jdbc:mysql://server1:3306/sales</property><br> + <property name="org.wso2.ws.dataservice.user">wsas</property><br> + <property +name="org.wso2.ws.dataservice.password">wsas</property><br> + </config><br> + <operation name="getCustomers"><br> + <call-query href="getCustomersQuery"/><br> + </operation><br> + <operation name="getCustomerById"><br> + <call-query href="getCustomerByIdQuery"><br> + <with-param name="customer_id" query-param="customer_id"/><br> + </call-query><br> + </operation><br> + <query id="getCustomersQuery"><br> + <sql>select customer_id, name, city from customers</sql><br> + <result element="customers" rowName="customer"><br> + <element name="customer_id" column="customer_id"/><br> + <element name="name" column="name"/><br> + <element name="city" column="city"/><br> + </result><br> + </query><br> + <query id="getCustomerByIdQuery"><br> + <param name="customer_id" sqlType="INTEGER"/><br> + <sql>select customer_id, name, city from customers where customer_id +=?</sql><br> + <result element="customers" rowName="customer"><br> + <element name="customer_id" column="customer_id"/><br> + <element name="name" column="name"/><br> + <element name="city" column="city"/><br> + </result><br> + </query><br> +</data></p> + +<h2>Sample output XML</h2> +After deploying this Data Service, 'sales' Web service will have +'getCustomers' and 'getCustomerById' operations. 'getCustomers' operation +will return query results as shown below. + +<p class="Code"><customers><br> + <customer><br> + <customer_id>10<customer_id><br> + <name>Peter</name><br> + <city>London</city><br> + </customer><br> + <customer><br> + <customer_id>11<customer_id><br> + <name>Mark</name><br> + <city>New York</city><br> + </customer><br> + <customer><br> + <customer_id>12<customer_id><br> + <name>Jane</name><br> + <city>San Jose</city><br> + </customer><br> +</customers><br> +</p> + +<p>© 2007-2008 WSO2 Inc.</p> +</div> +</body> +</html> _______________________________________________ Mashup-dev mailing list [email protected] http://wso2.org/cgi-bin/mailman/listinfo/mashup-dev
