Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Gemini/DBAccess/GettingStarted
Contents
Getting Started with Gemini DBAccess
Gemini DBAccess provides a way for a database to be accessed through JDBC in a modular environment like OSGi.
Download
The starting point for using DBAccess it the project's download page Download. You can either use a released version, or a development milestone. The packages can be consumed in different ways:
- p2 update site
- maven repository
You can also download the zipped update site and extract the bundles from its plugins directory.
Additionally Required Bundles
To run Gemini DBAccess in OSGi you will need to have the following:
1. OSGi Framework
You may use Plugin Development Environment (PDE) in Eclipse, which will give you access to the Equinox
OSGi framework, or you may execute outside of PDE and use any OSGi framework you choose, such as Felix.
2. Database and JDBC driver
You should have installed and started your database server. DBAccess bundles do not start databases or servers.
It is assumed that such servers are already running. If the driver is not already OSGi-ready then you may need
to create a bundle. If the drivers have been packaged with DBAccess then you will not need additional copies.
Note: The JDBC drivers for the Derby embedded database are shipped with Gemini DBAccess.
3. OSGi Enterprise API bundle
Some of the OSGi Enterprise APIs are used by DBAccess so the osgi.enterprise bundle must be resident. It normally
includes both the source and the class files so it can be used for both execution and debugging. It can be obtained
here: http://www.osgi.org/Download/Release4V42
Note: This bundle is shipped with Gemini DBAccess.
4. The Gemini DBAccess bundles
There are typically three bundles for each supported database. The first bundle is the JDBC driver bundle
and includes the JDBC driver code. If a driver is already OSGi-ready then it should be bundlized
appropriately. If the driver is not already in an appropriate OSGi bundle then DBAccess will either provide
one, or explain how to create one, depending upon whether the driver JARs may be distributed or not.
The second bundle is a DBAccess bundle that contains all of the logic to implement and register the
DataSourceFactory service as specified by the OSGi JDBC specification. It is the same for all supported DB platforms. Its name is org.eclipse.gemini.dbaccess.util.
The third bundle is JDBC driver specific and encapsulates for example the specific Java imports for the DataSources and Drivers.
For example, the following bundles provide support for the Derby client/server database:
- org.apache.derby - the derby JDBC driver jars
- org.eclipse.gemini.dbaccess.util - the bundle common that contains the DBAccess logic
- org.eclipse.gemini.dbaccess.derby - the Gemini supporting classes for Derby
Note: These bundles are shipped with Gemini DBAccess.
Installation
If running in PDE then import the various bundles (the framework will already be there) as plug-ins
into your workspace. The easiest way to do that is presumably by defining a target platform and importing the DBAccess features through its p2 update site.
If you are not using PDE, but are using the framework directly then follow the documentation of the framework for installing the bundles.
Configuration
Gemini DBAccess does not require any special environment configuration
Example
For an example of how to access a database connection from an OSGi program run the sample program. To do this, simply install and start the Derby bundles and the sample bundle (org.eclipse.gemini.dbaccess.samples).
Working with the Gemini DBAccess Project
If you want to look at the source code of Gemini DBAccess and compile and run it, please refer to the Committer Guide
Supported Database Platforms
| JDBC driver | JDBC driver bundle | Compatible driver version | Included | Comment |
|---|---|---|---|---|
| Derby | org.apache.derby_<version>.jar | 10.x | yes | Delivered in version 10.8.2.2 with DBAccess, see 1) |
| MySQL Connector/J | mysql-connector-java-<version>-bin.jar | 5.1.x | no | |
| H2 | h2-<version>.jar | 1.3.x | no | |
| HSQLDB | hsqldb.jar | 2.x | no |
| JDBC driver | JDBC driver bundle | Compatible driver version | Included | Comment |
|---|---|---|---|---|
| Derby | org.apache.derby_<version>.jar | 10.x | yes | Delivered in version 10.5.1 with DBAccess, see 1) |
Comments
- To use versions of Derby other than 10.8.2.2 (or 10.5.1 for DBAccess 1.0) you may need to replace the derby.jar and derbyclient.jar driver jars inside the org.apache.derby bundle with the version that you require.