Getting Started with Gemini DBAccess 
------------------------------------

Gemini DBAccess provides a way for a database to be accessed through JDBC in a modular environment like OSGi.


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 most of the logic to implement and register the 
DataSourceFactory service as specified by the OSGi JDBC specification. It is independent of the
specifc JDBC driver.

The third bundle is also a DBAccess bundle that contains the JDBC driver specific parts.

For example, the following bundles provide support for the Derby client/server database: 

1. org.apache.derby - the derby JDBC driver jars
2. org.eclipse.gemini.dbaccess.util - the Gemini supporting classes common to all JDBC drivers
3. org.eclipse.gemini.dbaccess.derby - the Gemini supporting classes for Derby

*** Note: These bundles are shipped with Gemini DBAccess.




Maven Build
-----------

1) Install Maven 3.
2) You may need to configure the proxy settings. In case you are behind a firewall, edit the file 
/mvn_parent/settings.xml and replace the TODOs with the right proxy settings.
3) To execute the build, go into /mvn_parent and run on the command line:
> mvn clean install
or, if you have configured the settings.xml:
> mvn -fae -s settings.xml clean install


Some remarks on what the build does:
- the folder /mvn_parent contains a pom.xml which is the "parent" of all
subprojects. Every bundle which is build has its own pom.xml file
- it builds every bundle (result as usually for maven is under /target in the
respective directory)
- A feature, which currently includes everything except the tests, is also built.
- An update site is generated: /gemini.dbaccess.updatesite . When this is build, you
should find there under /target/site/ a p2 repository containing the feature
and all plugins included into it. 
- currently not all tests are executed
- If you add findbugs:findbugs at the end of the command line, you'll find in the different
/target directories which are produced some information from findbugs. This could be aggregated 
and displayed in late stage by Hudson. To try it, just run:
> mvn clean install findbugs:findbugs
or, if you have configured the settings.xml:
> mvn -fae -s settings.xml clean install findbugs:findbugs


Installation
------------

If you use the Eclipse IDE, the easiest way to consume the bundles is the update site at
http://www.eclipse.org/gemini/dbaccess/download/. Alternatively, if running in the 
Eclipse IDE you can also import the various bundles (the framework will already be there) as plug-ins 
into your workspace. 

If you are not using an (Eclipse) IDE, but are using the framework directly then follow the 
documentation of the framework for installing the bundles.


Some Hints when Working with the Gemeini DBAccess Project 
--------------------------------------------------------

To compile and run the projects in Eclipse, you have to open the gemini.dbaccess.targetdef project, 
open the file gemini.dbaccess.target with the Target Editor and execute "Set as Target Platform"