/*-------------------------------------------------------------------------
*
* Copyright (c) 2003-2008, PostgreSQL Global Development Group
*
* IDENTIFICATION
*   $PostgreSQL: pgjdbc/org/postgresql/fastpath/Fastpath.java,v 1.35 2008/01/08 06:56:28 jurka Exp $
*
*-------------------------------------------------------------------------
*/
package org.postgresql.fastpath;

import java.sql.SQLException;
import java.sql.ResultSet;
import java.util.Hashtable;
import org.postgresql.core.BaseConnection;
import org.postgresql.core.QueryExecutor;
import org.postgresql.core.ParameterList;
import org.postgresql.util.PSQLException;
import org.postgresql.util.PSQLState;
import org.postgresql.util.GT;

/**
 * This class implements the Fastpath api.
 *
 * <p>This is a means of executing functions imbeded in the org.postgresql
 *  backend from within a java application.
 *
 * <p>It is based around the file src/interfaces/libpq/fe-exec.c
 *
 */
public class Fastpath
{
    // Java passes oids around as longs, but in the backend
    // it's an unsigned int, so we use this to make the conversion
    // of long -> signed int which the backend interprets as unsigned.
    private final static long NUM_OIDS = 4294967296L; // 2^32

    // This maps the functions names to their id's (possible unique just
    // to a connection).
    private final Hashtable func = new Hashtable();
    private final QueryExecutor executor;
    private final BaseConnection connection;

    /**
     * Initialises the fastpath system
     *
     * @param conn BaseConnection to attach to
     */
    public Fastpath(BaseConnection conn)
    {
        this.connection = conn;
        this.executor = conn.getQueryExecutor();
    }

    /**
     * Send a function call to the PostgreSQL backend
     *
     * @param fnId Function id
     * @param resultType True if the result is an integer, false for other results
     * @param args FastpathArguments to pass to fastpath
     * @return null if no data, Integer if an integer result, or byte[] otherwise
     * @exception SQLException if a database-access error occurs.
     */
    public Object fastpath(int fnId, boolean resultType, FastpathArg[] args) throws SQLException
    {
        // Turn fastpath array into a parameter list.
        ParameterList params = executor.createFastpathParameters(args.length);
        for (int i = 0; i < args.length; ++i)
        {
            args[i].populateParameter(params, i + 1);
        }

        // Run it.
        byte[] returnValue = executor.fastpathCall(fnId, params, connection.getAutoCommit());

        // Interpret results.
        if (!resultType || returnValue == null)
            return returnValue;

        if (returnValue.length != 4)
            throw new PSQLException(GT.tr("Fastpath call {0} - No result was returned and we expected an integer.", new Integer(fnId)),
                                    PSQLState.NO_DATA);

        return new Integer((returnValue[3] & 255) |
                           ((returnValue[2] & 255) << 8) |
                           ((returnValue[1] & 255) << 16) |
                           ((returnValue[0] & 255) << 24));
    }

    /**
     * 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
     *
     * @param name Function name
     * @param resulttype True if the result is an integer, false for other
     * results
     * @param args FastpathArguments to pass to fastpath
     * @return null if no data, Integer if an integer result, or byte[] otherwise
     * @exception SQLException if name is unknown or if a database-access error
     * occurs.
     * @see org.postgresql.largeobject.LargeObject
     */
    public Object fastpath(String name, boolean resulttype, FastpathArg[] args) throws SQLException
    {
        if (connection.getLogger().logDebug())
            connection.getLogger().debug("Fastpath: calling " + name);
        return fastpath(getID(name), resulttype, args);
    }

    /**
     * This convenience method assumes that the return value is an Integer
     * @param name Function name
     * @param args Function arguments
     * @return integer result
     * @exception SQLException if a database-access error occurs or no result
     */
    public int getInteger(String name, FastpathArg[] args) throws SQLException
    {
        Integer i = (Integer)fastpath(name, true, args);
        if (i == null)
            throw new PSQLException(GT.tr("Fastpath call {0} - No result was returned and we expected an integer.", name),
                                    PSQLState.NO_DATA);
        return i.intValue();
    }

    /**
     * This convenience method assumes that the return value is an oid.
     * @param name Function name
     * @param args Function arguments
     * @exception SQLException if a database-access error occurs or no result
     */
    public long getOID(String name, FastpathArg[] args) throws SQLException
    {
        long oid = getInteger(name, args);
        if (oid < 0)
            oid += NUM_OIDS;
        return oid;
    }

    /**
     * This convenience method assumes that the return value is not an Integer
     * @param name Function name
     * @param args Function arguments
     * @return byte[] array containing result
     * @exception SQLException if a database-access error occurs or no result
     */
    public byte[] getData(String name, FastpathArg[] args) throws SQLException
    {
        return (byte[])fastpath(name, false, args);
    }

    /**
     * This adds a function to our lookup table.
     *
     * <p>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.
     *
     * @param name Function name
     * @param fnid Function id
     */
    public void addFunction(String name, int fnid)
    {
        func.put(name, new Integer(fnid));
    }

    /**
     * This takes a ResultSet containing two columns. Column 1 contains the
     * function name, Column 2 the oid.
     *
     * <p>It reads the entire ResultSet, loading the values into the function
     * table.
     *
     * <p><b>REMEMBER</b> to close() the resultset after calling this!!
     *
     * <p><b><em>Implementation note about function name lookups:</em></b>
     *
     * <p>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.
     *
     * <p>The org.postgresql.largeobject.LargeObject class performs a query upon it's startup,
     * and passes the returned ResultSet to the addFunctions() method here.
     *
     * <p>Once this has been done, the LargeObject api refers to the functions by
     * name.
     *
     * <p>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.
     *
     * @param rs ResultSet
     * @exception SQLException if a database-access error occurs.
     * @see org.postgresql.largeobject.LargeObjectManager
     */
    public void addFunctions(ResultSet rs) throws SQLException
    {
        while (rs.next())
        {
            func.put(rs.getString(1), new Integer(rs.getInt(2)));
        }
    }

    /**
     * This returns the function id associated by its name.
     *
     * <p>If addFunction() or addFunctions() have not been called for this name,
     * then an SQLException is thrown.
     *
     * @param name Function name to lookup
     * @return Function ID for fastpath call
     * @exception SQLException is function is unknown.
     */
    public int getID(String name) throws SQLException
    {
        Integer id = (Integer)func.get(name);

        // may be we could add a lookup to the database here, and store the result
        // in our lookup table, throwing the exception if that fails.
        // We must, however, ensure that if we do, any existing ResultSet is
        // unaffected, otherwise we could break user code.
        //
        // so, until we know we can do this (needs testing, on the TODO list)
        // for now, we throw the exception and do no lookups.
        if (id == null)
            throw new PSQLException(GT.tr("The fastpath function {0} is unknown.", name), PSQLState.UNEXPECTED_ERROR);

        return id.intValue();
    }

    /**
     * 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.
     */
    public static FastpathArg createOIDArg(long oid)
    {
        if (oid > Integer.MAX_VALUE)
            oid -= NUM_OIDS;
        return new FastpathArg((int)oid);
    }

}