postgres/src/interfaces/jdbc/org/postgresql/fastpath/Fastpath.java

package org.postgresql.fastpath;

import java.io.*;
import java.lang.*;
import java.net.*;
import java.util.*;
import java.sql.*;
import org.postgresql.util.*;

// Important: There are a lot of debug code commented out. Please do not
// delete these.

/**
 * 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
 *
 * @see org.postgresql.FastpathFastpathArg
 * @see org.postgresql.LargeObject
 */
public class Fastpath
{
  // This maps the functions names to their id's (possible unique just
  // to a connection).
  protected Hashtable func = new Hashtable();
  
  protected org.postgresql.Connection conn;		// our connection
  protected org.postgresql.PG_Stream stream;	// the network stream
  
  /**
   * Initialises the fastpath system
   *
   * <p><b>Important Notice</b>
   * <br>This is called from org.postgresql.Connection, and should not be called
   * from client code.
   *
   * @param conn org.postgresql.Connection to attach to
   * @param stream The network stream to the backend
   */
  public Fastpath(org.postgresql.Connection conn,org.postgresql.PG_Stream stream)
  {
    this.conn=conn;
    this.stream=stream;
    //DriverManager.println("Fastpath initialised");
  }
  
  /**
   * 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
  {
    // added Oct 7 1998 to give us thread safety
    synchronized(stream) {
      
    // send the function call
    try {
      // 70 is 'F' in ASCII. Note: don't use SendChar() here as it adds padding
      // that confuses the backend. The 0 terminates the command line.
      stream.SendInteger(70,1);
      stream.SendInteger(0,1);

      stream.SendInteger(fnid,4);
      stream.SendInteger(args.length,4);
      
      for(int i=0;i<args.length;i++)
	args[i].send(stream);
      
      // This is needed, otherwise data can be lost
      stream.flush();
      
    } catch(IOException ioe) {
      throw new PSQLException("postgresql.fp.send",new Integer(fnid),ioe);
    }
    
    // Now handle the result
    
    // We should get 'V' on sucess or 'E' on error. Anything else is treated
    // as an error.
    //int in = stream.ReceiveChar();
    //DriverManager.println("ReceiveChar() = "+in+" '"+((char)in)+"'");
    //if(in!='V') {
    //if(in=='E')
    //throw new SQLException(stream.ReceiveString(conn.getEncoding()));
    //throw new SQLException("Fastpath: expected 'V' from backend, got "+((char)in));
    //}
    
    // Now loop, reading the results
    Object result = null; // our result
    while(true) {
      int in = stream.ReceiveChar();
      //DriverManager.println("ReceiveChar() = "+in+" '"+((char)in)+"'");
      switch(in)
	{
	case 'V':
	  break;
	  
	  //------------------------------
	  // Function returned properly
	  //
	case 'G':
	  int sz = stream.ReceiveIntegerR(4);
	  //DriverManager.println("G: size="+sz);  //debug
	  
	  // Return an Integer if
	  if(resulttype)
	    result = new Integer(stream.ReceiveIntegerR(sz));
	  else {
	    byte buf[] = new byte[sz];
	    stream.Receive(buf,0,sz);
	    result = buf;
	  }
	  break;
	  
	  //------------------------------
	  // Error message returned
	case 'E':
          throw new PSQLException("postgresql.fp.error",stream.ReceiveString(conn.getEncoding()));
	  
	  //------------------------------
	  // Notice from backend
	case 'N':
          conn.addWarning(stream.ReceiveString(conn.getEncoding()));
	  break;
	  
	  //------------------------------
	  // End of results
	  //
	  // Here we simply return res, which would contain the result
	  // processed earlier. If no result, this already contains null
	case '0':
	  //DriverManager.println("returning "+result);
	  return result;
	  
	case 'Z':
	    break;
	    
	default:
	  throw new PSQLException("postgresql.fp.protocol",new Character((char)in));
	}
    }
    }
  }
  
  /**
   * 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
   *
   * @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
   */
  public Object fastpath(String name,boolean resulttype,FastpathArg[] args) throws SQLException
  {
    //DriverManager.println("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("postgresql.fp.expint",name);
    return i.intValue();
  }
  
  /**
   * This convenience method assumes that the return value is 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 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.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("postgresql.fp.unknown",name);
    
    return id.intValue();
  }
}