Getting started with Data Services using WSO2 WSAS-2.0

Data Services is a convenient mechanism to provide a service interface to data stored in a relational database. Parameters for the Web service will be passed to SQL query & you will get custom defined xml response, generated using database data.

Objective
This starter guide will explain how to deploy a simplest form of data service using sample embedded derby database that ships with WSO2WSAS-2.0.
My main intention is to guide you through how to deploy a simple data service without paying attention to too many configuration details. More advance features will be discussed in a future article.

Prerequisites
1. Download WSO2WSAS-2.0 from http://dist.wso2.org/products/wsas/java/2.0/
2. Install it as a standalone server (Install location will be referred to as WSAS_HOME hereafter.)
3. Download & Install Ant (version 1.6.5 or higher) from http://ant.apache.org/
4. Start WSO2WSAS-2.0 (run WSAS_HOME/bin/wso2wsas.bat | wso2wsas.sh)
5. Open a web browser & navigate to https://localhost:9443/
6. Login to WSO2WSAS-2.0 (using Username/password = admin/admin)

Step 1 – Creating & populating sample database

1. In a new command window, go to WSAS_HOME/samples/DataService & type 'ant'.
2. This will produce an output similar to following.

Now you have a sample Derby database created & populated. From next step onwards, we will be using this database to create our Data Service.

Step 2 – Define Data Service Screen

In a web browser, click on 'Services' link (upper left hand corner) & you will be taken to following screen.

Click on 'Define Data Service' link.

Step 3 – Creating a Data Service (Configuring connection)
Fill the screen using values in table below & click 'next' button.

Step 4 – Creating a Data Service (Configuring SQL Query)

Now your here.

Fill first part of this screen with values from following table.

Adding Result-to-output mapping

Enter following values to 'Add/Edit output mapping' section & click 'Store Mapping' button.

Your screen will be updated as follows.

Add another mapping with using following values.

Now the screen should look like this.

And the full screen would look like the following.

Hit 'Store Query' button and the query will be saved. Click on the 'Next' button to continue.

Step 4 – Creating a Data Service (Configuring Operation)

Your screen should now look like following. The drop down in front of 'query' field will list the name of the SQL Query (i.e. allEmployees) that we entered in the previous step.

Fill the 'Operation Name' field with the value 'getAllEmployees' & hit 'Store Operation' button. Your screen should appear like this.

Step 5 – Deploying Data Service
We are about to deploy our simple data service. But please take a moment to check the content inside 'Preview of Data Service Configuration' box. It should be equivalent to following.

<data name="EmployeeServices">
<config>
<property name="org.wso2.ws.dataservice.driver">org.apache.derby.jdbc.EmbeddedDriver</property>
<property name="org.wso2.ws.dataservice.protocol">jdbc:derby:../samples/DataService/database/DATA_SERV_SAMP</property>

<property name="org.wso2.ws.dataservice.user">wsas</property>
<property name="org.wso2.ws.dataservice.password">wsas</property>
</config>

<query id="allEmployees">
<sql>select FIRSTNAME, EMAIL from WS02WSAS.EMPLOYEES</sql>
<result element="Employees" rowName="Employee">
<element name="Name" column="FIRSTNAME" />
<element name="Email" column="EMAIL" />
</result>
</query>
<operation name="getAllEmployees">
<call-query href="allEmployees" />
</operation>
</data>

If your configuration is not matching, chances are that you have made a mistake in one of the above steps. Please start from the beginning. (You can edit the existing configuration. But for brevity of this Starter Guide, I will not go into details of editing. It will be available in next tutorial).

The content here is explained in Data Service Specification [1]. You will find a link to this under references section.

Deploy the Data Service by clicking 'Finish' button.

You will be taken to 'Services' screen & after a while following service will appear on the you screen.

Step 6 – Testing the Deployed Service
Congratulations !!!!. You have deployed a Data service running within WSO2WSAS-2.0. Let's call the service & examine the output.

Since Data Service is similar to any other web service, you can invoke it as same as you invoke other web service. But to make things easy, lets use the 'Try it' feature in WSO2WSAS-2.0 to invoke the service. Carryout following steps and you will invoke the service with zero coding !!!.

Click on the 'Service' link for EmployeeServices.

You will be taken to a screen similar to following.

Copy Http endpoint reference (which is 'http://192.168.2.3:9762/services/EmployeeServices' in my case), append '/getAllEmployees' to end of it.

Finally URL should look like,

http://192.168.2.3:9762/services/EmployeeServices/getAllEmployees

'EmployeeServices' is the service name for our data service & 'getAllEmployees' is the operation we created.

Paste the above on new browser window & press enter. You will get a result window similar to following.

This XML output is generated using data in the database (retrieved against the SQL Query we supplied in a step 4). The element names are in sync with element names we provided under section 'Result-to-output mapping'.

Step 7 : Another way to test the service

Go to Service description page for 'EmployeeServices'. Click on 'Try it' link. (Highlighted in the image bellow)

In the screen the follows, click on 'getAllEmployees' button to invoke the service.

References
1.Data Service Specification (http://wso2.org/wiki/display/wsf/Data+Services+and+Resources)