| Getting Started with Gemini DBAccess | |
| ------------------------------------ | |
| Gemini DBAccess provides a way for a database to be accessed through JDBC in a modular environment like OSGi. | |
| If you want to use the DBAccess bundles, please refer to | |
| - http://wiki.eclipse.org/Gemini/DBAccess/GettingStarted | |
| If you want to look at the source code of Gemini DBAccess and compile and run it, please refer to the Committer's guide | |
| - http://wiki.eclipse.org/Gemini/DBAccess/CommitterGuide | |
| The description below a a copy of the wiki page http://wiki.eclipse.org/Gemini/DBAccess/GettingStarted | |
| 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 | |
| Committers Guide: http://wiki.eclipse.org/Gemini/DBAccess/CommitterGuide |