Data source 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
A Data Source can be added with InMemory configuration or with JNDI. Follow the instructions below to add a new Data Source to a running Carbon instance.
1. Log on to the product's management console and select "Data Sources."
2. Click on the "Add Data Source" link in the "Data Sources" page.
3. Specify the required options in the "New Data Source" page. Depending on the data source type, the required fields may vary. Discussed below are the two types available.
Default RDBMS
If you select the "Data Source Type" as RDBMS, the following screen will appear.
This is the default RDBMS data source configuration provided by WSO2. Users can also write your own RDBMS configuration by selecting the Custom Data Source option. The following fields should be provided when defining the default RDBMS data source.
- Data Source Type : RDBMS
- Name : Name of the data source (This value should be unique.)
- Data Source Provider : Discussed below.
- Driver : The JDBC driver to be used.
- URL : The connection URL to be passed to the JDBC driver to establish a connection.
- User Name : The connection user name 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 Data Source : Discussed below.
- Data Source Configuration Parameters : Additional properties can be defined when creating an RDBMS data source. For more information on these properties, refer to section Properties of RDBMS Data Sources.
The meaning of many fields is similar to the DBCPconfiguration guide, to which you can refer for more information: http://commons.apache.org/dbcp/configuration.html
4. Once the values are entered, click "Save".
5. You have created a carbon data source. Also refer to edit and delete Data Sources.
Data Source Provider
There are two types of data source providers. You can use the default provider or link an external provider. For the 'default' Data Source Provider, given connection properties Driver, URL, User Name and Password need to be entered as follows:
If you need to add a data source supported by an external provider class such as "com.mysql.jdbc.jdbc2.optional.MysqlXADataSource", select the "external" option and enter the name and value of connection properties by clicking "Add Property". Given below is an example data source of External Data source Provider with entered values.
JNDI Data Source
Java Naming and Directory Interface (JNDI) is a Java application programming interface (API) providing naming and directory functionality for Java software clients to discover and look up data and objects via a name. It helps decouple object creation from the object look-up. When you have registered a data source with JNDI, others can discover it through a JNDI look-up and use it.
To expose a data source as a JNDI data source, select the "Expose as a JNDI Data Source".
Custom Data Source
If you select the "Data Source Type" as Custom, the following screen will appear.
- Data Source Type : Custom
- Custom Data Source Type : The actual type of the custom data source. This can also be RDBMS. More information is given below
- Name : Name of the data source (This value should be unique)
- Description : Description of the data source
- Configuration : XML configuration of the data source
Shown below is an example configuration of a custom data source of type 'DS_CUSTOM'.
4. Once the values are entered, click "Save".
5. You have created a carbon data source. Also refer to edit and delete Data Sources.
Custom Data Source Type
Custom data source support helps interface data services with any data source type available. There are two options in writing a custom data source:
Tabular Data Sources
Tabular data sources are used when there is a data source which represents its data using tables, where a set a named tables contains data rows that can be queried later.
To implement tabular data sources, the interface "org.wso2.carbon.dataservices.core.custom.datasource.TabularDataBasedDS" is used. The "IN_MEMORY_SAMPLE_DS" data source which comes by default with the "Datasource Management" feature is a sample implementation of a tabular data source. It's configuration is as follows:
<configuration xmlns:svns="http://org.wso2.securevault/configuration" xmlns:xml="http://www.w3.org/XML/1998/namespace">
<customDataSourceClass>org.wso2.carbon.dataservices.core.custom.datasource.InMemoryDataSource</customDataSourceClass>
<customDataSourceProps>
<property name="inmemory_datasource_schema">{Vehicles:[ID,Model,Classification,Year]}</property>
<property name="inmemory_datasource_records">
{Vehicles:[["S10_1678","Harley Davidson Ultimate Chopper","Motorcycles","1969"],
["S10_1949","Alpine Renault 1300","Classic Cars","1952"],
["S10_2016","Moto Guzzi1100i","Motorcycles","1996"],
["S10_4698","Harley-Davidson Eagle Drag Bike","Motorcycles","2003"],
["S10_4757","Alfa Romeo GTA","Classic Cars","1972"],
["S10_4962","LanciaA Delta 16V","Classic Cars","1962"],
["S12_1099","Ford Mustang","Classic Cars","1968"],
["S12_1108","Ferrari Enzo","Classic Cars","2001"]]}</property>
</customDataSourceProps>
</configuration>
A tabular data source 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 data source. A sample data service descriptor on how this is done can be found at InMemoryDSSample. Also, this is also supported in Carbon data sources, with the data source reader implementation "org.wso2.carbon.dataservices.core.custom.datasource.CustomTabularDataSourceReader". A sample Carbon data source configuration file can be found at <CARBON_HOME>\repository\conf\datasources\custom-datasources.xml.
Custom Query Data Sources
The custom query based data sources are meant to be created, when you have a data source which has some form of a query expression support. Also, basically any non-tabular data based data source can be created with this type. Even if the target data source do not have query expression format, you can create your own one and use that. So for example, any NoSQL type data source can be supported using this type of a data source. To implement these type of data sources, the interface org.wso2.carbon.dataservices.core.custom.datasource.CustomQueryBasedDS has to be implemented. A sample implementation of this type of a custom data source can be seen at EchoDataSource. A sample data service descriptor with custom query data sources in action can be found at InMemoryDSSample. This is supported in Carbon data sources, with the data source reader implementation org.wso2.carbon.dataservices.core.custom.datasource.CustomQueryDataSourceReader. A sample of a Carbon data source configuration file can be found at custom-datasources.xml.