Skip to content
Datasource implementation for Hamming Platform
Java
Branch: master
Clone or download

README.md

carbon-datasources

Introduction

Carbon-datasources project is the data source implementation for Carbon 5. For any bundle deployed in Carbon 5 and any non-OSGi component , if it requires to access a database, datasources are the preferred means of getting a connection. DataSource objects can provide connection pooling which is a must for performance improvement. For carbon-datasources, HikariCP is used as its database connection pooling implementation.

Carbon-datasources is responsible to read the data source configuration files, bind the data sources into JNDI context and make these data sources available as an OSGi service in OSGi environment or exposed through Java SPI in non-OSGi environment.

Features

  • Reading the given configuration xml files and create data source object which internally maintain a connection pool
  • Exposing services to fetch and manage data source objects in both OSGi and non-OSGi environment.
  • If specified in the configuration, binding data source objects to the carbon-jndi context.

Important

  • This project has a dependency with carbon-jndi. Thus in order for this to work carbon-jndi needs to be in place.
  • Place the required jdbc driver jar in the CARBON_HOME/osgi/dropins folder.

Getting Started

Using carbon datasources in OSGi environment

A client bundle which needs to use data sources should put their database configuration in the profile's deployment.yaml file under CARBON_HOME/conf/PROFILE directory. Refer the sample configuration file as follows for wso2.datsources element configuration;

wso2.datasources:
  dataSources:
    -
      name: WSO2_CARBON_DB
      description: "The datasource used for registry and user manager"
      jndiConfig:
          name: jdbc/WSO2CarbonDB
      definition:
        type: RDBMS
        configuration:
          jdbcUrl: "jdbc:h2:./target/database/TEST_DB;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000
          username: wso2carbon
          password: wso2carbon
          driverClassName: org.h2.Driver
          connectionTestQuery: "SELECT 1"
          idleTimeout: 60000
          isAutoCommit: false
          maxPoolSize: 10
          validationTimeout: 30000

The carbon-datasources bundle picks these configuration and build the data sources.

The client bundles could retrieve data sources in one of two ways;

  • If JNDI configuration is provided in the data source configuration, use JNDI Context Manager to fetch data sources.
  • Use OSGi Services provided by the carbon-datasources bundle.
  1. Fetching a data source object from JNDI Context Manager
public class ActivatorComponent {

    @Reference(
            name = "org.wso2.carbon.datasource.jndi",
            service = JNDIContextManager.class,
            cardinality = ReferenceCardinality.AT_LEAST_ONE,
            policy = ReferencePolicy.DYNAMIC,
            unbind = "onJNDIUnregister"
    )
    protected void onJNDIReady(JNDIContextManager jndiContextManager) {
        try {
            Context ctx = jndiContextManager.newInitialContext();
            //Cast the object to required DataSource type and perform crud operation.
            HikariDataSource dsObject = (HikariDataSource)ctx.lookup("java:comp/env/jdbc/WSO2CarbonDB");
        } catch (NamingException e) {
            logger.info("Error occurred while jndi lookup", e);
        }
    }

    protected void onJNDIUnregister(JNDIContextManager jndiContextManager) {
        logger.info("Unregistering data sources sample");
    }
}

Note that all the data sources are bound under the following context, java:comp/env/jdbc.

  1. Fetching a data source object from the OSGi Service
public class ActivatorComponent {

    @Reference(
            name = "org.wso2.carbon.datasource.DataSourceService",
            service = DataSourceService.class,
            cardinality = ReferenceCardinality.AT_LEAST_ONE,
            policy = ReferencePolicy.DYNAMIC,
            unbind = "unregisterDataSourceService"
    )
    protected void onDataSourceServiceReady(DataSourceService dataSourceService) {
        Connection connection = null;
        try {
            HikariDataSource dsObject = (HikariDataSource) dataSourceService.getDataSource("WSO2_CARBON_DB");
            connection = dsObject.getConnection();
        } catch (DataSourceException e) {
            logger.error("error occurred while fetching the data source.", e);
        } catch (SQLException e) {
            logger.error("error occurred while fetching the connection.", e);
        } finally {
            if (connection != null) {
                try {
                    connection.close();
                } catch (SQLException e) {
                    logger.error("error occurred while closing the connection.", e);
                }
            }
        }
    }

    protected void unregisterDataSourceService(DataSourceService dataSourceService) {
        logger.info("Unregistering data sources sample");
    }
}

In addition to retrieval of data sources, carbon-datasources bundle provides a management service for data source management activities. Following sample code snippet illustrates how to access the management service.

public class ActivatorComponent {

