{"id":18965845,"url":"https://github.com/wso2/carbon-datasources","last_synced_at":"2025-04-08T08:11:52.591Z","repository":{"id":4299396,"uuid":"52675136","full_name":"wso2/carbon-datasources","owner":"wso2","description":"Datasource implementation for Hamming Platform","archived":false,"fork":false,"pushed_at":"2025-03-11T11:23:06.000Z","size":2017,"stargazers_count":39,"open_issues_count":0,"forks_count":49,"subscribers_count":255,"default_branch":"master","last_synced_at":"2025-04-01T05:33:56.561Z","etag":null,"topics":["common"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wso2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-27T16:06:21.000Z","updated_at":"2025-03-11T11:23:08.000Z","dependencies_parsed_at":"2024-11-08T14:36:29.232Z","dependency_job_id":"85722a4c-3b00-4a3e-b6ef-3f51579c9234","html_url":"https://github.com/wso2/carbon-datasources","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fcarbon-datasources","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fcarbon-datasources/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fcarbon-datasources/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fcarbon-datasources/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wso2","download_url":"https://codeload.github.com/wso2/carbon-datasources/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247801170,"owners_count":20998339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["common"],"created_at":"2024-11-08T14:33:15.609Z","updated_at":"2025-04-08T08:11:52.565Z","avatar_url":"https://github.com/wso2.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# carbon-datasources\n\n### Introduction\n\nCarbon-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\nare the preferred means of getting a connection. DataSource objects can provide connection pooling which is a must for performance improvement. For carbon-datasources,\n[HikariCP](https://github.com/brettwooldridge/HikariCP) is used as its database connection pooling implementation.\n\nCarbon-datasources is responsible to read the data source configuration files, bind the data sources into JNDI context and make these data sources available\nas an OSGi service in OSGi environment or exposed through Java SPI in non-OSGi environment.\n\n## Features\n\n* Reading the given configuration xml files and create data source object which internally maintain a connection pool\n* Exposing services to fetch and manage data source objects in both OSGi and non-OSGi environment.\n* If specified in the configuration, binding data source objects to the carbon-jndi context.\n\n## Important\n\n* This project has a dependency with [carbon-jndi](https://github.com/wso2/carbon-jndi). Thus in order for this to work carbon-jndi needs to be in place.\n* Place the required jdbc driver jar in the CARBON_HOME/osgi/dropins folder.\n\n## Getting Started\n\n### Using carbon datasources in OSGi environment\n\nA 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;\n\n````YAML\nwso2.datasources:\n  dataSources:\n    -\n      name: WSO2_CARBON_DB\n      description: \"The datasource used for registry and user manager\"\n      jndiConfig:\n          name: jdbc/WSO2CarbonDB\n      definition:\n        type: RDBMS\n        configuration:\n          jdbcUrl: \"jdbc:h2:./target/database/TEST_DB;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000\n          username: wso2carbon\n          password: wso2carbon\n          driverClassName: org.h2.Driver\n          connectionTestQuery: \"SELECT 1\"\n          idleTimeout: 60000\n          isAutoCommit: false\n          maxPoolSize: 10\n          validationTimeout: 30000\n````\n\nThe carbon-datasources bundle picks these configuration and build the data sources.\n\nThe client bundles could retrieve data sources in one of two ways;\n\n* If JNDI configuration is provided in the data source configuration, use [JNDI Context Manager](https://github.com/wso2/carbon-jndi) to fetch data sources.\n* Use OSGi Services provided by the carbon-datasources bundle.\n\n\n1) Fetching a data source object from JNDI Context Manager\n\n````java\npublic class ActivatorComponent {\n\n    @Reference(\n            name = \"org.wso2.carbon.datasource.jndi\",\n            service = JNDIContextManager.class,\n            cardinality = ReferenceCardinality.AT_LEAST_ONE,\n            policy = ReferencePolicy.DYNAMIC,\n            unbind = \"onJNDIUnregister\"\n    )\n    protected void onJNDIReady(JNDIContextManager jndiContextManager) {\n        try {\n            Context ctx = jndiContextManager.newInitialContext();\n            //Cast the object to required DataSource type and perform crud operation.\n            HikariDataSource dsObject = (HikariDataSource)ctx.lookup(\"java:comp/env/jdbc/WSO2CarbonDB\");\n        } catch (NamingException e) {\n            logger.info(\"Error occurred while jndi lookup\", e);\n        }\n    }\n\n    protected void onJNDIUnregister(JNDIContextManager jndiContextManager) {\n        logger.info(\"Unregistering data sources sample\");\n    }\n}\n````\n\nNote that all the data sources are bound under the following context, `java:comp/env/jdbc`.\n\n2) Fetching a data source object from the OSGi Service\n\n````java\npublic class ActivatorComponent {\n\n    @Reference(\n            name = \"org.wso2.carbon.datasource.DataSourceService\",\n            service = DataSourceService.class,\n            cardinality = ReferenceCardinality.AT_LEAST_ONE,\n            policy = ReferencePolicy.DYNAMIC,\n            unbind = \"unregisterDataSourceService\"\n    )\n    protected void onDataSourceServiceReady(DataSourceService dataSourceService) {\n        Connection connection = null;\n        try {\n            HikariDataSource dsObject = (HikariDataSource) dataSourceService.getDataSource(\"WSO2_CARBON_DB\");\n            connection = dsObject.getConnection();\n        } catch (DataSourceException e) {\n            logger.error(\"error occurred while fetching the data source.\", e);\n        } catch (SQLException e) {\n            logger.error(\"error occurred while fetching the connection.\", e);\n        } finally {\n            if (connection != null) {\n                try {\n                    connection.close();\n                } catch (SQLException e) {\n                    logger.error(\"error occurred while closing the connection.\", e);\n                }\n            }\n        }\n    }\n\n    protected void unregisterDataSourceService(DataSourceService dataSourceService) {\n        logger.info(\"Unregistering data sources sample\");\n    }\n}\n````\n\nIn addition to retrieval of data sources, carbon-datasources bundle provides a management service for data source management activities. Following sample code\nsnippet illustrates how to access the management service.\n\n````java\npublic class ActivatorComponent {\n\n    @Reference(\n            name = \"org.wso2.carbon.datasource.DataSourceManagementService\",\n            service = DataSourceManagementService.class,\n            cardinality = ReferenceCardinality.AT_LEAST_ONE,\n            policy = ReferencePolicy.DYNAMIC,\n            unbind = \"unregisterDataSourceManagementService\"\n    )\n    protected void onDataSourceManagementServiceReady(DataSourceManagementService dataSourceManagementService) {\n        logger.info(\"Sample bundle register method fired\");\n        try {\n            DataSourceMetadata metadata = dataSourceManagementService.getDataSource(\"WSO2_CARBON_DB\");\n            logger.info(metadata.getName());\n            //You can perform your functionalities by using the injected service.\n        } catch (DataSourceException e) {\n            logger.error(\"Error occurred while fetching the data sources\", e);\n        }\n    }\n\n    protected void unregisterDataSourceManagementService(DataSourceManagementService dataSourceManagementService) {\n        logger.info(\"Unregistering data sources sample\");\n    }\n}\n````\n\n### Using carbon datasources in non-OSGi environment\n\nThe datasources required for non-OSGi client application can be defined in a configuration YAML file. Refer the sample configuration file as follows;\nJNDI configuration cannot be added to a datasource because JNDI support is not there for non-OSGi applications at the moment.\n\n````YAML\n  # Data Sources Configuration\nwso2.datasources:\n    # datasources\n  dataSources:\n  - name: WSO2_CARBON_DB\n    description: The datasource used for registry and user manager\n    definition:\n        # data source type\n        # THIS IS A MANDATORY FIELD\n      type: RDBMS\n        # data source configuration\n      configuration:\n        jdbcUrl: 'jdbc:h2:./target/database/TEST_DB1;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000'\n        username: wso2carbon\n        password: wso2carbon\n        driverClassName: org.h2.Driver\n        maxPoolSize: 50\n        idleTimeout: 60000\n        connectionTestQuery: SELECT 1\n        validationTimeout: 30000\n        isAutoCommit: false\n````\n\nThe 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.\nThe 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.\n\nThe 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.\n\n````java\n        DataSourceManager dataSourceManager = DataSourceManager.getInstance();\n        Path configFilePath = Paths.get(\"src\", \"main\", \"resources\", \"conf\", \"datasources\");\n        DataSourceService dataSourceService = new DataSourceServiceImpl();\n        DataSourceManagementService dataSourceMgtService = new DataSourceManagementServiceImpl();\n        String analyticsDataSourceName = \"WSO2_ANALYTICS_DB\";\n        \n        try {\n            //Load and initialize the datasources defined in configuration files\n            dataSourceManager.initDataSources(configFilePath.toFile().getAbsolutePath());\n            \n            //Get datsources using DataSourceManagement service\n            logger.info(\"Initial data source count: \" + dataSourceMgtService.getDataSource().size());\n            \n            //Get a particular datasource using its name\n            logger.info(\"Found \" + analyticsDataSourceName + \": \" + (\n                    dataSourceService.getDataSource(analyticsDataSourceName) != null ? true : false));\n            \n            //Delete a datasource using its name\n            dataSourceMgtService.deleteDataSource(analyticsDataSourceName);\n            logger.info(\"Deleted \" + analyticsDataSourceName + \" successfully\");\n            logger.info(\"Data source count after deleting \" + analyticsDataSourceName + \": \" + dataSourceMgtService\n                    .getDataSource().size());\n\n        } catch (DataSourceException e) {\n            logger.error(\"Error occurred while using carbon datasource.\", e);\n        }\n````\n\n\nPlease refer the javadocs of `org.wso2.carbon.datasource.core.api.DataSourceManagementService` for usage.\n\nFor full source code, see [Carbon Datasource sample] (sample).\n\n## Download\n\nUse Maven snippet:\n````xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.wso2.carbon.datasources\u003c/groupId\u003e\n    \u003cartifactId\u003eorg.wso2.carbon.datasource.core\u003c/artifactId\u003e\n    \u003cversion\u003e${carbon.datasource.version}\u003c/version\u003e\n\u003c/dependency\u003e\n````\n\n### Snapshot Releases\n\nUse following Maven repository for snapshot versions of Carbon Datasources.\n\n````xml\n\u003crepository\u003e\n    \u003cid\u003ewso2.snapshots\u003c/id\u003e\n    \u003cname\u003eWSO2 Snapshot Repository\u003c/name\u003e\n    \u003curl\u003ehttp://maven.wso2.org/nexus/content/repositories/snapshots/\u003c/url\u003e\n    \u003csnapshots\u003e\n        \u003cenabled\u003etrue\u003c/enabled\u003e\n        \u003cupdatePolicy\u003edaily\u003c/updatePolicy\u003e\n    \u003c/snapshots\u003e\n    \u003creleases\u003e\n        \u003cenabled\u003efalse\u003c/enabled\u003e\n    \u003c/releases\u003e\n\u003c/repository\u003e\n````\n\n### Released Versions\n\nUse following Maven repository for released stable versions of Carbon Datasources.\n\n````xml\n\u003crepository\u003e\n    \u003cid\u003ewso2.releases\u003c/id\u003e\n    \u003cname\u003eWSO2 Releases Repository\u003c/name\u003e\n    \u003curl\u003ehttp://maven.wso2.org/nexus/content/repositories/releases/\u003c/url\u003e\n    \u003creleases\u003e\n        \u003cenabled\u003etrue\u003c/enabled\u003e\n        \u003cupdatePolicy\u003edaily\u003c/updatePolicy\u003e\n        \u003cchecksumPolicy\u003eignore\u003c/checksumPolicy\u003e\n    \u003c/releases\u003e\n\u003c/repository\u003e\n````\n\n## Building From Source\n\nClone this repository first (`git clone https://github.com/wso2/carbon-datasources`) and use `mvn clean install` to build .\n\n## Contributing to Carbon Datasources Project\n\nPull requests are highly encouraged and we recommend you to create a GitHub issue to discuss the issue or feature that you are contributing to.\n\n## License\n\nCarbon Datasources is available under the Apache 2 License.\n\n## Copyright\n\nCopyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwso2%2Fcarbon-datasources","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwso2%2Fcarbon-datasources","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwso2%2Fcarbon-datasources/lists"}