Exposing an RDBMS as a Data Service

In this tutorial, we will run through the process of service enabling an RDBMS as a data service. 

Step 1: Setting up an RDBMS

Follow the steps given below to set up a MySQL database for this tutorial.

1. Install the MySQL server.
2. Download the JDBC driver for MySQL from here and copy it to your <DSS_HOME>/repository/components/lib directory.
   
3. Create the following database: trainingdb

4. Create the following table:
   

   CREATE TABLE ACCOUNT(AccountID int NOT NULL,Branch varchar(255) NOT NULL, AccountNumber varchar(255),AccountType ENUM('CURRENT', 'SAVINGS') NOT NULL,
   Balance FLOAT,ModifiedDate DATE,PRIMARY KEY (AccountID)); 

5. Enter the following data into the table:
   

   INSERT INTO ACCOUNT VALUES (1,"AOB","A00012","CURRENT",231221,'2014-12-02');

Step 2: Adding an RDBMS datasource

Follow the steps given below.

1. Log in to the management console and select Create under Data Service.

2. In the Create Data Service screen, enter AccountDetailsService as the data service name.

   
   

3. Click Next. When you get to the Add New Data Source screen, select RDBMS as the data source type. The RDBMS-specific options will be available for editing.
   

4. In the Datasource ID field, enter AccountDetails as the datasource name.

5. In the Datasource Type field, select RDBMS and Default from the lists.

   If you enter External instead of the Default datasource type, your datasource should be supported by an external provider class, such as com.mysql.jdbc.jdbc2.optional.MysqlXADataSource. You can select the External option and enter the name and value of connection properties by clicking Add Property. For example,
   
   After an external datasource is created, it can be used as a usual datasource in queries. See the tutorial on handling distributed transactions for more information on using external datasources.

6. Enter MySQL in the Database Engine field.

7. Enter the following driver class for MySQL in the Driver Class URL field: com.mysql.jdbc.Driver.

   Be sure to download the JDBC driver for MySQL from here and copy it to your <DSS_HOME>/repository/components/lib directory.

   If the driver class does not exist in the relevant folders when you create the datasource, you will get an exception such as 'Cannot load JDBC driver class com.mysql.jdbc.Driver'.

   See the section on working with RDBMS datasources, for more options that you can use with your RDBMS data service.

8. Enter the URL to your MySQL database in the URL field:  jdbc:mysql://localhost:3306/trainingdb

9. Enter the username and password to connect to your MySQL database. By default the username is root and the password is blank. 

10. Click Next to start defining a query.

Step 3: Defining a query 

Now let's start writing a query for getting data from the datasource. The query will specify the data that should be fetched and the format that should be used to display data when the query is invoked.

1. Click Add New Query to open the Add New Query screen.
2. Enter the following values:
   
• Query ID: Enter an ID for the query.
• Datasource: Select the datasource for which you are going to write a query. Select the RDBMS datasource that you created previously.
  

• SQL: In this field, enter the SQL statement describing the data that should be retrieved from the RDBMS datasource.
  

  SELECT AccountID,Branch,AccountNumber,AccountType,Balance,ModifiedDate FROM
  ACCOUNT WHERE AccountID=:AccountID

3. Add input mappings: Click Generate Input Mapping to automatically create a mapping for the AccountID field in the database.
   

   Input mappings allow you to add parameters to a query so that you can set the parameter value when executing the query. According to the above definition, you need to provide the account ID as an input in order to retrieve the data corresponding to the account ID.

   Find out more about defining Input Mappings in WSO2 DSS.

4. Add output mappings: Click Generate Response to automatically creating mappings for the fields that should show in the output.
   

   Output mapping is used to specify how the data that is fetched from your query will be shown in the response. Note that, by default, the output type is XML. Find out more about defining Output Mappings in WSO2 DSS. 

5. Click Next to open the Operations screen.

Step 4: Defining an operation to invoke the query

Data service operations are written to invoke queries.

1. Click Add New Operation to open Add New Operation screen.
2. Add a name for your operation in the Operation Name field.
3. In the Query ID field, select the query that you defined previously.
4. Save the operation.