Page Comparison

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

1. Log on to the product's management console and select "Data Sources."

Image Modified

2. Click on the "Add Data Source" link in the "Data Sources" page.

Image Modified

3. Specify the required options in the "New Data Source" page.

Image Removed

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

Depending on the data source type, the required fields may vary. Discussed below are the two types available.

• RDBMS
• Custom Data Source

RDBMS

Anchor
rdbms rdbms

If you select the "Data Source Type" as RDBMS, the following screen will appear.

Image Added

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 - 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 Pool Implementation - The type of the data source pool implementation. "Pool Type" can be either:
  • BasicDataSource - This data source is an implementation of javax.sql.DataSource that is configured via Java Bean properties.
  • PerUserPoolDataSource - This data source uses individual pools per user. Some properties can be set specifically for a given user if the deployment environment can support initialization of mapped properties. For example, a pool of admin or write-access connections can be guaranteed a certain number of connections that are separate from a maximum set for users with read-only connections.
• Repository Type - The type of the data source repository.
  • InMemory
  • JNDI
• Max Active (int) - The maximum number of active connections that can be allocated from this pool at the same time. If a negative value is specified, there will not be a limit to the number of connections.

• Max Idle (int) -The minimum number of connections that can remain idle in the pool without extra ones being created. It can be zero to create none.

• Initial Size (int) - The initial number of connections that are created when the pool is started.
• Max Open Statements (int) - The maximum number of active connections that can be allocated from this pool at the same time. If a negative value is specified, there will not be a limit to the number of connections.

• Transaction Isolation - For the isolation values, please refer to the javadoc here: http://docs.oracle.com/javase/1.4.2/docs/api/java/sql/Connection.html#field_summary
• Auto Commit - The default auto-commit state of connections created by this pool.
• Pool Statements - Enables prepared statement pooling for this pool.

   

  Image Removed

  Tip The default value is "False."

• Test On Borrow - Indicates whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool and we will attempt to borrow another.

   

  Image Removed

  Tip The default value is "True." For the value "True" to have any effect, the validationQuery parameter must be set to a non-null string.

• Test While Idle - Indicates whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

   

  Image Removed

  Tip The default value is "False." For the value "True" to have any effect, the validationQuery parameter must be set to a non-null string.

• Validation Query - The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query must be an SQL "SELECT" statement that returns at least one row.

For example,

Image Removed

JNDI Data Source

Special options of the JNDI configuration:

• IC Factory - Initial context factory of the JNDI.
• Provider Port - If specified, it will be used to create a JNDI provider URL internally.
• Provider URL - The URL of the JNDI provider. It is assumed that this URL exists and is accessible.

For example,

Image Removed

4. Click on the "Add" button to create the new Data Source.

5. The new Data Source appears in the "Data Sources" list.

Image Removed

• 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

Anchor
pro pro

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:

Image Added

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.

Image Added

JNDI Data Source

Anchor
jndi jndi

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".

Image Added

Custom Data Source 

Anchor
custom custom

If you select the "Data Source Type" as Custom, the following screen will appear.

Image Added

• Data Source Type : Custom 
• Custom Data Source Type : Described 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

Custom Data Source Type 

Anchor
CusDSType CusDSType

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

Custom Tabular Data Sources  

Tabular data sources are used when there is a data source which represents its data using tables, where a set of 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. A sample implementation of tabular custom data source can be found at InMemoryDataSource. 

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 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  

Custom query based data sources are created when there is a data source which has some form of a query expression support.

To implement , the interface "org.wso2.carbon.dataservices.core.custom.datasource.CustomQueryBasedDS" is used. Any non-tabular data source can be created using the query-based approach. Even if the target data source does not have a query expression format, users can create their own and it. For example, any NoSQL type data source can be supported using this type of a data source. 

A sample implementation of a query-based custom data source can be seen at EchoDataSource. A sample data service descriptor with custom query data sources can be found in action in 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 <CARBON_HOME>\repository\conf\datasources\custom-datasources.xml. 

In the "init" methods of all custom data sources, user-supplied properties will be parsed to initialize the data source accordingly. Also, a property named "__DATASOURCE_ID__", which contains a UUID to uniquely identify the current data source, will be passed. This can be used by custom data source authors to identify the data sources accordingly. For example, scenarios like data source instances communicating within a server cluster for data synchronization.

Shown below is an example configuration of a custom data source of type 'DS_CUSTOM_TABULAR'.

Image Added

4. Once the values are entered, click "Save".

5. You have created a carbon data source. Also refer to  edit and delete Data Sources .