User Documentation

User Documentation

Under development, english not reviewed, please report errors.

1 Downloading and compiling: 1.1 From binaries; 1.2 From source; 1.3 Installing the JDBC Metadata Activities
2 Using the Driver: 2.1 Driver Class; 2.2 Driver URL; 2.3 GT Security; 2.4 Example
3 Other JDBC and OGSA-DAI resources

1 Downloading and Compiling

1.1 From bianries

You can download the driver binaries to both, Axis 1.4 and GT. Please visit the Downloads Section of our Web Site.

All jars required to run an OGSA-DAI client where packed inside the jars, but we run into some problems where some ClassNotFoundException appeared, one of these errors was seen when using the driver with an Web Application deployed in Tomcat 5.0.x. You can also put the prerequisities in your CLASSPATH, see Section 'C.1.21. What do I need in my CLASSPATH to be able to run OGSA-DAI clients or compile OGSA-DAI client examples?' of the OGSA-DAI documentation.

After downloading put the driver in your classpath, and it is ready to use. Indeed you don't need any other jar to use the driver, but there is some exceptions as mentioned before.

1.2 From source

You can download the sources and compile it to get the jars. Follow the steps bellow:

						$svn co https://ogsadai-jdbc.svn.sourceforge.net/svnroot/ogsadai-jdbc/0.1 ogsadai-jdbc-0.1 

						$cd ogsadai-jdbc-0.1 

						$export JAVA_HOME=/PATH/TO/JDK_1.4 

						$ant

<> We implemented the version 2.0 of the JDBC interface in this version of the driver, which is used by the JVM 1.4. To compile you need to set the $JAVA_HOME enviroment variable to the JDK 1.4. The source will be compiled, and the jars will be created under the './bin' directory.

1.3 Installing the JDBC Metadata Activity

In this version of the driver you will need to install the JDBC Metadata Activity, that was developed for support the driver to get metadata regarding the exposed relational database. To install it download it from our Downloads section.

You will need the OGSA-DAI 3.0 package, download it and unpack it, if you already have it, move to the directory of OGSA-DAI package. Inside the directory of the OGSA-DAI you must create a directory, and move the Activitiy jar.

					$cd /PATH/TO/OGSA-DAI 

					$mkdir jdbc-metadata-activities 

					$mv /path/to/jar/jdbc_metadata_activities.jar ./jdbc-metadata-activities

Note: The activity inside this package have a dependency, you need to download XStream, unpack it and copy the xstream-1.3.jar to the directory you created.

After, you need to run the following commands to deploy the activities in OGSA-DAI:

					$ant -Dgt.dir=$GLOBUS_LOCATION -Ddai.activity.jar.dir=./jdbc-metadata-activities 

       -Ddai.activity.id=br.usp.pcs.lahpc.ogsadai.activities.DatabaseMetaDataMethodActivity
      
 -Ddai.activity.class=br.usp.pcs.lahpc.ogsadai.activities.metadata.DatabaseMetaDataMethodActivity.java

					-Ddai.target.gt=true deployActivity

We are supposing you are using OGSA-DAI deployed into the Globus Toolkit 4 container. To see how to deploy activities in other scenarios, for example, if you are using Tomcat, see Section'16.1.8. Deploying an activity' at the OGSA-DAI 3.0 documentation.

Now you must configure your data resource to use the Activity we just deployed. To do that run the following command:

      $ant -Dgt.dir=$GLOBUS_LOCATION -Ddai.resource.id=my-data-resource-ID -Ddai.activity.id=br.usp.pcs.lahpc.ogsadai.activities.DatabaseMetaDataMethodActivity -Ddai.activity.name=br.usp.pcs.lahpc.ogsadai.activities.metadata.DatabaseMetaDataMethodActivity -Ddai.target.gt=true exposeResourceActivity
    

once more, we are supposing you are using OGSA-DAI deployed in GT4, to see how to do that in other scenarios see Section '16.1.9. Extending the supported activities of a resource' at the OGSA-DAI 3.0 Documentation. At this point, the driver can be used to access the specified resource.

2 Using the Driver

2.1 Driver Class

The Driver class is br.usp.pcs.lahpc.ogsadai.jdbc.Driver. When writing a program that use the driver, before get a connection you should call the following method:

					Class.forName("br.usp.pcs.lahpc.ogsadai.jdbc.Driver");
				

2.2 Driver URL

To get a connection you should inform the driver the URL of the resource, this URL have the following structure, bellow an example:

					Connection ogsadaiCon = DriverManager
					.getConnection("jdbc:ogsadai://example.com/wsrf/services/dai/lbb");
				

Note: the port number, the driver doesn't set a default port number yet, you must allways provide the port number.

The characters before the first two slashs references the protocol to be used, in this case jdbc:ogsadai:gsi, after the protocol we inform the machine that holds the data resource prefixed by two slashs, in our case //example.com. The following lines are the directory in the container where the dai resources were deployed, in our case /wsrf/services/dai/. The last characters, just after the last slash is the id of the relational data resource, in our case lbb

2.3 GT Security

To use GT4 security with the driver, you should have a valid proxy and a valid certificate, if everything is working in your system, run the comand:

					$grid-proxy-init
				

Type the passphrase of the certificate. After that, you must change the URL of the database in your application adding gsi in the protocol at the URL, for example:

					jdbc:ogsadai:gsi://example.com:8443/wsrf/services/dai/lbb
				

Note: the port number, the driver doesn't set a default port number yet, you must allways provide the port number.

2.4 Example

					import java.sql.Connection;

					import java.sql.DriverManager;

					import java.sql.PreparedStatement;

					import java.sql.ResultSet;

					import java.sql.SQLException;

					public class JDBCTest {

					    	public static void main(String[] args) {

					        		try {

								            Class.forName("br.usp.pcs.lahpc.ogsadai.jdbc.Driver");

								            Connection conn = DriverManager

										.getConnection("jdbc:ogsadai:gsi://192.168.10.129:8443/wsrf/services/dai/lbb");

								            PreparedStatement stmt = conn.prepareStatement("SELECT * FROM littleblackbook WHERE id < ?;");

								            stmt.setInt(1, 10);

								            stmt.execute();

								            ResultSet rs =             stmt.getResultSet();

								            while (rs.next()) {

									                System.out.println(rs.getInt("id") + "\t | \t"

										                    	+ rs.getString("name") + "\t | \t"

											                + rs.getString("address") + "\t | \t"

											                    + rs.getString("phone"));

								            }

							        } catch (ClassNotFoundException e) {

            								e.printStackTrace();

						       	} catch (SQLException e) {

								            e.printStackTrace();

							        }

						    }

					}

3 Other JDBC and OGSA-DAI resources

OGSA-DAI 3.0 GT Documentation
OGSA-DAI 3.0 Axis 1.4 Documentation
JDBC 2.0 Documentation
Trail: JDBC(TM) Database Access

Copyright 2008 - Laboratory of Architecture and High Performance computing - LAHPC
Polytechnic School - University of São Paulo