Red Hat Database Extensions to the JDBC API

Red Hat Database is an extensible database system that is based on PostgreSQL. You can add your own functions and data types to the backend. These facilities, which are unique to PostgreSQL, are supported from Java with a set of extension APIs.

All extensions are found within the org.postgresql package, typically as sub-packages. The list below gives the available packages and gives a short description of each.

org.postgresql

Contains Red Hat Database's implementation of java.sql.Connection, which includes additional methods that provide access to other extensions including Fastpath and LargeObjectManager.

org.postgresql.fastpath

Includes the Fastpath and FastpathArg classes. These classes are a Java implementation of the libpq Fastpath mechanism, which enables backend functions to be executed by clients.

org.postgresql.largeobject

Consists of two classes, LargeObjectManager, which deals with creating, opening and deleting large objects, and LargeObject, which deals with an individual object.

org.postgresql.util

Contains the Serializable, PGobject, and PGmoney classes as well as the utility classes PGtokenizer and UnixCrypt.

org.postgresql.geometric

Red Hat Database has a set of data types that allow for the storage of geometric features in a table. These include points, lines, and polygons. These types are supported in Java through the org.postgresql.geometric package. It contains classes that extend the org.postgresql.util.PGobject class.

org.postgresql

Connection

The Connection class, part of the org.postgresql package, is the Red Hat Database JDBC driver's implementation of java.sql.Connection. The org.postgresql.Connection defines three methods in addition to the methods required by the java.sql.Connection interface.

Connection Definition

package org.postgresql;
public class Connection implements java.sql.Connection {
   // Methods (new; java.sql.Connection methods not listed)
   public void addDataType(String type, String name);
   public Fastpath getFastpathAPI() throws SQLException;
   public LargeObjectManager getLargeObjectAPI() throws SQLException;
}

Fastpath

Fastpath is an API that 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 the Fastpath as an API, you need to import the org.postgresql.fastpath package in the preamble of the source file in which Fastpath will be used. A Fastpath object that is associated with a given database connection can be obtained by requesting one from the Connection object (cast to org.postgresql.Connection). For example:

import org.postgresql.Connection;
import org.postgresql.fastpath.*;
...
Fastpath fp = ((org.postgresql.Connection) con).getFastpathAPI();

Fastpath Definition

package org.postgresql.fastpath;
   public class Fastpath {
      // Methods
      public void addFunction(String name, int fnid);
      public void addFunctions(ResultSet rs) throws SQLException;
      public Object fastpath(int field, boolean resulttype, 
         FastpathArg args[]) throws SQLException;
      public Object fastpath(String name, boolean resulttype, 
         FastpathArg args[]) throws SQLException;
      public byte[] getData(String name, FastpathArg args[]) throws SQLException;
      public int getID(String name) throws SQLException;
      public int getInteger(String name, FastpathArg args[]) throws SQLException;
   }

Methods

public void addFunction(String name, int fnid)

This method adds a function to the function name-to-OID look-up table used internally by the Fastpath API. User code should use the addFunctions method, which is based upon a query, rather than hard coding the OID as 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 method takes a ResultSet containing two columns as its argument. The first column contains a function name; the second contains that function's OID. The addFunctions method reads the entire ResultSet, loading the values into its internal function name-to-OID mapping table.

public Object fastpath(int fnid, boolean resulttype, FastpathARG args[]) throws SQLException

This method sends a function call to the Red Hat Database backend that the Fastpath object is associated with. This version of Fastpath calls a function by OID.

public Object fastpath(String name, boolean resulttype, FastpathARG args[]) throws SQLException

The fastpath method sends a function call to the Red Hat Database backend that the Fastpath object is associated with. This version of Fastpath calls a function by name.

public byte[] getData(String name, FastpathArg args[]) throws SQLException

getData is a wrapper method around Fastpath that assumes that the function to be called returns binary data.

public int getID(String name) throws SQLException

getID returns the OID of the function associated with the given function name. If the function name is not in the lookup table (that is: if either addFunction() or addFunctions() has not been called), then an SQLException is thrown.

public int getInteger(String name, FastpathArg args[]) throws SQLException

getInteger is a wrapper method for fastpath that assumes that the function to be called returns an integer value.

FastpathArg Definition

package org.postgresql.fastpath;
public class FastpathArg {
   public FastpathArg(int value);
   public FastpathArg(byte[] bytes);
   public FastpathArg(byte[] buf, int off, int len);
   public FastpathArg(String s);
}

LargeObject

This class implements the large object interface to Red Hat Database. It provides the basic methods required to run the interface plus a pair of methods that provide InputStream and OutputStream classes for this object.

Refer to LargeObjectManager on how to gain access to LargeObject objects.

LargeObject Definition

package org.postgresql.largeobject;
public class LargeObject {
   // Constants
   public static final int SEEK_SET;
   public static final int SEEK_CUR;
   public static final int SEEK_END;
   
