Adding Datasources

Datasource management capability is provided by the following feature in the WSO2 feature repository:

Name : WSO2 Carbon - Datasource Management Feature
Identifier : org.wso2.carbon.datasource.feature.group

If the datasource management capability is not included in your product by default, you can add it by installing the above feature using the instructions given in section, Feature Management. 
Two types of datasources can be created. For more information, see:

Adding a RDBMS datasource

To add a new RDBMS datasource to a running Carbon instance:

1. Log into the product's Management Console.
2. On the Configure menu, click Datasources.
   The Datasources page will appear.
   Click Add Datasource.
   Select RDBMS as the datasource type.
   This is the default RDBMS datasource configuration provided by WSO2. Users can also write your own RDBMS configuration by selecting the Custom Datasource option. 

   The following fields should be provided when defining the default RDBMS datasource:

   
   
   • Name : Name of the datasource (This value should be unique.)
   • Datasource Provider : For more information, see Datasource Provider.
   • Driver  : The JDBC driver to be used.
   • URL  : The connection URL to be passed to the JDBC driver to establish a connection.
   • Username  : The connection username to be passed to the JDBC driver to establish a connection.
   • Password  : The connection password to be passed to the JDBC driver to establish a connection.
   • Expose as a JNDI Datasource  : For information, see  Exposing Datasources as JNDI Resources.
   • Datasource Configuration Parameters : Additional properties can be defined when creating an RDBMS datasource. For more information on these properties, see Properties of RDBMS Datasources.

   The meaning of many fields are similar to the DBCP configuration guide. For more information, go to http://commons.apache.org/dbcp/configuration.html

3. Click Save.

Datasource Provider

There are two types of datasource providers. You can use the default provider or link an external provider.

• If you need to add a datasource supported by the default datasource provider:
  
  • Select "default" as the Datasource  Provider  option.
  • Enter the connection properties which are namely the Driver, URL, Username and Password.
    
• If you need to add a datasource supported by an external provider class (such as,  com.mysql.jdbc.jdbc2.optional.MysqlXADataSource) : 
  
  • Select "external" as the Datasource Provider  option.
  • Click Add Property and enter the name and value of connection properties. Given below is an example of a datasource of an external datasource provider with entered values.

Adding a custom datasource

To add a new custom datasource to a running Carbon instance:

1. Log into the product's Management Console.
2. On the Configure menu, click Datasource.
   The Datasources page will appear.
3. Click Add Datasources.
4. Select Custom as the datasource type. The following fields should be provided when defining the custom RDBMS datasource:
   
   • Custom Datasource Type : For more information, see Custom Datasource Types.
     
   • Name : Name of the datasource (This value should be unique).
   • Description : Description of the datasource.
   • Configuration : XML configuration of the datasource.
5. Click Save.

Custom Datasource Type

The actual type of the custom datasource can be either DS_CUSTOM_TABULAR or DS_CUSTOM_QUERY. There are two options which cover most of the common business use cases. 

• Custom Tabular Datasources
• Custom Query Datasources

Custom Tabular Datasources

Tabular datasources are used when there is a datasource which represents its data using tables, where a set of named tables contains data rows that can be queried later. You can use the org.wso2.carbon.dataservices.core.custom.datasource.TabularDataBasedDS  interface to implement tabular datasources. For a sample implementation of tabular custom datasource, see  InMemoryDataSource.  

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. For a sample data service descriptor, see InMemoryDSSample. In addition, this is supported in Carbon datasources, with the datasource reader implementation org.wso2.carbon.dataservices.core.custom.datasource.CustomTabularDataSourceReader. For a sample Carbon datasource configuration file, see <PRODUCT_HOME>\repository\conf\datasources\custom-datasources.xml.

Custom Query Datasources

Custom query based datasources are created when there is a datasource that has some form of a query expression support. You can use the org.wso2.carbon.dataservices.core.custom.datasource.CustomQueryBasedDS java interface  to implement query datasources. Any non-tabular datasource can be created 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 using this type of a datasource.  

For a sample implementation of a query based custom datasource, see EchoDataSource. For a sample data service descriptor with custom query datasources, see InMemoryDSSample. This is supported in Carbon datasources, with the datasource reader implementation org.wso2.carbon.dataservices.core.custom.datasource.CustomQueryDataSourceReader. For a sample of a Carbon datasource configuration file, see <PRODUCT_HOME>\repository\conf\datasources\custom-datasources.xml.  

In the init methods of all custom datasources, user supplied properties will be parsed to initialize the datasource accordingly. In addition, a property named __DATASOURCE_ID__ that contains a universally unique identifier (UUID) to uniquely identify the current datasource will be parsed. The custom datasource authors can use the latter to identify the datasources accordingly. For example, datasource instances communicating within a server cluster for data synchronization.

Shown below is an example configuration of a custom datasource of type DS_CUSTOM_TABULAR.

Related Links

Editing and Deleting Datasources