Author: kalpanie Date: Wed Jul 1 02:58:54 2009 New Revision: 40503 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=40503
Log: added images and changed the content as per latest Modified: branches/wsas/java/3.1/product/docs/xdoc/data_service.xml Modified: branches/wsas/java/3.1/product/docs/xdoc/data_service.xml URL: http://wso2.org/svn/browse/wso2/branches/wsas/java/3.1/product/docs/xdoc/data_service.xml?rev=40503&r1=40502&r2=40503&view=diff ============================================================================== --- branches/wsas/java/3.1/product/docs/xdoc/data_service.xml (original) +++ branches/wsas/java/3.1/product/docs/xdoc/data_service.xml Wed Jul 1 02:58:54 2009 @@ -1,219 +1,179 @@ -<!-- - ~ 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://wso2.org/downloads/wsas";>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> +<!-- + ~ 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://wso2.org/downloads/wsas";>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> + +<h4>Data Service Step 1</h4> + +<p>Select 'Add' from the left navigation menu of management console. Data Service Step-1 will be displayed.</p> + +<p><img src="ds/docs/images/datasource.jpg" alt="Data source selection page" /></p> + +<h4>Data Service - Step 2</h4> + +<p>Enter the following values in 'Data Source Type: RDBMS' popup window.</p> +<p>DataBase Type = MySQL</p> +<p>Driver Class = com.mysql.jdbc.Driver</p> +<p>JDBC URL = jdbc:mysql://localhost:3306/employeedb + </p> +<p>User name = root</p> +<ul><li>Click on 'Test Connection' button. You should get 'Database connection is successfull with driver class + com.mysql.jdbc.Driver , jdbc url jdbc:mysql://localhost:3306/employeedb and user name root' message if the + database connection is successful. + </li> +<li>Click 'OK' button. You will see a preview of data service configuration as follows.</li> +</ul> +<p><img src="ds/docs/images/preview-step1.jpg" alt="Preview of data service step 1" /></p> + + +<h4>Data Service - Step 3</h4> + +<ul><li>Next, click on 'Next' button at the Data Service Step-1. Data Service Step-2 will be displayed. Initilally + your service does not include any queries. + </li> +<li>Click on 'New Query' to add a new query to our service. 'Add New Query' pop up window will be displayed. + Enter the following values there. + </li> +</ul> +<p>Query ID = DataQueryEmp</p> +<p> + SQL Statement = select id, name, address from employee + </p> +<p> Grouped by Element = employees</p> +<p>Row name = employee</p> +<p>Row namespace = http://test.org</p> +<ul><li>Now click on 'Add New Output Mapping' button in 'Add New Query' window. 'Add New Output Mapping' window will + be popped up. Add three output mappings as follows + </li> +</ul> +<ol type="1"><li>Mapping Type = Element<p>output field name = id</p> +<p> + SQL Column Name = id + </p> +</li> +<li>Mapping Type = Element<p>output field name = name</p> +<p> + SQL Column Name = name + </p> +</li> +<li>Mapping Type = Attribute<p>output field name = address</p> +<p> + SQL Column Name = address + </p> +</li> +</ol> +<p>We have added one query to our data service configuration. In this example, we do not use an SQL statement + which accepts input parameters. Therefore, we can ignore 'Input Mappings'. + </p> +<p><br /> +<img src="ds/docs/images/configur_query.jpg" alt="Add New Query" /><br /> +<br /> +</p> + +<h4>Data Service - Step 4</h4> + +<ul><li>Click on 'Next' button at the Data Service Step-3. You will be directed to the Data Service Step-4 where you + can add new operations to the data service configuration. + </li> +<li>Click on 'Add New Operation' button.</li> +</ul> + +<p><br /> +<img src="ds/docs/images/add-operations.jpg" alt="Add New Operations" /><br /> +<br /> +</p> + +<p> + Your new data service will be listed in 'Deployed Services' page as follows. + </p> +<p><br /> +<img src="ds/docs/images/services.jpg" alt="Deployed Services" /><br /> +<br /> +</p> +<h2 id="invokeservice">Invoking Data Service</h2><p> + In this section, we'll look at two different ways to invoke our data service without writing single line of + code. First we will invoke our data service using 'Tryit' utility which integrated in to Solution Management console. Then we invoke it using a simple HTTP GET request. + </p> +<ul><li>Click on 'EmployeeDataService' in 'Deployed Services' page. You will be directed to 'Service Management' + page as follows. + </li> +</ul> +<p><br /> +<img src="ds/docs/images/service-mgt.jpg" alt="Service Management" /><br /> +<br /> +</p> +<ul><li>Select 'Try This Service' link. Following page will be displayed.</li> +</ul> +<p><br /> +<img src="ds/docs/images/try-it.jpg" alt="Try it page of EmployeeDataService" /><br /> +<br /> +</p> +<p>Click on 'getAllEmployees' button to invoke our data service. You will get the response message in the same + page. Note that employee id and name will be returned as xml elements and address will be wrapped as an + attribute. This is due to our output mapping configuration at step 2 of the wizard. We have configured id + and name as element mapping types and address as attribute mapping type. You can edit them and observe the + associated changes in response very easily using Tryit. + </p> +<ul><li>Now, we will invoke the same data service using our second approach, HTTP GET request. Copy and paste the + dollowing URL in your browser and hit enter. + </li> +</ul> +<p>http://10.100.1.150:9763/services/EmployeeDataService/getAllEmployees</p> +<p>You will get the same result back as in 'Tryit' approach</p> + +<h3></h3> +</body> +</html> _______________________________________________ Wsas-java-dev mailing list [email protected] https://wso2.org/cgi-bin/mailman/listinfo/wsas-java-dev