   // Methods
   public void close() throws SQLException;
   public int getOID();
   public byte[] read(int len) throws SQLException;
   public void read(byte buf[], int off, int len) 
      throws SQLException;
   public void write(byte buf[]) throws SQLException;
   public void write(byte buf[], int off, int len) 
      throws SQLException;
}

LargeObjectManager Definition

package org.postgresql.largeobject;
public class LargeObjectManager {
   // Constants
   public static final int WRITE;
   public static final int READ;
   public static final int READWRITE;
   
   // Methods
   public LargeObject open(int oid) throws SQLException;
   public LargeObject open(int oid, int mode) throws SQLException;
   public int create() throws SQLException;
   public int create(int mode) throws SQLException;
   public void delete(int oid) throws SQLException;
   public void unlink(int oid) throws SQLException;
}

org.postgres.utils

Serializable Interface

Red Hat Database is more extensible than most other databases and supports unique object-oriented features. 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)

The above shows that we can use a table name as a field, and the row's OID value is stored in that field.

With Java, you can convert an object to a Stream as long as its class implements the java.io.Serializable interface. This process, known as Object Serialization, can be used to store complex objects in the database. If JDBC was used, you could use a Large Object to store objects. You cannot, however, perform queries on those objects.

What the org.postgresql.util.Serialize class does is provide a means of storing an object as a table. It also provides methods to retrieve that object from a table. In most cases, you do not need to access this class directly; you would use the PreparedStatement.setObject() and ResultSet.getObject() methods. Those methods check the object's class name against the tables 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 retrieves them, continuing on recursively.

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.

If your object contains a line such as:

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.

Serializable Definition

package org.postgresql.util;
public class Serializable {
  // Constructors
  public Serialize(Connection con, String type) 
     throws SQLException;
   
  // Methods
  public Object fetch(int oid) throws SQLException;
  public int store(Object o) throws SQLException;
   
  // Class Methods
  public static void create(Connection con, Object o)
     throws SQLException;
  public static String toClassName(String name) 
     throws SQLException;
  public static String toPostgreSQL(String name) 
     throws SQLException;
}

PGobject Class

The PGobject class is used to describe specialized data types that are not included in the JDBC standards. A call to the addDatatype method of an org.postgresql.Connection object permits a class that extends PGobject to be associated with a named type. This is how the org.postgresql.geometric package operates.

ResultSet.getObject() will return a PGobject instance for any type that is not recognized and does not have its own handler. Therefore, all PostgreSQL data types are supported.

PGobject Definition

package org.postgresql.util;
public class PGobject implements Serializable, Cloneable {
   // Constructors
   public PGobject();
   
   // Methods
   public Object clone();
   public boolean equals(Object obj);
   public final String getType();
   public String getValue();
   public final void setType(String type);
   public void setValue(String value) throws SQLException;
   public String toString();
}

PGmoney Class

The PGmoney class handles the Red Hat Database money data type.

PGmoney Definition

package org.postgresql.util;
public class PGmoney extends PGobject 
   implements Serializable, Cloneable {
   // Variables
   public double val;
   
   // Constructors
   public PGmoney();
   public PGmoney(double val);
   public PGmoney(String value) throws SQLException;
   
   // Methods
   public void setValue(String s) throws SQLException;
   public boolean equals(Object obj);
   public Object clone();
   public String getValue();
}

PGtokenizer Class

The PGtokenizer class is used to tokenize the text output of Red Hat Database. It is used by the geometric classes. Any custom handler classes that need to parse output from Red Hat Database will find PGtokenizer useful.

PGtokenizer Definition

package org.postgresql.util;
public class PGtokenizer {
   // Constructors
   public PGtokenizer(String string, char delim);
   
   // Methods
   public int getSize();
   public String getToken(int n);
   public void remove(String l, String t);
   public void removeAngle();
   public void removeBox();
   public void removePara();
   public int tokenize(String string, char delim);
   public PGtokenizer tokenizeToken(int n, char delim);
   
   // Class methods
   public static String remove(String s, String l, String t);
   public static String removeAngle(String s);
   public static String removeBox(String s);
   public static String removePara(String s);
}

UnixCrypt Class

UnixCrypt provides the ability to encrypt passwords that are to be sent over the network stream for user authentication. It contains static methods to encrypt passwords and to compare passwords with Unix-encrypted ones.

UnixCrypt Definition

package org.postgresql.util;
public class UnixCrypt {
   // Class Methods
   public static final String crypt(String original);
   public static final String crypt(String salt, 
      String original);
   public static final boolean matches(String 
      encrypted, String entered);
}

org.postgresql.geometric

PGpoint Definition

package org.postgresql.geometric;
public class PGpoint extends PGobject 
   implements Serializable, Cloneable {
   // Variables
   public double x;
   public double y;
   
   // Constructors
   public PGpoint();
   public PGpoint(double x, double y);
   public PGpoint(String value) throws SQLException;
   
   // Methods
   public Object clone();
   public boolean equals(Object obj);
   public String getValue();
   public void move(int x, int y);
   public void move(double x, double y);
   public void setLocation(int x, int y);
   public void setLocation(Point p);
   public void setValue(String s) throws SQLException;
   public void translate(int x, int y);
   public void translate(double x, double y);
}

