Class Fastpath


  • public class Fastpath
    extends java.lang.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 Detail

      • Fastpath

        public Fastpath​(org.postgresql.core.BaseConnection conn)
        Initialises the fastpath system
        Parameters:
        conn - BaseConnection to attach to
    • Method Detail

      • fastpath

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

        public byte[] fastpath​(int fnId,
                               FastpathArg[] args)
                        throws java.sql.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:
        java.sql.SQLException - if a database-access error occurs.
      • fastpath

        public byte[] fastpath​(java.lang.String name,
                               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 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:
        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
      • getLong

        public long getLong​(java.lang.String name,
                            FastpathArg[] args)
                     throws java.sql.SQLException
        This convenience method assumes that the return value is a long (bigint)
        Parameters:
        name - Function name
        args - Function arguments
        Returns:
        long 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 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:
        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.