JDBC InterfaceAuthor
Originally written by Peter T. Mount (peter@retep.org.uk),
the original author of the JDBC driver.
JDBC is a core API of Java 1.1 and later.
It provides a standard set of
interfaces to SQL-compliant databases.
Postgres provides a type
4 JDBC Driver. Type 4 indicates
that the driver is written in Pure Java, and communicates in the
database system's own network protocol. Because of this, the driver
is platform independent; once compiled, the driver can be used on
any system.
This chapter is not intended as a complete guide to
JDBC programming, but should help to get you
started. For more information refer to the standard
JDBC API documentation.
Also, take a look at the examples included with the source. The
basic example is used here.
Setting up the JDBC DriverGetting the Driver
Precompiled versions of the driver can be downloaded from
the PostgreSQL
JDBC web site.
Alternatively you can build the driver from source. Although you
should only need to do this if you are making changes to the source
code.
Starting with PostgreSQL version 7.1,
the JDBC driver is built using
Ant, a special tool for building
Java-based packages. You should download
Ant from the Ant
web site and install it before proceeding. Precompiled
Ant distributions are typically set up
to read a file .antrc in the current user's
home directory for configuration. For example, to use a different
JDK than the default, this may work:
JAVA_HOME=/usr/local/sun-jdk1.3
JAVACMD=$JAVA_HOME/bin/java
To build the driver, add the option to your
configure command line, e.g.,
$./configure --prefix=xxx --with-java ...
This will build and install the driver along with the rest of the
PostgreSQL package when you issue the
make/gmake and make/gmake install
commands. If you only want to build the driver and not the rest
of PostgreSQL, change into the
directory src/interfaces/jdbc and issue the
respective make/gmake command there. Refer to the
PostgreSQL installation instructions
for more information about the configuration and build process.
When building the driver from source the jar file that is created
will be named postgresql.jar. The build will
create this file in the src/interfaces/jdbc/jars
directory. The resulting driver will be built for the version of
Java you are running. If you build with a 1.1 JDK you will build
a version that supports the jdbc1 specification, if you build with a
Java2 JDK (i.e. JDK1.2 or JDK1.3) you will build a version that
supports the jdbc2 specification.
Do not try to build the driver by calling javac
directly, as the driver uses some dynamic loading techniques for
performance reasons, and javac cannot cope.
Do not try to run ant directly either, because
some configuration information is communicated through the
makefiles. Running ant directly without
providing these parameters will result in a broken driver.
Setting up the Class Path
To use the driver, the jar archive (named
postgresql.jar if you built from source, otherwise
it will likely be named jdbc7.2-1.1.jar or
jdbc7.2-1.2.jar for the jdbc1 and jdbc2 versions
respectively)
needs to be included in the
class path, either by putting it in the CLASSPATH
environment variable, or by using flags on the
java command line. By default, the jar archive
is installed in the directory /usr/local/pgsql/share/java. You may
have it in a different directory if you used the
option when you ran
configure, or if you are using a binary distribution
that places it in some different location.
For instance, I have an application that uses the
JDBC driver to access a large database
containing astronomical objects. I have the application and the
JDBC driver installed in the /usr/local/lib directory, and the
Java JDK installed in
/usr/local/jdk1.3.1. To run the
application, I would use:
export CLASSPATH=/usr/local/lib/finder.jar:/usr/local/pgsql/share/java/postgresql.jar:.
java Finder
finder.jar contains the Finder application.
Loading the driver from within the application is covered in
.
Preparing the Database for JDBC
Because Java only uses TCP/IP connections, the
PostgreSQL server must be configured to
accept TCP/IP connections. This can be done by setting
tcpip_socket = true in the
postgresql.conf file or by supplying the
option flag when starting
postmaster.
Also, the client authentication setup in the
pg_hba.conf file may need to be configured.
Refer to the Administrator's Guide for
details. The JDBC Driver supports trust,
ident, password, md5, and crypt authentication methods.
Using the DriverImporting JDBC
Any source that uses JDBC needs to import the
java.sql package, using:
import java.sql.*;
Do not import the org.postgresql package. If
you do, your source will not compile, as
javac will get confused.
Loading the Driver
Before you can connect to a database, you need to load the
driver. There are two methods available, and it depends on your
code which is the best one to use.
In the first method, your code implicitly loads the driver using the
Class.forName() method.
For Postgres, you would use:
Class.forName("org.postgresql.Driver");
This will load the driver, and while loading, the driver will automatically
register itself with JDBC.
The forName() method can throw a
ClassNotFoundException if the driver is
not available.
This is the most common method to use, but restricts your code to
use just Postgres. If your code may
access another database system in the future, and you do not use
any Postgres-specific extensions, then
the second method is advisable.
The second method passes the driver as a parameter to the
JVM as it starts, using the
argument. Example:
java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer
In this example, the JVM will attempt to load
the driver as part of its initialization. Once done, the
ImageViewer is started.
Now, this method is the better one to use because it allows your
code to be used with other database packages without recompiling
the code. The only thing that would also change is the connection
URL, which is covered next.
One last thing: When your code then tries to open a
Connection, and you get a No
driver availableSQLException
being thrown, this is probably caused by the driver not being in
the class path, or the value in the parameter not being correct.
Connecting to the Database
With JDBC, a database is represented by a
URL (Uniform Resource Locator). With
Postgres, this takes one of the
following forms:
jdbc:postgresql:database
jdbc:postgresql://host/database
jdbc:postgresql://host:port/database
where:
host
The host name of the server. Defaults to localhost.
port
The port number the server is listening on. Defaults to the
Postgres standard port number (5432).
database
The database name.
To connect, you need to get a Connection instance from
JDBC. To do this,
you would use the DriverManager.getConnection() method:
Connection db = DriverManager.getConnection(url, username, password);
Closing the Connection
To close the database connection, simply call the
close() method to the Connection:
db.close();
Issuing a Query and Processing the Result
Any time you want to issue SQL statements to
the database, you require a Statement
instance. Once you have a Statement, you
can use the executeQuery() method to issue a
query. This will return a ResultSet
instance, which contains the entire result. illustrates this process.
Processing a Simple Query in JDCB
This example with issue a simple query and print out the first
column of each row.
Statement st = db.createStatement();
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
while(rs.next()) {
System.out.print("Column 1 returned ");
System.out.println(rs.getString(1));
}
rs.close();
st.close();
Using the Statement Interface
The following must be considered when using the
Statement interface:
You can use a single Statement instance
as many times as you want. You could create one as soon as you
open the connection and use it for the connection's
lifetime. But you have to remember that only one
ResultSet can exist per
Statement.
If you need to perform a query while processing a
ResultSet, you can simply create and
use another Statement.
If you are using threads, and several are using the database,
you must use a separate Statement for
each thread. Refer to if you are
thinking of using threads, as it covers some important points.
Using the ResultSet Interface
The following must be considered when using the
ResultSet interface:
Before reading any values, you must call
next(). This returns true if there is a
result, but more importantly, it prepares the row for
processing.
Under the JDBC specification, you should
access a field only once. It is safest to stick to this rule,
although at the current time, the
Postgres driver will allow you to
access a field as many times as you want.
You must close a ResultSet by calling
close() once you have finished using it.
Once you make another query with the
Statement used to create a
ResultSet, the currently open
ResultSet instance is closed
automatically.
Performing Updates
To perform an update (or any other SQL
statement that does not return a result), you simply use the
executeUpdate() method:
st.executeUpdate("CREATE TABLE basic (a int, b int)");
Using Large Objects
In Postgres, Large
Objects (also known as BLOBs) are
used to hold data in the database that cannot be stored in a normal
SQL table. They are stored in a separate table in a special format,
and are referred to from your own tables by an OID value.
For Postgres, you must access Large
Objects within an SQL transaction. You would
open a transaction by using the
setAutoCommit() method with an input
parameter of false:
Connection mycon;
...
mycon.setAutoCommit(false);
... // now use Large Objects
There are two methods of using Large Objects. The first is the
standard JDBC way, and is documented here. The
other, uses PostgreSQL extensions to
the API, which presents the libpq large object
API to Java, providing even better access to
large objects than the standard. Internally, the driver uses the
extension to provide large object support.
In JDBC, the standard way to access Large
Objects is using the getBinaryStream() method
in ResultSet, and
setBinaryStream() method in
PreparedStatement. These methods make the
large object appear as a Java stream, allowing you to use the
java.io package, and others, to manipulate the
object. illustrates the usage of
this approach.
Using the JDBC Large Object Interface
For example, suppose you have a table containing the file name of
an image and you have a large object containing that image:
CREATE TABLE images (imgname text, imgoid oid);
To insert an image, you would use:
File file = new File("myimage.gif");
FileInputStream fis = new FileInputStream(file);
PreparedStatement ps = conn.prepareStatement("INSERT INTO images VALUES (?, ?)");
ps.setString(1, file.getName());
ps.setBinaryStream(2, fis, file.length());
ps.executeUpdate();
ps.close();
fis.close();
The question marks must appear literally. The actual data is
substituted by the next lines.
Here, setBinaryStream transfers a set number
of bytes from a stream into a Large Object, and stores the OID
into the field holding a reference to it. Notice that the
creation of the Large Object itself in the database happens
transparently.
Retrieving an image is even easier. (We use
PreparedStatement here, but the
Statement class can equally be used.)
PreparedStatement ps = con.prepareStatement("SELECT imgoid FROM images WHERE imgname=?");
ps.setString(1, "myimage.gif");
ResultSet rs = ps.executeQuery();
if (rs != null) {
while(rs.next()) {
InputStream is = rs.getBinaryStream(1);
// use the stream in some way here
is.close();
}
rs.close();
}
ps.close();
Here you can see how the Large Object is retrieved as an
InputStream. You will also notice that we
close the stream before processing the next row in the
result. This is part of the JDBC specification,
which states that any InputStream returned
is closed when ResultSet.next() or
ResultSet.close() is called.
PostgreSQL Extensions to the
JDBC APIPostgres is an extensible database
system. You can add your own functions to the backend, which can
then be called from queries, or even add your own data types. As
these are facilities unique to Postgres,
we support them from Java, with a set of extension
API's. Some features within the core of the
standard driver actually use these extensions to implement Large
Objects, etc.
Accessing the Extensions
To access some of the extensions, you need to use some extra
methods in the org.postgresql.Connection
class. In this case, you would need to case the return value of
Driver.getConnection(). For example:
Connection db = Driver.getConnection(url, username, password);
// ...
// later on
Fastpath fp = ((org.postgresql.Connection)db).getFastpathAPI();
Class org.postgresql.Connection
public class Connection extends Object implements Connection
java.lang.Object
|
+----org.postgresql.Connection
These are the extra methods used to gain access to
PostgreSQL's extensions. Methods
defined by java.sql.Connection are not
listed.
Methods
public Fastpath getFastpathAPI() throws SQLException
This returns the Fastpath API for the
current connection. It is primarily used by the Large Object
API.
The best way to use this is as follows:
import org.postgresql.fastpath.*;
...
Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI();
where myconn> is an open Connection> to PostgreSQL.
Returns:
Fastpath object allowing access to functions on the
PostgreSQL backend.
Throws:
SQLException by Fastpath when initializing for first time
public LargeObjectManager getLargeObjectAPI() throws SQLException
This returns the Large Object API for the
current connection.
The best way to use this is as follows:
import org.postgresql.largeobject.*;
...
LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
where myconn> is an open Connection> to
PostgreSQL.
Returns:LargeObject object that implements the API
Throws:SQLException by LargeObject when initializing for first time
public void addDataType(String type, String name)
This allows client code to add a handler for one of
PostgreSQL's more unique data types. Normally, a data type not
known by the driver is returned by ResultSet.getObject() as a
PGobject> instance. This method allows you to write a class
that extends PGobject>, and tell the driver the type name, and
class name to use. The down side to this, is that you must
call this method each time a connection is made.
The best way to use this is as follows:
...
((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name");
...
where myconn is an open Connection> to
PostgreSQL. The handling class must
extend org.postgresql.util.PGobject.
Class org.postgresql.Fastpath
public class Fastpath extends Object
java.lang.Object
|
+----org.postgresql.fastpath.Fastpath
Fastpath is an API that
exists within the libpq C interface, and allows a client machine
to execute a function on the database backend. Most client code
will not need to use this method, but it is provided because the
Large Object API uses it.
To use, you need to import the
org.postgresql.fastpath package, using the
line:
import org.postgresql.fastpath.*;
Then, in your code, you need to get a
FastPath object:
Fastpath fp = ((org.postgresql.Connection)conn).getFastpathAPI();
This will return an instance associated with the database
connection that you can use to issue commands. The casing of
Connection to
org.postgresql.Connection is required, as
the getFastpathAPI() is an extension method,
not part of JDBC. Once you have a
Fastpath instance, you can use the
fastpath() methods to execute a backend
function.
See Also:FastpathFastpathArg, LargeObjectMethods
public Object fastpath(int fnid,
boolean resulttype,
FastpathArg args[]) throws SQLException
Send a function call to the PostgreSQL backend.
Parameters:fnid> - Function id
resulttype> - True if the result is an integer, false
for
other results
args> - FastpathArguments to pass to fastpath
Returns:
null if no data, Integer if an integer result, or byte[]
otherwise
public Object fastpath(String name,
boolean resulttype,
FastpathArg args[]) throws SQLException
Send a function call to the PostgreSQL backend by name.
The mapping for the procedure name to function id needs to
exist, usually to an earlier call to addfunction(). This is
the preferred method to call, as function id's can/may change
between versions of the backend. For an example of how this
works, refer to org.postgresql.LargeObject
Parameters:name> - Function name
resulttype> - True if the result is an integer, false
for
other results
args> - FastpathArguments to pass to fastpath
Returns:
null if no data, Integer if an integer result, or byte[]
otherwise
See Also:LargeObject
public int getInteger(String name,
FastpathArg args[]) throws SQLException
This convenience method assumes that the return value is an Integer
Parameters:name - Function name
args - Function arguments
Returns:integer resultThrows:SQLException if a database-access error occurs or no result
public byte[] getData(String name,
FastpathArg args[]) throws SQLException
This convenience method assumes that the return value is binary
data.
Parameters:name - Function name
args - Function arguments
Returns:byte[] array containing resultThrows:SQLException if a database-access error occurs or no result
public void addFunction(String name,
int fnid)
This adds a function to our look-up table. User code should
use the addFunctions method, which is based upon a query,
rather than hard coding the oid. The oid for a function is not
guaranteed to remain static, even on different servers of the
same version.
public void addFunctions(ResultSet rs) throws SQLException
This takes a ResultSet containing two columns. Column 1
contains the function name, Column 2 the oid. It reads the
entire ResultSet, loading the values into the function table.
Remember to close() the
ResultSet after calling this!
Implementation note about function name look-ups
PostgreSQL stores the function id's and their corresponding
names in the pg_proc> table. To speed things up locally,
instead of querying each function from that table when
required, a Hashtable is used. Also, only the function's
required are entered into this table, keeping connection
times as fast as possible.
The org.postgresql.LargeObject class
performs a query upon its start-up, and passes the returned
ResultSet to the
addFunctions() method here. Once this
has been done, the Large Object API refers
to the functions by name.
Do not think that manually converting them to the oid's will
work. OK, they will for now, but they can change during
development (there was some discussion about this for V7.0),
so this is implemented to prevent any unwarranted headaches
in the future.
See Also:LargeObjectManager
public int getID(String name) throws SQLException
This returns the function id associated by its name If
addFunction() or addFunctions() have not been called for this
name, then an SQLException is thrown.
Class org.postgresql.fastpath.FastpathArg
public class FastpathArg extends Object
java.lang.Object
|
+----org.postgresql.fastpath.FastpathArg
Each fastpath call requires an array of arguments, the number and
type dependent on the function being called. This class
implements methods needed to provide this capability.
For an example on how to use this, refer to the
org.postgresql.LargeObject package.
See Also:Fastpath, LargeObjectManager, LargeObjectConstructors
public FastpathArg(int value)
Constructs an argument that consists of an integer value
Parameters:
value - int value to set
public FastpathArg(byte bytes[])
Constructs an argument that consists of an array of bytes
Parameters:
bytes - array to store
public FastpathArg(byte buf[],
int off,
int len)
Constructs an argument that consists of part of a byte array
Parameters:buf>source arrayoffoffset within arraylenlength of data to include
public FastpathArg(String s)
Constructs an argument that consists of a String.
Geometric Data TypesPostgreSQL has a set of data types that
can store geometric features into a table. These include single
points, lines, and polygons. We support these types in Java with
the org.postgresql.geometric package. It contains classes that
extend the org.postgresql.util.PGobject class. Refer to that
class for details on how to implement your own data type handlers.
Class org.postgresql.geometric.PGbox
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.geometric.PGbox
public class PGbox extends PGobject implements Serializable,
Cloneable
This represents the box data type within PostgreSQL.
Variables
public PGpoint point[]
These are the two corner points of the box.
Constructors
public PGbox(double x1,
double y1,
double x2,
double y2)
Parameters:
x1 - first x coordinate
y1 - first y coordinate
x2 - second x coordinate
y2 - second y coordinate
public PGbox(PGpoint p1,
PGpoint p2)
Parameters:
p1 - first point
p2 - second point
public PGbox(String s) throws SQLException
Parameters:
s - Box definition in PostgreSQL syntax
Throws: SQLException
if definition is invalid
public PGbox()
Required constructor
Methods
public void setValue(String value) throws SQLException
This method sets the value of this object. It should be
overridden, but still called by subclasses.
Parameters:
value - a string representation of the value of the
object
Throws: SQLException
thrown if value is invalid for this type
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two boxes are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
Returns:
the PGbox in the syntax expected by PostgreSQL
Overrides:
getValue in class PGobject
Class org.postgresql.geometric.PGcircle
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.geometric.PGcircle
public class PGcircle extends PGobject implements Serializable,
Cloneable
This represents PostgreSQL's circle data type, consisting of a point
and a radius
Variables
public PGpoint center
This is the center point
double radius
This is the radius
Constructors
public PGcircle(double x,
double y,
double r)
Parameters:
x - coordinate of center
y - coordinate of center
r - radius of circle
public PGcircle(PGpoint c,
double r)
Parameters:
c - PGpoint describing the circle's center
r - radius of circle
public PGcircle(String s) throws SQLException
Parameters:
s - definition of the circle in PostgreSQL's syntax.
Throws: SQLException
on conversion failure
public PGcircle()
This constructor is used by the driver.
Methods
public void setValue(String s) throws SQLException
Parameters:
s - definition of the circle in PostgreSQL's syntax.
Throws: SQLException
on conversion failure
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two circles are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
Returns:
the PGcircle in the syntax expected by PostgreSQL
Overrides:
getValue in class PGobject
Class org.postgresql.geometric.PGline
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.geometric.PGline
public class PGline extends PGobject implements Serializable,
Cloneable
This implements a line consisting of two points. Currently line is
not yet implemented in the backend, but this class ensures that when
it's done were ready for it.
Variables
public PGpoint point[]
These are the two points.
Constructors
public PGline(double x1,
double y1,
double x2,
double y2)
Parameters:
x1 - coordinate for first point
y1 - coordinate for first point
x2 - coordinate for second point
y2 - coordinate for second point
public PGline(PGpoint p1,
PGpoint p2)
Parameters:
p1 - first point
p2 - second point
public PGline(String s) throws SQLException
Parameters:
s - definition of the line in PostgreSQL's syntax.
Throws: SQLException
on conversion failure
public PGline()
required by the driver
Methods
public void setValue(String s) throws SQLException
Parameters:
s - Definition of the line segment in PostgreSQL's
syntax
Throws: SQLException
on conversion failure
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two lines are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
Returns:
the PGline in the syntax expected by PostgreSQL
Overrides:
getValue in class PGobject
Class org.postgresql.geometric.PGlseg
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.geometric.PGlseg
public class PGlseg extends PGobject implements Serializable,
Cloneable
This implements a lseg (line segment) consisting of two points
Variables
public PGpoint point[]
These are the two points.
Constructors
public PGlseg(double x1,
double y1,
double x2,
double y2)
Parameters:
x1 - coordinate for first point
y1 - coordinate for first point
x2 - coordinate for second point
y2 - coordinate for second point
public PGlseg(PGpoint p1,
PGpoint p2)
Parameters:
p1 - first point
p2 - second point
public PGlseg(String s) throws SQLException
Parameters:
s - Definition of the line segment in PostgreSQL's syntax.
Throws: SQLException
on conversion failure
public PGlseg()
required by the driver
Methods
public void setValue(String s) throws SQLException
Parameters:
s - Definition of the line segment in PostgreSQL's
syntax
Throws: SQLException
on conversion failure
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two line segments are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
Returns:
the PGlseg in the syntax expected by PostgreSQL
Overrides:
getValue in class PGobject
Class org.postgresql.geometric.PGpath
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.geometric.PGpath
public class PGpath extends PGobject implements Serializable,
Cloneable
This implements a path (a multiply segmented line, which may be
closed)
Variables
public boolean open
True if the path is open, false if closed
public PGpoint points[]
The points defining this path
Constructors
public PGpath(PGpoint points[],
boolean open)
Parameters:
points - the PGpoints that define the path
open - True if the path is open, false if closed
public PGpath()
Required by the driver
public PGpath(String s) throws SQLException
Parameters:
s - definition of the path in PostgreSQL's syntax.
Throws: SQLException
on conversion failure
Methods
public void setValue(String s) throws SQLException
Parameters:
s - Definition of the path in PostgreSQL's syntax
Throws: SQLException
on conversion failure
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two pathes are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
This returns the path in the syntax expected by
PostgreSQL
Overrides:
getValue in class PGobject
public boolean isOpen()
This returns true if the path is open
public boolean isClosed()
This returns true if the path is closed
public void closePath()
Marks the path as closed
public void openPath()
Marks the path as open
Class org.postgresql.geometric.PGpoint
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.geometric.PGpoint
public class PGpoint extends PGobject implements Serializable,
Cloneable
This implements a version of java.awt.Point, except it uses double
to represent the coordinates.
It maps to the point data type in PostgreSQL.
Variables
public double x
The X coordinate of the point
public double y
The Y coordinate of the point
Constructors
public PGpoint(double x,
double y)
Parameters:
x - coordinate
y - coordinate
public PGpoint(String value) throws SQLException
This is called mainly from the other geometric types, when a
point is embedded within their definition.
Parameters:
value - Definition of this point in PostgreSQL's
syntax
public PGpoint()
Required by the driver
Methods
public void setValue(String s) throws SQLException
Parameters:
s - Definition of this point in PostgreSQL's syntax
Throws: SQLException
on conversion failure
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two points are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
Returns:
the PGpoint in the syntax expected by PostgreSQL
Overrides:
getValue in class PGobject
public void translate(int x,
int y)
Translate the point with the supplied amount.
Parameters:
x - integer amount to add on the x axis
y - integer amount to add on the y axis
public void translate(double x,
double y)
Translate the point with the supplied amount.
Parameters:
x - double amount to add on the x axis
y - double amount to add on the y axis
public void move(int x,
int y)
Moves the point to the supplied coordinates.
Parameters:
x - integer coordinate
y - integer coordinate
public void move(double x,
double y)
Moves the point to the supplied coordinates.
Parameters:
x - double coordinate
y - double coordinate
public void setLocation(int x,
int y)
Moves the point to the supplied coordinates. refer to
java.awt.Point for description of this
Parameters:
x - integer coordinate
y - integer coordinate
See Also:
Point
public void setLocation(Point p)
Moves the point to the supplied java.awt.Point refer to
java.awt.Point for description of this
Parameters:
p - Point to move to
See Also:
Point
Class org.postgresql.geometric.PGpolygon
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.geometric.PGpolygon
public class PGpolygon extends PGobject implements Serializable,
Cloneable
This implements the polygon data type within PostgreSQL.
Variables
public PGpoint points[]
The points defining the polygon
Constructors
public PGpolygon(PGpoint points[])
Creates a polygon using an array of PGpoints
Parameters:
points - the points defining the polygon
public PGpolygon(String s) throws SQLException
Parameters:
s - definition of the polygon in PostgreSQL's syntax.
Throws: SQLException
on conversion failure
public PGpolygon()
Required by the driver
Methods
public void setValue(String s) throws SQLException
Parameters:
s - Definition of the polygon in PostgreSQL's syntax
Throws: SQLException
on conversion failure
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two polygons are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
Returns:
the PGpolygon in the syntax expected by PostgreSQL
Overrides:
getValue in class PGobject
Large Objects
Large objects are supported in the standard
JDBC specification. However, that interface is
limited, and the API provided by PostgreSQL allows for random
access to the objects contents, as if it was a local file.
The org.postgresql.largeobject package provides to Java the libpq
C interface's large object API. It consists of
two classes, LargeObjectManager, which deals with creating,
opening and deleting large objects, and LargeObject which deals
with an individual object.
Class org.postgresql.largeobject.LargeObject
public class LargeObject extends Object
java.lang.Object
|
+----org.postgresql.largeobject.LargeObject
This class implements the large object interface to
PostgreSQL.
It provides the basic methods required to run the interface, plus
a pair of methods that provide InputStream and OutputStream
classes for this object.
Normally, client code would use the getAsciiStream,
getBinaryStream, or getUnicodeStream methods in ResultSet, or
setAsciiStream, setBinaryStream, or setUnicodeStream methods in
PreparedStatement to access Large Objects.
However, sometimes lower level access to Large Objects are
required, that are not supported by the JDBC
specification.
Refer to org.postgresql.largeobject.LargeObjectManager on how to
gain access to a Large Object, or how to create one.
See Also:LargeObjectManagerVariablespublic static final int SEEK_SETIndicates a seek from the beginning of a filepublic static final int SEEK_CURIndicates a seek from the current positionpublic static final int SEEK_ENDIndicates a seek from the end of a fileMethods
public int getOID()
Returns the OID of this LargeObject
public void close() throws SQLException
This method closes the object. You must not call methods in
this object after this is called.
public byte[] read(int len) throws SQLException
Reads some data from the object, and return as a byte[] array
public int read(byte buf[],
int off,
int len) throws SQLException
Reads some data from the object into an existing array
Parameters:bufdestination arrayoffoffset within arraylennumber of bytes to read
public void write(byte buf[]) throws SQLException
Writes an array to the object
public void write(byte buf[],
int off,
int len) throws SQLException
Writes some data from an array to the object
Parameters:bufdestination arrayoffoffset within arraylennumber of bytes to writeClass org.postgresql.largeobject.LargeObjectManager
public class LargeObjectManager extends Object
java.lang.Object
|
+----org.postgresql.largeobject.LargeObjectManager
This class implements the large object interface to
PostgreSQL. It provides methods that
allow client code to create, open and delete large objects from
the database. When opening an object, an instance of
org.postgresql.largeobject.LargeObject is
returned, and its methods then allow access to the object.
This class can only be created by org.postgresql.Connection. To
get access to this class, use the following segment of code:
import org.postgresql.largeobject.*;
Connection conn;
LargeObjectManager lobj;
// ... code that opens a connection ...
lobj = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
Normally, client code would use the getAsciiStream,
getBinaryStream, or getUnicodeStream methods in ResultSet, or
setAsciiStream, setBinaryStream, or setUnicodeStream methods in
PreparedStatement to access Large Objects. However, sometimes
lower level access to Large Objects are required, that are not
supported by the JDBC specification.
Refer to org.postgresql.largeobject.LargeObject on how to
manipulate the contents of a Large Object.
Variablespublic static final int WRITEThis mode indicates we want to write to an object.public static final int READThis mode indicates we want to read an object.public static final int READWRITEThis mode is the default. It indicates we want read and write access to a large object.Methods
public LargeObject open(int oid) throws SQLException
This opens an existing large object, based on its OID. This
method assumes that READ and WRITE access is required (the
default).
public LargeObject open(int oid,
int mode) throws SQLException
This opens an existing large object, based on its OID, and
allows setting the access mode.
public int create() throws SQLException
This creates a large object, returning its OID.
It defaults to READWRITE for the new object's attributes.
public int create(int mode) throws SQLException
This creates a large object, returning its OID, and sets the
access mode.
public void delete(int oid) throws SQLException
This deletes a large object.
public void unlink(int oid) throws SQLException
This deletes a large object. It is identical to the delete
method, and is supplied as the C API uses
unlink.
Object SerializationPostgreSQL is not a normal
SQL database. It is more extensible than most
other databases, and does support object oriented features that
are unique to it.
One of the consequences of this, is that you can have one table
refer to a row in another table. For example:
test=> CREATE TABLE users (username NAME,fullname TEXT);
CREATE
test=> CREATE TABLE server (servername NAME,adminuser users);
CREATE
test=> INSERT INTO users VALUES ('peter','Peter Mount');
INSERT 2610132 1
test=> INSERT INTO server VALUES ('maidast',2610132::users);
INSERT 2610133 1
test=> SELECT * FROM users;
username|fullname
--------+--------------
peter |Peter Mount
(1 row)
test=> SELECT * FROM server;
servername|adminuser
----------+---------
maidast | 2610132
(1 row)
Okay, the above example shows that we can use a table name as a
field, and the row's oid value is stored in that field.
What does this have to do with Java?
In Java, you can store an object to a Stream as long as it's class
implements the java.io.Serializable interface. This process, known
as Object Serialization, can be used to store complex objects into
the database.
Now, under JDBC, you would have to use a
Large Object to store them. However, you cannot perform queries on
those objects.
What the org.postgresql.util.Serialize class does, is provide a
means of storing an object as a table, and to retrieve that object
from a table. In most cases, you would not need to access this
class direct, but you would use the PreparedStatement.setObject()
and ResultSet.getObject() methods. Those methods will check the
objects class name against the table's in the database. If a match
is found, it assumes that the object is a Serialized object, and
retrieves it from that table. As it does so, if the object
contains other serialized objects, then it recurses down the tree.
Sound's complicated? In fact, it's simpler than what I wrote -
it's just difficult to explain.
The only time you would access this class, is to use the create()
methods. These are not used by the driver, but issue one or more
CREATE TABLE statements to the database, based on a Java Object
or Class that you want to serialize.
Oh, one last thing. If your object contains a line like:
public int oid;
then, when the object is retrieved from the table, it is set to
the oid within the table. Then, if the object is modified, and re-
serialized, the existing entry is updated.
If the oid variable is not present, then when the object is
serialized, it is always inserted into the table, and any existing
entry in the table is preserved.
Setting oid to 0 before serialization, will also cause the object
to be inserted. This enables an object to be duplicated in the
database.
Class org.postgresql.util.Serialize
java.lang.Object
|
+----org.postgresql.util.Serialize
public class Serialize extends Object
This class uses PostgreSQL's object oriented features to store Java
Objects. It does this by mapping a Java Class name to a table in the
database. Each entry in this new table then represents a Serialized
instance of this class. As each entry has an OID (Object IDentifier),
this OID can be included in another table. This is too complex to show
here, and will be documented in the main documents in more detail.
Constructors
public Serialize(org.postgresql.Connection c,
String type) throws SQLException
This creates an instance that can be used to serialize
or deserialize a Java object from a PostgreSQL table.
Methods
public Object fetch(int oid) throws SQLException
This fetches an object from a table, given it's OID
Parameters:
oid - The oid of the object
Returns:
Object relating to oid
Throws: SQLException
on error
public int store(Object o) throws SQLException
This stores an object into a table, returning it's OID.
If the object has an int called OID, and it is > 0, then
that value is used for the OID, and the table will be updated. If the
value of OID is 0, then a new row will be created, and the value of
OID will be set in the object. This enables an object's value in the
database to be updateable. If the object has no int called OID, then
the object is stored. However if the object is later retrieved,
amended and stored again, it's new state will be appended to the
table, and will not overwrite the old entries.
Parameters:
o - Object to store (must implement Serializable)
Returns:
oid of stored object
Throws: SQLException
on error
public static void create(org.postgresql.Connection con,
Object o) throws SQLException
This method is not used by the driver, but it creates a
table, given a Serializable Java Object. It should be used before
serializing any objects.
Parameters:
c - Connection to database
o - Object to base table on
Throws: SQLException
on error
public static void create(org.postgresql.Connection con,
Class c) throws SQLException
This method is not used by the driver, but it creates a
table, given a Serializable Java Object. It should be used before
serializing any objects.
Parameters:
c - Connection to database
o - Class to base table on
Throws: SQLException
on error
public static String toPostgreSQL(String name) throws SQLException
This converts a Java Class name to a PostgreSQL table, by
replacing . with _
Because of this, a Class name may not have _ in the name.
Another limitation, is that the entire class name (including
packages) cannot be longer than 31 characters (a limit
forced by PostgreSQL).
Parameters:
name - Class name
Returns:
PostgreSQL table name
Throws: SQLException
on error
public static String toClassName(String name) throws SQLException
This converts a PostgreSQL table to a Java Class name, by
replacing _ with .
Parameters:
name - PostgreSQL table name
Returns:
Class name
Throws: SQLException
on error
Utility Classes
The org.postgresql.util package contains classes used by the internals of
the main driver, and the other extensions.
Class org.postgresql.util.PGmoney
java.lang.Object
|
+----org.postgresql.util.PGobject
|
+----org.postgresql.util.PGmoney
public class PGmoney extends PGobject implements Serializable,
Cloneable
This implements a class that handles the PostgreSQL money type
Variables
public double val
The value of the field
Constructors
public PGmoney(double value)
Parameters:
value - of field
public PGmoney(String value) throws SQLException
Create a money.
Parameters:
value - Definition of this money in PostgreSQL's
syntax
public PGmoney()
Required by the driver
Methods
public void setValue(String s) throws SQLException
Parameters:
s - Definition of this money in PostgreSQL's syntax
Throws: SQLException
on conversion failure
Overrides:
setValue in class PGobject
public boolean equals(Object obj)
Parameters:
obj - Object to compare with
Returns:
true if the two moneys are identical
Overrides:
equals in class PGobject
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class PGobject
public String getValue()
Returns:
the PGmoney in the syntax expected by PostgreSQL
Overrides:
getValue in class PGobject
Class org.postgresql.util.PGobject
java.lang.Object
|
+----org.postgresql.util.PGobject
public class PGobject extends Object implements Serializable,
Cloneable
This class is used to describe data types that are unknown by
JDBC
Standard.
A call to org.postgresql.Connection permits a class that extends this
class to be associated with a named type. This is how the
org.postgresql.geometric package operates.
ResultSet.getObject() will return this class for any type that is
not recognized on having it's own handler. Because of this, any
PostgreSQL data type is supported.
Constructors
public PGobject()
This is called by org.postgresql.Connection.getObject() to
create the object.
Methods
public final void setType(String type)
This method sets the type of this object.
It should not be extended by subclasses, hence its final
Parameters:
type - a string describing the type of the object
public void setValue(String value) throws SQLException
This method sets the value of this object. It must be
overridden.
Parameters:
value - a string representation of the value of the
object
Throws: SQLException
thrown if value is invalid for this type
public final String getType()
As this cannot change during the life of the object, it's
final.
Returns:
the type name of this object
public String getValue()
This must be overridden, to return the value of the object,
in the form required by PostgreSQL.
Returns:
the value of this object
public boolean equals(Object obj)
This must be overridden to allow comparisons of objects
Parameters:
obj - Object to compare with
Returns:
true if the two objects are identical
Overrides:
equals in class Object
public Object clone()
This must be overridden to allow the object to be cloned
Overrides:
clone in class Object
public String toString()
This is defined here, so user code need not override it.
Returns:
the value of this object, in the syntax expected by
PostgreSQL
Overrides:
toString in class Object
Class org.postgresql.util.PGtokenizer
java.lang.Object
|
+----org.postgresql.util.PGtokenizer
public class PGtokenizer extends Object
This class is used to tokenize the text output of PostgreSQL.
We could have used StringTokenizer to do this, however, we needed
to handle nesting of '(' ')' '[' ']' '<' and '>' as these are used by
the geometric data types.
It's mainly used by the geometric classes, but is useful in parsing
any output from custom data types output from PostgreSQL.
See Also:
PGbox, PGcircle, PGlseg, PGpath, PGpoint, PGpolygon
Constructors
public PGtokenizer(String string,
char delim)
Create a tokenizer.
Parameters:
string - containing tokens
delim - single character to split the tokens
Methods
public int tokenize(String string,
char delim)
This resets this tokenizer with a new string and/or
delimiter.
Parameters:
string - containing tokens
delim - single character to split the tokens
public int getSize()
Returns:
the number of tokens available
public String getToken(int n)
Parameters:
n - Token number ( 0 ... getSize()-1 )
Returns:
The token value
public PGtokenizer tokenizeToken(int n,
char delim)
This returns a new tokenizer based on one of our tokens. The
geometric data types use this to process nested tokens (usually
PGpoint).
Parameters:
n - Token number ( 0 ... getSize()-1 )
delim - The delimiter to use
Returns:
A new instance of PGtokenizer based on the token
public static String remove(String s,
String l,
String t)
This removes the lead/trailing strings from a string
Parameters:
s - Source string
l - Leading string to remove
t - Trailing string to remove
Returns:
String without the lead/trailing strings
public void remove(String l,
String t)
This removes the lead/trailing strings from all tokens
Parameters:
l - Leading string to remove
t - Trailing string to remove
public static String removePara(String s)
Removes ( and ) from the beginning and end of a string
Parameters:
s - String to remove from
Returns:
String without the ( or )
public void removePara()
Removes ( and ) from the beginning and end of all tokens
public static String removeBox(String s)
Removes [ and ] from the beginning and end of a string
Parameters:
s - String to remove from
Returns:
String without the [ or ]
public void removeBox()
Removes [ and ] from the beginning and end of all tokens
public static String removeAngle(String s)
Removes < and > from the beginning and end of a string
Parameters:
s - String to remove from
Returns:
String without the < or >
public void removeAngle()
Removes < and > from the beginning and end of all tokens
Class org.postgresql.util.Serialize
This was documented earlier under Object Serialization.
Class org.postgresql.util.UnixCrypt
java.lang.Object
|
+----org.postgresql.util.UnixCrypt
public class UnixCrypt extends Object
This class provides us with the ability to encrypt passwords when
sent over the network stream
Contains static methods to encrypt and compare passwords with Unix
encrypted passwords.
See John Dumas's Java Crypt page for the original source.
(Invalid URL) http://www.zeh.com/local/jfd/crypt.html
Methods
public static final String crypt(String salt,
String original)
Encrypt a password given the clear-text password and a
salt.
Parameters:
salt - A two-character string representing the salt
used
to iterate the encryption engine in lots of different
ways. If you are generating a new encryption then this
value should be randomized.
original - The password to be encrypted.
Returns:
A string consisting of the 2-character salt followed
by
the encrypted password.
public static final String crypt(String original)
Encrypt a password given the clear-text password. This method
generates a random salt using the 'java.util.Random' class.
Parameters:
original - The password to be encrypted.
Returns:
A string consisting of the 2-character salt followed
by
the encrypted password.
public static final boolean matches(String encryptedPassword,
String enteredPassword)
Check that enteredPassword encrypts to encryptedPassword.
Parameters:
encryptedPassword - The encryptedPassword. The first
two characters are assumed to be the salt. This string would be the
same as one found in a Unix /etc/passwd file.
enteredPassword - The password as entered by the user
(or otherwise acquired).
Returns:
true if the password should be considered correct.
Using the driver in a multi-threaded or a servlet environment
A problem with many JDBC drivers is that only
one thread can use a Connection at any one
time -- otherwise a thread could send a query while another one is
receiving results, and this would be a bad thing for the database
engine.
PostgreSQL 6.4 brought thread safety to
the entire driver. (Standard JDBC was thread
safe in 6.3, but the Fastpath API was not.)
Consequently, if your application uses multiple threads then you do
not have to worry about complex algorithms to ensure that only one
uses the database at any time.
If a thread attempts to use the connection while another one is
using it, it will wait until the other thread has finished its
current operation. If it is a regular SQL
statement, then the operation consists of sending the statement and
retrieving any ResultSet (in full). If it
is a Fastpath call (e.g., reading a block
from a LargeObject) then it is the time to
send and retrieve that block.
This is fine for applications and applets but can cause a
performance problem with servlets. With servlets you can have a
heavy load on the connection. If you have several threads
performing queries then each but one will pause, which may not be what
you are after.
To solve this, you would be advised to create a pool of
connections. When ever a thread needs to use the database, it asks
a manager class for a Connection. The
manager hands a free connection to the thread and marks it as
busy. If a free connection is not available, it opens one. Once
the thread has finished with it, it returns it to the manager who
can then either close it or add it to the pool. The manager would
also check that the connection is still alive and remove it from
the pool if it is dead.
So, with servlets, it is up to you to use either a single
connection, or a pool. The plus side for a pool is that threads
will not be hit by the bottle neck caused by a single network
connection. The down side is that it increases the load on the
server, as a backend process is created for each
Connection. It is up to you and your
applications requirements.
Further Reading
If you have not yet read it, I'd advise you read the
JDBC API Documentation
(supplied with Sun's JDK), and the
JDBC Specification. Both are available from
http://java.sun.com/products/jdbc/index.html.
http://jdbc.postgresql.org
contains updated information not included in this document, and
also includes precompiled drivers.