# Makefile for Java JDBC interface
#
# IDENTIFICATION
-# $Id: Makefile,v 1.19 2000/04/26 14:19:29 momjian Exp $
+# $Id: Makefile,v 1.20 2000/05/03 15:58:08 peter Exp $
#
#-------------------------------------------------------------------------
# postgresql to org/postgresql
PGBASE = org/postgresql
-# In 6.5, the all rule builds the makeVersion class which then calls make using
-# the jdbc1 or jdbc2 rules
+# For 6.5.3 and 7.0+, we need to select the correct JDBC API, so prompt
+# for the version.
all:
@echo ------------------------------------------------------------
@echo Due to problems with some JVMs that dont return a meaningful
# the jar file.
OBJ_COMMON= $(PGBASE)/Connection.class \
$(PGBASE)/Driver.class \
+ $(PGBASE)/DriverClass.class \
$(PGBASE)/Field.class \
$(PGBASE)/PG_Stream.class \
$(PGBASE)/ResultSet.class \
echo "public static String connectClass=\"org.postgresql.jdbc1.Connection\";" ;\
echo "}" \
) >$(PGBASE)/DriverClass.java
+ -$(RM) postgresql.jar
@$(MAKE) jdbc1real
+# This rule does the real work for JDBC1.2, however do not call it directly.
+# This is because the JDBC driver relies on the org.postgresql.DriverClass
+# class to determine the driver version.
jdbc1real: $(PGBASE)/DriverClass.class \
$(OBJ_COMMON) $(OBJ_JDBC1) postgresql.jar msg
echo "public static String connectClass=\"org.postgresql.jdbc2.Connection\";" ;\
echo "}" \
) >$(PGBASE)/DriverClass.java
+ -$(RM) postgresql.jar
@$(MAKE) jdbc2real
+# This rule does the real work for JDBC2, however do not call it directly.
+# This is because the JDBC driver relies on the org.postgresql.DriverClass
+# class to determine the driver version.
jdbc2real: $(PGBASE)/DriverClass.class \
$(OBJ_COMMON) $(OBJ_JDBC2) postgresql.jar msg
# If you have problems with this rule, replace the $( ) with ` ` as some
# shells (mainly sh under Solaris) doesn't recognise $( )
#
-# Note: This works by storing all compiled classes under the $(PGBASE)
-# directory. We use this later for compiling the dual-mode driver.
-#
postgresql.jar: $(OBJ) $(OBJ_COMMON)
$(JAR) -c0f $@ `$(FIND) $(PGBASE) -name "*.class" -print` \
$(wildcard $(PGBASE)/*.properties)
#
$(PGBASE)/Connection.class: $(PGBASE)/Connection.java
$(PGBASE)/DatabaseMetaData.class: $(PGBASE)/DatabaseMetaData.java
-$(PGBASE)/Driver.class: $(PGBASE)/Driver.java
+$(PGBASE)/Driver.class: $(PGBASE)/Driver.java
$(PGBASE)/Field.class: $(PGBASE)/Field.java
$(PGBASE)/PG_Stream.class: $(PGBASE)/PG_Stream.java
$(PGBASE)/PreparedStatement.class: $(PGBASE)/PreparedStatement.java
This is a simple readme describing how to compile and use the jdbc driver.
-This isn't a guide on how to use JDBC - for that refer to Javasoft's web site:
-
- http://www.javasoft.com
+This file was amended on May 2 2000 to document the changes made in the 7.0
+release.
-or the JDBC mailing list:
+---------------------------------------------------------------------------
+This isn't a guide on how to use JDBC - for that refer to Javasoft's web site:
- http://www.blackdown.org
+ http://www.javasoft.com
For problems with this driver, then refer to the postgres-interfaces email
list:
http://www.postgresql.org
-When PostgreSQL V6.4 was released, full documentation for the driver was
-included in the main documentation tree (under the doc directory).
-
-This file was finally amended on December 29 1998 to account for the major
-changes made to the driver since V6.4 was released.
-
---------------------------------------------------------------------------
COMPILING
-To compile the driver, simply use make in the src/interfaces/jdbc directory.
-This will compile the driver, and build a .jar file (Java ARchive).
+There are actually two versions of the driver. One for the JDBC1.2 specification, and one for the JDBC2 specification. To compile the driver, you need to select the correct one.
-REMEMBER: once you have compiled the driver, it will work on ALL platforms
-that support the JDK 1.1 api or later.
+If you have JDK1.1.x you need to type: make jdbc1
-The V6.5 driver introduced support for the JDBC2 specification (which is used
-with JDK 1.2 api and later). This caused us some problems because classes
-written for JDBC1 and JDBC2 are not compatible, so a large chunk of the
-driver had to be re-written to accomodate this.
+If you have JDK1.2 or JDK1.3, you need to type: make jdbc2
-Running make will build a .jar file (postgresql.jar) which contains the driver.
-That jar file will contain the driver for _your_ version of the JDK. That is,
-if you run make using JDK 1.1.7, then you will get the JDBC1 driver. If you
-run using 1.2 then you will get the JDBC2 driver.
+This will compile the driver, and build a .jar file (Java ARchive) called
+postgresql.jar
-Tip: If you want the driver to run on both JDBC1 or JDBC2, first compile under
-JDK 1.1.x, then recompile under JDK 1.2.
+That jar file will contain the driver for _your_ version of the JDK.
-In testing, I've done this using 1.1.6 (running under linux), and running make
-on my Win95 based Laptop (CygWin B20.1 was used to get a GNUMake - and a
-decent shell {bash}).
-
-When the .jar file is built, it includes all the classes under postgresql, and
-the driver automatically selects the correct classes.
+REMEMBER: Once you have compiled the driver, it will work on ALL platforms
+that support that version of the API. You don't need to build it for each
+platform.
That means you don't have to compile it on every platform. Believe me, I
still hear from people who ask me "I've compiled it ok under Solaris, but it
INSTALLING THE DRIVER
-To install the driver, the .class files have to be in the classpath. This can be
-done in two ways:
-
-1: create a directory "postgresql" (and it must be called this) in the current
- directory (or a directory in the class path), and copy all .class files
- into it.
+To install the driver, the .class files have to be in the classpath. To do
+this, copy the postgres.jar file into a directory, and add it to the classpath.
-2: copy the postgres.jar file into a directory, and add it to the classpath.
+ie: under LINUX/SOLARIS (the example here is my linux box):
- ie: under LINUX/SOLARIS (the example here is my linux box):
-
- export CLASSPATH=.:/usr/local/lib/postgresql.jar:/usr/local/jdk1.1.1/lib/classes.zip
-
- note: in java, .zip and .jar files hold collections of classes.
+ export CLASSPATH=.:/usr/local/lib/postgresql.jar
---------------------------------------------------------------------------
introduce the driver using the following snippet of code:
try {
- Class.forName("postgresql.Driver");
+ Class.forName("org.postgresql.Driver");
} catch(Exception e) {
// your error handling code goes here
}
Remember, this method restricts your code to just the postgresql database.
+ However, this is how most people load the driver.
2: Parameters
This method specifies the driver from the command line. When running the
application, you specify the driver using the option:
- -Djdbc.drivers=postgresql.Driver
+ -Djdbc.drivers=org.postgresql.Driver
eg: This is an example of running one of my other projects with the driver:
- java -Djdbc.drivers=postgresql.Driver finder.finder
+ java -Djdbc.drivers=org.postgresql.Driver uk.org.retep.finder.Main
note: This method only works with Applications (not for Applets).
However, the application is not tied to one driver, so if you needed
jdbc:postgresql:database?user=me
jdbc:postgresql:database?user=me&password=mypass
-Previous versions you had to use an auth argument to tell the driver what
-authentication scheme to use when connecting to the database.
-
-However, this is no longer supported because the database tells the driver
-what scheme it's expecting.
-
---------------------------------------------------------------------------
That's the basics related to this driver. You'll need to read the JDBC Docs
-on how to use it.
+on how to use it. However, there are some examples included in the example
+directory. To build, type: make examples
+
+To run them, they follow the same syntax. For example, the basic example shows
+how to insert data, and perform queries:
+
+ java example.basic jdbc:postgresql:test user password
+
+---------------------------------------------------------------------------
POSTGRESQL SPECIFICS
--------------------
+Large Objects:
+
+A "feature" of PostgreSQL is that access to LargeObjects is only permitted
+within a Transaction. Because of this, any use of LargeObjects (also known
+as Blobs) requires that the Connection.setAutoCommit() method be called
+disabling the autocommit feature.
+
+For example:
+
+ Connection db; // open the connection here
+ db.setAutoCommit(false); // Turn off AutoCommit
+
+ ------------------
+
+Large Object API
+
+Most of the time, you can use the getBytes()/setBytes() methods to read and
+write small Large Objects. However, PostgreSQL's own internal api's are
+available. These allow you to access the object as if it was a file.
+
+The first thing you need to do is to open the LargeObjectManager. This class
+handles the opening of existing objects, and creating new ones. To do this,
+you use the following line of code:
+
+ LargeObjectManager lobj;
+ lobj = ((org.postgresql.Connection)db).getLargeObjectAPI();
+
+where db is a reference to an open Connection object.
+
+Once that is done, you can use the API for the lifetime of that Connection.
+
+To create an object, you call the create() method. This takes an argument
+with the file modes you intend to use. The following line is normally
+sufficient:
+
+ int oid = lobj.create(LargeObjectManager.READ|LargeObjectManager.WRITE);
+
+Here, lobj is the LargeObjectManager we have opened earlier, and oid is the
+Large Object's oid in the database.
+
+To open an existing object, you use the open() method. This takes an oid, and
+the file permissions. It then returns a LargeObject object.
+
+ LargeObject obj = lobj.open(oid,LargeObjectManager.WRITE);
+
+Once the LargeObject is open, you can call methods to read, write, seek etc.
+Here's the supported methods:
+
+ int oid = obj.getOID(); Return the objects oid
+ obj.close(); Close the object
+ byte data[] = obj.read(int len); Read len bytes
+ onj.read(byte data[],int off,int len); Read into data[off] len bytes
+ obj.write(byte data[]); Write the array data
+ obj.write(byte data[],int off,int len); Write len bytes from data[off]
+ obj.seek(int pos,int ref); As fseek in C.
+ obj.seek(int pos); Move to pos (from the begining)
+ int pos = obj.tell(); Returns the current position
+ int size = obj.size(); Returns the objects size
+
+Caveat: If you commit(), rollback() a transaction, or turn on autocommit whilst
+an object is open PostgreSQL will close it. You will need to reopen the object
+before using it again. Using the existing LargeObject will cause an
+SQLException to be thrown.
+
+ ------------------
+
Date datatype:
The driver now issues the "show datestyle;" query when it first connects, so
// Clean up the database (in case we failed earlier) then initialise
cleanup();
+ // Because we use LargeObjects, we must use Transactions
+ db.setAutoCommit(false);
+
// Now run tests using JDBC methods, then LargeObjects
doexample();
public void cleanup()
{
try {
- st.executeUpdate("drop table basic");
+ st.executeUpdate("drop table basic1");
+ } catch(Exception ex) {
+ // We ignore any errors here
+ }
+
+ try {
+ st.executeUpdate("drop table basic2");
} catch(Exception ex) {
// We ignore any errors here
}
System.out.println("Thread 1 running...");
// First we need a table to store data in
- st.executeUpdate("create table basic (a int2, b int2)");
+ st.executeUpdate("create table basic1 (a int2, b int2)");
// Now insert some data, using the Statement
- st.executeUpdate("insert into basic values (1,1)");
- st.executeUpdate("insert into basic values (2,1)");
- st.executeUpdate("insert into basic values (3,1)");
+ st.executeUpdate("insert into basic1 values (1,1)");
+ st.executeUpdate("insert into basic1 values (2,1)");
+ st.executeUpdate("insert into basic1 values (3,1)");
// For large inserts, a PreparedStatement is more efficient, because it
// supports the idea of precompiling the SQL statement, and to store
// Also, this is the only way of writing dates in a datestyle independent
// manner. (DateStyles are PostgreSQL's way of handling different methods
// of representing dates in the Date data type.)
- PreparedStatement ps = db.prepareStatement("insert into basic values (?,?)");
+ PreparedStatement ps = db.prepareStatement("insert into basic1 values (?,?)");
for(int i=2;i<200;i++) {
ps.setInt(1,4); // "column a" = 5
ps.setInt(2,i); // "column b" = i
ps.executeUpdate(); // executeUpdate because insert returns no data
+// c.commit();
if((i%50)==0)
DriverManager.println("Thread 1 done "+i+" inserts");
}
// Finally perform a query on the table
DriverManager.println("Thread 1 performing a query");
- ResultSet rs = st.executeQuery("select a, b from basic");
+ ResultSet rs = st.executeQuery("select a, b from basic1");
int cnt=0;
if(rs!=null) {
// Now we run through the result set, printing out the result.
try {
System.out.println("Thread 2 running...");
+ // First we need a table to store data in
+ st.executeUpdate("create table basic2 (a int2, b int2)");
+
// For large inserts, a PreparedStatement is more efficient, because it
// supports the idea of precompiling the SQL statement, and to store
// directly, a Java object into any column. PostgreSQL doesnt support
// Also, this is the only way of writing dates in a datestyle independent
// manner. (DateStyles are PostgreSQL's way of handling different methods
// of representing dates in the Date data type.)
- PreparedStatement ps = db.prepareStatement("insert into basic values (?,?)");
+ PreparedStatement ps = db.prepareStatement("insert into basic2 values (?,?)");
for(int i=2;i<200;i++) {
ps.setInt(1,4); // "column a" = 5
ps.setInt(2,i); // "column b" = i
ps.executeUpdate(); // executeUpdate because insert returns no data
+// c.commit();
if((i%50)==0)
DriverManager.println("Thread 2 done "+i+" inserts");
}
// Finally perform a query on the table
DriverManager.println("Thread 2 performing a query");
- ResultSet rs = st.executeQuery("select * from basic where b>1");
+ ResultSet rs = st.executeQuery("select * from basic2 where b>1");
int cnt=0;
if(rs!=null) {
// First find out the column numbers.
projects / users / rhaas / postgres.git / commitdiff