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 class implements the Fastpath api.

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

Constructor Index

 o Fastpath(Connection, PG_Stream)
Initialises the fastpath system

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

Method Index

 o addFunction(String, int)
This adds a function to our lookup table.
 o addFunctions(ResultSet)
This takes a ResultSet containing two columns.
 o fastpath(int, boolean, FastpathArg[])
Send a function call to the PostgreSQL backend
 o fastpath(String, boolean, FastpathArg[])
Send a function call to the PostgreSQL backend by name.
 o getData(String, FastpathArg[])
This convenience method assumes that the return value is an Integer
 o 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.

 o getInteger(String, FastpathArg[])
This convenience method assumes that the return value is an Integer

Constructors

 o Fastpath
 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

Methods

 o fastpath
 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.
 o fastpath
 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
 o getInteger
 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
 o getData
 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
 o addFunction
 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
 o addFunctions
 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
 o getID
 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