All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class postgresql.fastpath.Fastpath

java.lang.Object
   |
   +----postgresql.fastpath.Fastpath

public class Fastpath

extends Object

This is a means of executing functions imbeded in the postgresql backend from within a java application.

It is based around the file src/interfaces/libpq/fe-exec.c

Implementation notes:

Network protocol:

The code within the backend reads integers in reverse.

There is work in progress to convert all of the protocol to network order but it may not be there for v6.3

When fastpath switches, simply replace SendIntegerReverse() with SendInteger()

See Also:

FastpathFastpathArg, LargeObject

Fastpath(Connection, PG_Stream)

Initialises the fastpath system

Important Notice
This is called from postgresql.Connection, and should not be called from client code.

addFunction(String, int)

This adds a function to our lookup table.

addFunctions(ResultSet)

This takes a ResultSet containing two columns.

fastpath(int, boolean, FastpathArg[])

Send a function call to the PostgreSQL backend

fastpath(String, boolean, FastpathArg[])

Send a function call to the PostgreSQL backend by name.

getData(String, FastpathArg[])

This convenience method assumes that the return value is an Integer

getID(String)

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.

getInteger(String, FastpathArg[])

This convenience method assumes that the return value is an Integer

 public Fastpath(Connection conn,
                 PG_Stream stream)

Initialises the fastpath system

Important Notice
This is called from postgresql.Connection, and should not be called from client code.

Parameters:

conn - postgresql.Connection to attach to

stream - The network stream to the backend

 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

Throws: SQLException

if a database-access error occurs.

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

Send a function call to the PostgreSQL backend by name. Note: the mapping for the procedure name to function id needs to exist, usually to an earlier call to addfunction(). This is the prefered method to call, as function id's can/may change between versions of the backend. For an example of how this works, refer to 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

Throws: SQLException

if name is unknown or if a database-access error occurs.

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 result

Throws: 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 an Integer

Parameters:

name - Function name

args - Function arguments

Returns:

byte[] array containing result

Throws: SQLException

if a database-access error occurs or no result

 public void addFunction(String name,
                         int fnid)

This adds a function to our lookup 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.

Parameters:

name - Function name

fnid - Function id

 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 lookups:

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 postgresql.LargeObject class performs a query upon it's startup, and passes the returned ResultSet to the addFunctions() method here.

Once this has been done, the LargeObject api refers to the functions by name.

Dont 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.

Parameters:

rs - ResultSet

Throws: SQLException

if a database-access error occurs.

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.

Parameters:

name - Function name to lookup

Returns:

Function ID for fastpath call

Throws: SQLException

is function is unknown.

All Packages  Class Hierarchy  This Package  Previous  Next  Index