Fastpath
Keywords: org.postgresql.fastpath.Fastpath class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.postgresql.fastpath
Class Fastpath

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

    public class Fastpath

extends java.lang.Object

This class implements the Fastpath api.

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

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

Constructor Summary
`Fastpath(org.postgresql.core.BaseConnection conn)` Initialises the fastpath system

Method Summary
`void` | `addFunction(java.lang.String name, int fnid)` This adds a function to our lookup table.
`void` | `addFunctions(java.sql.ResultSet rs)` This takes a ResultSet containing two columns.
`static FastpathArg` | `createOIDArg(long oid)` Creates a FastpathArg with an oid parameter.
`java.lang.Object` | `fastpath(int fnId, boolean resultType, FastpathArg[] args)` Send a function call to the PostgreSQL backend
`java.lang.Object` | `fastpath(java.lang.String name, boolean resulttype, FastpathArg[] args)` Send a function call to the PostgreSQL backend by name.
`byte[]` | `getData(java.lang.String name, FastpathArg[] args)` This convenience method assumes that the return value is not an Integer
`int` | `getID(java.lang.String name)` This returns the function id associated by its name.
`int` | `getInteger(java.lang.String name, FastpathArg[] args)` This convenience method assumes that the return value is an Integer
`long` | `getOID(java.lang.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(org.postgresql.core.BaseConnection conn)

  Initialises the fastpath system

  Parameters:
    `conn` - BaseConnection to attach to

Method Detail

### fastpath

    public java.lang.Object fastpath(int fnId,
                                     boolean resultType,
                                     FastpathArg[] args)
                              throws java.sql.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:
    `java.sql.SQLException` - if a database-access error occurs.

### fastpath

    public java.lang.Object fastpath(java.lang.String name,
                                     boolean resulttype,
                                     FastpathArg[] args)
                              throws java.sql.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 org.postgresql.largeobject.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:
    `java.sql.SQLException` - if name is unknown or if a database-access error occurs.
  See Also:
    `LargeObject`

### getInteger

    public int getInteger(java.lang.String name,
                          FastpathArg[] args)
                   throws java.sql.SQLException

  This convenience method assumes that the return value is an Integer

  Parameters:
    `name` - Function name
    `args` - Function arguments
  Returns:
    integer result
  Throws:
    `java.sql.SQLException` - if a database-access error occurs or no result

### getOID

    public long getOID(java.lang.String name,
                       FastpathArg[] args)
                throws java.sql.SQLException

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

  Parameters:
    `name` - Function name
    `args` - Function arguments
  Throws:
    `java.sql.SQLException` - if a database-access error occurs or no result

### getData

    public byte[] getData(java.lang.String name,
                          FastpathArg[] args)
                   throws java.sql.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:
    `java.sql.SQLException` - if a database-access error occurs or no result

### addFunction

    public void addFunction(java.lang.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(java.sql.ResultSet rs)
                      throws java.sql.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 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:
    `java.sql.SQLException` - if a database-access error occurs.
  See Also:
    `LargeObjectManager`

### getID

    public int getID(java.lang.String name)
              throws java.sql.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:
    `java.sql.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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD