Exposing a Custom Datasource as a Data Service

See the topics given below to expose a custom datasource as a data service. Also, see the samples in Data Integration Samples.

Custom datasources allow you to interface data services with your own datasource implementation. There are two options for writing a custom datasource, and these two options cover most of the common business use cases as follows:

• Custom tabular datasources: Used to represent data in tables, where a set of named tables contain data rows that can be queried later. A tabular datasource is typically associated with an SQL data services query. This is done by internally using our own SQL parser to execute SQL against the custom datasource. You can use the org.wso2.carbon.dataservices.core.custom.datasource.TabularDataBasedDS interface to implement tabular datasources. For a sample implementation of a tabular custom datasource, see org.wso2.carbon.dataservices.core.custom.datasource.InMemoryDataSource. Also, this is supported in Carbon datasources with the following datasource reader implementation: org.wso2.carbon.dataservices.core.custom.datasource.CustomTabularDataSourceReader.

• Custom query datasources: Used when the datasource has some form of query expression support. Custom query datasources are implemented using the org.wso2.carbon.dataservices.core.custom.datasource.CustomQueryBasedDS interface. You can create any non-tabular datasource using the query-based approach. Even if the target datasource does not have a query expression format, you can create your own. For example, you can support any NoSQL type datasource this way. For a sample implementation of a query-based custom datasource, see org.wso2.carbon.dataservices.core.custom.datasource.EchoDataSource. This is supported in Carbon datasources with the following datasource reader implementation: org.wso2.carbon.dataservices.core.custom.datasource.CustomQueryDataSourceReader. 

In the init methods of all custom datasources, user-supplied properties are parsed to initialize the datasource accordingly. Also, a property named __DATASOURCE_ID__, which contains a UUID to uniquely identify the current datasource, is passed.Custom datasource authors use this to identify the datasources accordingly. For example, scenarios like datasource instances communicating within a server cluster for data synchronisation.

Follow the steps given below to create a custom tabular datasource.'

1. Log in to the management console of ESB profile of WSO2 EI using the following URL on your browser:  "https://localhost:9443/carbon/".

2. Click Create under the Data Service menu to open the Create Data Service window.

3. Enter the following data service name.

4. Leave the default values for the other fields.

1. Click Add New Datasource, and enter the following details: 

2. Click Add New Property to enter properties that will identify the data in the datasource.

3. Save the datasource. 

4. Click Next to go to the Queries screen.

1. Click Add New Query to start defining a query. We will write a query to find and display all users in the datasource.

2. Now let's specify output mappings for the data. We will create output mappings for the following data:  ID and Name. 

   1. Start by giving the following information:

   2. Click Add New Output Mapping to start creating the output mapping for the ID field.

   3. Add another output mapping for the Name column.

   4. You will now have the following output mappings listed for the getAllUsers query:

      Open

      

   5. Click Main Configuration to return to the Query screen.

3. Click Next to go to the Operations screen.

To invoke the query, you need to define an operation.

1. Click Add New Operation and enter the following information.

2. Save the operation.

Now, let's create REST resources to invoke the query created above. Alternatively, you can create SOAP operations to invoke the queries. See the previous section for instructions.

1. Click Add New Resource and enter the following information.

2. Save the resource.

You can now invoke the data service query using REST.

Once you have defined the operation, click  Finish to complete the data service creation process. You will now be taken to the  Deployed Services screen, which shows all the data services deployed on the server.

You can try the data service you created by using the TryIt tool that is in your product by default. 

1. Go to the Deployed Services screen.

2. Click the Try this service link for the CustomTabular data service. The TryIt Tool will open with the data service.

3. Select the getAllUsersOp operation.

4. Click Send to see the result:

   <Users xmlns="http://ws.wso2.org/dataservice"> <User> <ID>1</ID> <Name>Will Smith</Name> </User> <User> <ID>2</ID> <Name>Denzel Washington</Name> </User> </Users>

You can send an HTTP GET request to invoke the data service using cURL as shown below.

This will return the response in XML.

Follow the steps given below to create a custom query datasource.

1. Log in to the management console of ESB profile of WSO2 EI using the following URL on your browser:  "https://localhost:9443/carbon/".

2. Click Create under the Data Service menu to open the Create Data Service window.

3. Enter the following data service name.

4. Leave the default values for the other fields.

5. Click Next to go to the Datasources screen.

1. Click Add New Datasource, and enter the values shown below.

2. Click Add New Property to enter properties that will identify the data in the datasource.

   <property name="prop1">prop_value1</property> <property name="prop2">prop_value2</property>

3. Save the datasource. 

4. Click Next to go to the Queries screen.

1. Click Add New Query to open the Add New Query screen and enter the following details.

2. Now let's specify input mappings to enter data. We will create input mappings for the fields given in the expression above:  Column1 and Column2

   1. Click Add New Input Mapping to open the respective screen. Define a mapping for column 1.

   2. Add another input mapping for column 2. You will now have two input mappings for the two columns as shown below.

      Open

      

3. Now let's specify output mappings, which will determine how the result from your query will be presented when the query is invoked. The sample datasource we are using contains the following columns: Column 1 and Column 2. We will create an output mapping for each of these columns. 

   1. Start by entering the following values:

   2. Click Add New Output Mapping to start creating the output mapping for column. Enter a mappings for C1 and C1.

   3. Click Add to save the output mapping. You will now have one output mapping listed for the Q1 query.

   4. Create output mappings for the remaining columns given below.
      

   5. Click Main Configuration to return to the Query screen.

4. Click Next to go to the Operations screen.