    @Reference(
            name = "org.wso2.carbon.datasource.DataSourceManagementService",
            service = DataSourceManagementService.class,
            cardinality = ReferenceCardinality.AT_LEAST_ONE,
            policy = ReferencePolicy.DYNAMIC,
            unbind = "unregisterDataSourceManagementService"
    )
    protected void onDataSourceManagementServiceReady(DataSourceManagementService dataSourceManagementService) {
        logger.info("Sample bundle register method fired");
        try {
            DataSourceMetadata metadata = dataSourceManagementService.getDataSource("WSO2_CARBON_DB");
            logger.info(metadata.getName());
            //You can perform your functionalities by using the injected service.
        } catch (DataSourceException e) {
            logger.error("Error occurred while fetching the data sources", e);
        }
    }

    protected void unregisterDataSourceManagementService(DataSourceManagementService dataSourceManagementService) {
        logger.info("Unregistering data sources sample");
    }
}

Using carbon datasources in non-OSGi environment

The datasources required for non-OSGi client application can be defined in a configuration YAML file. Refer the sample configuration file as follows; JNDI configuration cannot be added to a datasource because JNDI support is not there for non-OSGi applications at the moment.

  # Data Sources Configuration
wso2.datasources:
    # datasources
  dataSources:
  - name: WSO2_CARBON_DB
    description: The datasource used for registry and user manager
    definition:
        # data source type
        # THIS IS A MANDATORY FIELD
      type: RDBMS
        # data source configuration
      configuration:
        jdbcUrl: 'jdbc:h2:./target/database/TEST_DB1;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000'
        username: wso2carbon
        password: wso2carbon
        driverClassName: org.h2.Driver
        maxPoolSize: 50
        idleTimeout: 60000
        connectionTestQuery: SELECT 1
        validationTimeout: 30000
        isAutoCommit: false

The carbon-datasources bundle picks the YAML configuration and build the data sources. The client application could retrieve datasources using the services provided by the carbon-datasources bundle. The JNDI support to retrieve the carbon datsources in non-OSGi environment will be added soon. The datasources defined in configuration files are initialized by the DataSourceManager. They can be retrieved using DataSourceService using their names. The DataSourceManagementService can be used to perform managerial operations on datasources.

The following is a sample code which loads and initializes the datsources defined in configuration files from configFilePath using DataSourceManager and performs some operation using the services.

        DataSourceManager dataSourceManager = DataSourceManager.getInstance();
        Path configFilePath = Paths.get("src", "main", "resources", "conf", "datasources");
        DataSourceService dataSourceService = new DataSourceServiceImpl();
        DataSourceManagementService dataSourceMgtService = new DataSourceManagementServiceImpl();
        String analyticsDataSourceName = "WSO2_ANALYTICS_DB";
        
        try {
            //Load and initialize the datasources defined in configuration files
            dataSourceManager.initDataSources(configFilePath.toFile().getAbsolutePath());
            
            //Get datsources using DataSourceManagement service
            logger.info("Initial data source count: " + dataSourceMgtService.getDataSource().size());
            
            //Get a particular datasource using its name
            logger.info("Found " + analyticsDataSourceName + ": " + (
                    dataSourceService.getDataSource(analyticsDataSourceName) != null ? true : false));
            
            //Delete a datasource using its name
            dataSourceMgtService.deleteDataSource(analyticsDataSourceName);
            logger.info("Deleted " + analyticsDataSourceName + " successfully");
            logger.info("Data source count after deleting " + analyticsDataSourceName + ": " + dataSourceMgtService
                    .getDataSource().size());

        } catch (DataSourceException e) {
            logger.error("Error occurred while using carbon datasource.", e);
        }

Please refer the javadocs of org.wso2.carbon.datasource.core.api.DataSourceManagementService for usage.

For full source code, see [Carbon Datasource sample] (sample).

Download

Use Maven snippet:

<dependency>
    <groupId>org.wso2.carbon.datasources</groupId>
    <artifactId>org.wso2.carbon.datasource.core</artifactId>
    <version>${carbon.datasource.version}</version>
</dependency>

Snapshot Releases

Use following Maven repository for snapshot versions of Carbon Datasources.

<repository>
    <id>wso2.snapshots</id>
    <name>WSO2 Snapshot Repository</name>
    <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
    <snapshots>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
    </snapshots>
    <releases>
        <enabled>false</enabled>
    </releases>
</repository>

Released Versions

Use following Maven repository for released stable versions of Carbon Datasources.

<repository>
    <id>wso2.releases</id>
    <name>WSO2 Releases Repository</name>
    <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
    <releases>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
        <checksumPolicy>ignore</checksumPolicy>
    </releases>
</repository>

Building From Source

Clone this repository first (git clone https://github.com/wso2/carbon-datasources) and use mvn clean install to build .

Contributing to Carbon Datasources Project

Pull requests are highly encouraged and we recommend you to create a GitHub issue to discuss the issue or feature that you are contributing to.

License

Carbon Datasources is available under the Apache 2 License.

Copyright

Copyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.

You can’t perform that action at this time.