PGpoint Methods

public Object clone()

Creates a new PGpoint object that is exactly the same as this one.

public boolean equals(Object obj)

Compare the current PGpoint object with another PGpoint object.

public String getValue()

Returns the definition of the PGpoint in Red Hat Database point syntax.

public void move(int x, int y)

Moves the point to the supplied coordinates.

public void move(double x, double y)

Moves the point to the supplied coordinates.

public void setLocation(int x, int y)

Moves the point to the supplied coordinates. This method is the same as move(int, int).

public void setLocation(java.awt.Point p)

Moves the point to the coordinate defined by the supplied Point.

public void setValue(String s) throws SQLException

This method sets the X and Y coordinates of this PGpoint. The Red Hat Database point syntax must be used.

public void translate(int dx, int dy)

Translates the point by the given amount. The new position of the PGpoint p at (x, y) will be (x + dx, y + dy).

public void translate(double x, double y)

Translates the point by the given amount. The new position of the PGpoint p at (x, y) will be (x + dx, y + dy).

PGlseg Class

This implements the lseg data type. lseg represents a finite line or line segment; the line does not extend beyond its two endpoints.

PGlseg Definition

package org.postgresql.geometric;
public class PGlseg extends PGobject 
   implements Serializable, Cloneable {
   // Variables
   public PGpoint[] point;
   
   // Constructors
   public PGlseg();
   public PGlseg(double x1, double y1, double x2, double y2);
   public PGlseg(PGpoint p1, PGpoint p2);
   public PGlseg(String s) throws SQLException;
   
   // Methods
   public Object clone();
   public boolean equals(Object obj);
   public String getValue();
   public void setValue(String s) throws SQLException;
}

PGline Class

This implements an infinite line which is defined by two points. The line data type exists in the backend but is currently unimplemented. This class is included for completeness.

PGline Definition

package org.postgresql.geometric;
public class PGline extends PGobject 
   implements Serializable, Cloneable {
   // Variables
   public PGpoint[] point;
   
   // Constructors
   public PGline();
   public PGline(double x1, double y1, double x2, double y2);
   public PGline(PGpoint p1, PGpoint p2);
   public PGline(String s) throws SQLException;
   
   // Methods
   public Object clone();
   public boolean equals(Object obj);
   public String getValue();
   public void setValue(String s) throws SQLException;
}

PGbox Class

The PGbox class represents Red Hat Database's box data type. A box is represented by a pair of points, the opposite corners of the box.

PGbox Definition

package org.postgresql.geometric;
public class PGbox extends PGobject 
   implements Serializable, Cloneable {
   // Variables
   public PGpoint[] point;
   
   // Constructors
   public PGbox(double x1, double y1, double x2, double y2);
   
   // Methods
   public Object clone();
   public boolean equals(Object obj);
   public String getValue();
         	public void setValue(String value) throws SQLException;
}

PGpolygon Class

The PGbox class represents Red Hat Database's polygon data type.

PGpolygon Definition

package org.postgresql.geometric;
public class PGpolygon extends PGobject 
   implements Serializable, Cloneable {
   // Variables
   public PGpoint[] points;
   
   // Constructors
   public PGpolygon();
   public PGpolygon(PGpoint points[]);
   public PGpolygon(String s) throws SQLException;
   
   // Methods
   public Object clone();
   public boolean equals(Object obj);
   public String getValue();
   public void setValue(String s) throws SQLException;
}

PGcircle Class

PGcircle represents Red Hat Database's circle data type. A circle consists of a center point and a radius.

PGcircle Definition

package org.postgresql.geometric;
public class PGcircle extends PGobject implements 
   Serializable, Cloneable {
   // Variables
   public PGpoint center;
   public double radius;
   
   // Constructors
   public PGcircle();
   public PGcircle(double x, double y, double r);
   public PGcircle(PGpoint c, double r);
   public PGcircle(String s) throws SQLException;
   
   // Methods
   public Object clone();
   public boolean equals(Object obj);
   public String getValue();
   public void setValue(String s) throws SQLException;
}

PGpath Class

PGpath implements a path, a line with multiple segments. The path may or may not be closed.

PGpath Definition

package org.postgresql.geometric;
public class PGpath extends PGobject implements 
   Serializable, Cloneable {
   // Variables
   public boolean open;
   public PGpoint[] points;
   
   // Constructors
   public PGpath();
   public PGpath(PGpoint points[], boolean open);
   public PGpath(String s) throws SQLException;
   
   // Methods
   public Object clone();
   public void closePath();
   public boolean equals(Object obj);
   public String getValue();
   public boolean isClosed();
   public boolean isOpen();
   public void openPath();
   public void setValue(String s) throws SQLException;
}