Documentation: Include information about supported JDBC drivers.
Change-Id: I126222650b49fcd0fb42661abde8fa99100435a6
Signed-off-by: Juergen G. Kissner <juergen.kissner@sap.com>
diff --git a/doc/GettingStarted.txt b/doc/GettingStarted.txt
index 3d3a29a..5ae5f26 100644
--- a/doc/GettingStarted.txt
+++ b/doc/GettingStarted.txt
@@ -4,100 +4,103 @@
Gemini DBAccess provides a way for a database to be accessed through JDBC in a modular environment like OSGi.
-Required Bundles
-----------------
+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
+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
+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.
+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
+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.
+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
+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
+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 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 also a DBAccess bundle that contains the JDBC driver specific parts.
+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:
+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.
+ 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
-
-
-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
+Note: These bundles are shipped with Gemini DBAccess.
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 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 an (Eclipse) IDE, but are using the framework directly then follow the
-documentation of the framework for installing the bundles.
+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
-Some Hints when Working with the Gemeini DBAccess Project
---------------------------------------------------------
+Example
+-------
-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"
+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
\ No newline at end of file
diff --git a/doc/Readme.txt b/doc/Readme.txt
index f81270f..f3a97d4 100644
--- a/doc/Readme.txt
+++ b/doc/Readme.txt
@@ -1,29 +1,41 @@
-Gemini DBAccess 1.1 Milestone M1 - July 26, 2012
+Gemini DBAccess 1.1 Release Candidate 1 - January 9, 2013
-This milestone provides you with database access to the server Derby database version 10.8.2.2
-To access other versions of Derby 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.
+The Gemini DBAccess is about providing modularized access to JDBC resources (OSGi).
+The bundles below exports a DataSourceFactory object so that client applications of the JDBC driver
+can import and access the features of the driver without having to package the driver as part of the application.
-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 following bundles that are included in this distribution:
+DBAccess implements the JDBC Service Specification Version 1.0 of the OSGi Service
+Platform Enterprise Specification, Release 4, Version 4.2, section 125.
+
+This version of DBAccess provides you with the database access to the database platforms listed below.
+(please also visit the wiki for forther information: http://wiki.eclipse.org/Gemini/DBAccess/SupportedDrivers):
Derby:
-org.apache.derby
-osgi.enterprise
-org.eclipse.gemini.dbaccess.derby
-org.eclipse.gemini.dbaccess.util
-org.eclipse.gemini.dbaccess.samples
+osgi.enterprise_<version>.jar
+org.eclipse.gemini.dbaccess.derby_<version>.jar
+org.eclipse.gemini.dbaccess.util_<version>.jar
+org.eclipse.gemini.dbaccess.samples_<version>.jar
+org.apache.derby_<version>.jar (currently 10.8.2.2)
+
+Note: To use versions of Derby other than 10.8.2.2 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.
MySQL:
-osgi.enterprise
-org.eclipse.gemini.dbaccess.mysql
-org.eclipse.gemini.dbaccess.util
-org.eclipse.gemini.dbaccess.samples
+osgi.enterprise_<version>.jar
+org.eclipse.gemini.dbaccess.mysql_<version>.jar
+org.eclipse.gemini.dbaccess.util_<version>.jar
mysql-connector-java-5.1.20-bin.jar (not included, please download here: http://www.mysql.com/downloads/connector/j/)
+HSQLDB:
+osgi.enterprise_<version>.jar
+org.eclipse.gemini.dbaccess.hsqldb_<version>.jar
+org.eclipse.gemini.dbaccess.util_<version>.jar
+hsqldb.jar (not included, please download here: http://sourceforge.net/projects/hsqldb/files/)
-
-
-
+H2:
+osgi.enterprise_<version>.jar
+org.eclipse.gemini.dbaccess.hsqldb_<version>.jar
+org.eclipse.gemini.dbaccess.util_<version>.jar
+h2-<version>.jar (not included, please download here: http://www.h2database.com/html/download.html)
