org.postgresql.fastpath
Class Fastpath

java.lang.Object
  org.postgresql.fastpath.Fastpath

public class Fastpath
extends Object

This class implements the Fastpath api.

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

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

Constructor Summary

Fastpath(BaseConnection conn)
Initialises the fastpath system

Method Summary

void	addFunction(String name, int fnid) This adds a function to our lookup table.
void	addFunctions(ResultSet rs) This takes a ResultSet containing two columns.
static FastpathArg	createOIDArg(long oid) Creates a FastpathArg with an oid parameter.
Object	fastpath(int fnId, boolean resultType, FastpathArg[] args) Deprecated. please use fastpath(int, FastpathArg[])
byte[]	fastpath(int fnId, FastpathArg[] args) Send a function call to the PostgreSQL backend
Object	fastpath(String name, boolean resulttype, FastpathArg[] args) Deprecated. Use getData(String, FastpathArg[]) if you expect a binary result, or one of getInteger(String, FastpathArg[]) or getLong(String, FastpathArg[]) if you expect a numeric one
byte[]	fastpath(String name, FastpathArg[] args) Send a function call to the PostgreSQL backend by name.
byte[]	getData(String name, FastpathArg[] args) This convenience method assumes that the return value is not an Integer
int	getID(String name) This returns the function id associated by its name.
int	getInteger(String name, FastpathArg[] args) This convenience method assumes that the return value is an integer
long	getLong(String name, FastpathArg[] args) This convenience method assumes that the return value is a long (bigint)
long	getOID(String name, FastpathArg[] args) This convenience method assumes that the return value is an oid.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Fastpath

public Fastpath(BaseConnection conn)

Initialises the fastpath system

Parameters:

conn - BaseConnection to attach to

Method Detail

fastpath

@Deprecated
public Object fastpath(int fnId,
                                  boolean resultType,
                                  FastpathArg[] args)
                throws SQLException

Deprecated. please use fastpath(int, FastpathArg[])

Send a function call to the PostgreSQL backend

Parameters:

fnId - Function id

resultType - True if the result is a numeric (Integer or Long)

args - FastpathArguments to pass to fastpath

Returns:

null if no data, Integer if an integer result, Long if a long result, or byte[] otherwise

Throws:

SQLException - if a database-access error occurs.

fastpath

public byte[] fastpath(int fnId,
                       FastpathArg[] args)
                throws SQLException

Send a function call to the PostgreSQL backend

Parameters:

fnId - Function id

args - FastpathArguments to pass to fastpath

Returns:

null if no data, byte[] otherwise

Throws:

SQLException - if a database-access error occurs.

fastpath

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

Deprecated. Use getData(String, FastpathArg[]) if you expect a binary result, or one of getInteger(String, FastpathArg[]) or getLong(String, FastpathArg[]) if you expect a numeric one

Parameters:

name - Function name

resulttype - True if the result is a numeric (Integer or Long)

args - FastpathArguments to pass to fastpath

Returns:

null if no data, Integer if an integer result, Long if a long result, or byte[] otherwise

Throws:

SQLException - if something goes wrong

See Also:

fastpath(int, FastpathArg[]), fastpath(String, FastpathArg[])

fastpath

public byte[] fastpath(String name,
                       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 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.LargeObject

Parameters:

name - Function name

args - FastpathArguments to pass to fastpath

Returns:

null if no data, byte[] otherwise

Throws:

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

See Also:

LargeObject

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

getLong

public long getLong(String name,
                    FastpathArg[] args)
             throws SQLException

This convenience method assumes that the return value is a long (bigint)

Parameters:

name - Function name

args - Function arguments

Returns:

long result

Throws:

SQLException - if a database-access error occurs or no result

getOID

public long getOID(String name,
                   FastpathArg[] args)
            throws SQLException

This convenience method assumes that the return value is an oid.

Parameters:

name - Function name

args - Function arguments

Returns:

oid of the given call

Throws:

SQLException - if a database-access error occurs or no result

getData

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

This convenience method assumes that the return value is not 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

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

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 HashMap is used. Also, only the function's required are entered into this table, keeping connection times as fast as possible.

The org.postgresql.largeobject.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

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.

createOIDArg

public static FastpathArg createOIDArg(long oid)

Creates a FastpathArg with an oid parameter. This is here instead of a constructor of FastpathArg because the constructor can't tell the difference between an long that's really int8 and a long thats an oid.

Parameters:

oid - input oid

Returns:

FastpathArg with an oid parameter