/*-------------------------------------------------------------------------
*
* Copyright (c) 2003-2008, PostgreSQL Global Development Group
*
* IDENTIFICATION
*   $PostgreSQL: pgjdbc/org/postgresql/largeobject/LargeObjectManager.java,v 1.24 2008/01/08 06:56:30 jurka Exp $
*
*-------------------------------------------------------------------------
*/
package org.postgresql.largeobject;


import java.sql.ResultSet;
import java.sql.SQLException;
import org.postgresql.core.BaseConnection;
import org.postgresql.fastpath.Fastpath;
import org.postgresql.fastpath.FastpathArg;
import org.postgresql.util.PSQLException;
import org.postgresql.util.GT;
import org.postgresql.util.PSQLState;

/**
 * This class implements the large object interface to org.postgresql.
 *
 * <p>It provides methods that allow client code to create, open and delete
 * large objects from the database. When opening an object, an instance of
 * org.postgresql.largeobject.LargeObject is returned, and its methods then allow
 * access to the object.
 *
 * <p>This class can only be created by org.postgresql.Connection
 *
 * <p>To get access to this class, use the following segment of code:
 * <br><pre>
 * import org.postgresql.largeobject.*;
 *
 * Connection  conn;
 * LargeObjectManager lobj;
 *
 * ... code that opens a connection ...
 *
 * lobj = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
 * </pre>
 *
 * <p>Normally, client code would use the getAsciiStream, getBinaryStream,
 * or getUnicodeStream methods in ResultSet, or setAsciiStream,
 * setBinaryStream, or setUnicodeStream methods in PreparedStatement to
 * access Large Objects.
 *
 * <p>However, sometimes lower level access to Large Objects are required,
 * that are not supported by the JDBC specification.
 *
 * <p>Refer to org.postgresql.largeobject.LargeObject on how to manipulate the
 * contents of a Large Object.
 *
 * @see java.sql.ResultSet#getAsciiStream
 * @see java.sql.ResultSet#getBinaryStream
 * @see java.sql.ResultSet#getUnicodeStream
 * @see java.sql.PreparedStatement#setAsciiStream
 * @see java.sql.PreparedStatement#setBinaryStream
 * @see java.sql.PreparedStatement#setUnicodeStream
 */
public class LargeObjectManager
{
    // the fastpath api for this connection
    private Fastpath fp;
    private BaseConnection conn;

    /**
     * This mode indicates we want to write to an object
     */
    public static final int WRITE = 0x00020000;

    /**
     * This mode indicates we want to read an object
     */
    public static final int READ = 0x00040000;

    /**
     * This mode is the default. It indicates we want read and write access to
     * a large object
     */
    public static final int READWRITE = READ | WRITE;

    /**
     * This prevents us being created by mere mortals
     */
    private LargeObjectManager()
    {
    }

    /**
     * Constructs the LargeObject API.
     *
     * <p><b>Important Notice</b>
     * <br>This method should only be called by org.postgresql.Connection
     *
     * <p>There should only be one LargeObjectManager per Connection. The
     * org.postgresql.Connection class keeps track of the various extension API's
     * and it's advised you use those to gain access, and not going direct.
     */
    public LargeObjectManager(BaseConnection conn) throws SQLException
    {
        this.conn = conn;
        // We need Fastpath to do anything
        this.fp = conn.getFastpathAPI();

        // Now get the function oid's for the api
        //
        // This is an example of Fastpath.addFunctions();
        //
        String sql;
        if (conn.getMetaData().supportsSchemasInTableDefinitions())
        {
            sql = "SELECT p.proname,p.oid " +
                  " FROM pg_catalog.pg_proc p, pg_catalog.pg_namespace n " +
                  " WHERE p.pronamespace=n.oid AND n.nspname='pg_catalog' AND (";
        }
        else
        {
            sql = "SELECT proname,oid FROM pg_proc WHERE ";
        }
        sql += " proname = 'lo_open'" +
               " or proname = 'lo_close'" +
               " or proname = 'lo_creat'" +
               " or proname = 'lo_unlink'" +
               " or proname = 'lo_lseek'" +
               " or proname = 'lo_tell'" +
               " or proname = 'loread'" +
               " or proname = 'lowrite'" +
               " or proname = 'lo_truncate'";

        if (conn.getMetaData().supportsSchemasInTableDefinitions())
        {
            sql += ")";
        }

        ResultSet res = conn.createStatement().executeQuery(sql);

        if (res == null)
            throw new PSQLException(GT.tr("Failed to initialize LargeObject API"), PSQLState.SYSTEM_ERROR);

        fp.addFunctions(res);
        res.close();

        conn.getLogger().debug("Large Object initialised");
    }

    /**
     * This opens an existing large object, based on its OID. This method
     * assumes that READ and WRITE access is required (the default).
     *
     * @param oid of large object
     * @return LargeObject instance providing access to the object
     * @exception SQLException on error
     * @deprecated As of 8.3, replaced by {@link #open(long)}
     */
    public LargeObject open(int oid) throws SQLException
    {
        return open((long)oid);
    }

    /**
     * This opens an existing large object, based on its OID. This method
     * assumes that READ and WRITE access is required (the default).
     *
     * @param oid of large object
     * @return LargeObject instance providing access to the object
     * @exception SQLException on error
     */
    public LargeObject open(long oid) throws SQLException
    {
        return open(oid, READWRITE);
    }

    /**
     * This opens an existing large object, based on its OID
     *
     * @param oid of large object
     * @param mode mode of open
     * @return LargeObject instance providing access to the object
     * @exception SQLException on error
     * @deprecated As of 8.3, replaced by {@link #open(long, int)}
     */
    public LargeObject open(int oid, int mode) throws SQLException
    {
        return open((long)oid, mode);
    }

    /**
     * This opens an existing large object, based on its OID
     *
     * @param oid of large object
     * @param mode mode of open
     * @return LargeObject instance providing access to the object
     * @exception SQLException on error
     */
    public LargeObject open(long oid, int mode) throws SQLException
    {
        if (conn.getAutoCommit())
            throw new PSQLException(GT.tr("Large Objects may not be used in auto-commit mode."),
                                    PSQLState.NO_ACTIVE_SQL_TRANSACTION);
        return new LargeObject(fp, oid, mode);
    }

    /**
     * This creates a large object, returning its OID.
     *
     * <p>It defaults to READWRITE for the new object's attributes.
     *
     * @return oid of new object
     * @exception SQLException on error
     * @deprecated As of 8.3, replaced by {@link #createLO()}
     */
    public int create() throws SQLException
    {
        return create(READWRITE);
    }

    /**
     * This creates a large object, returning its OID.
     *
     * <p>It defaults to READWRITE for the new object's attributes.
     *
     * @return oid of new object
     */
    public long createLO() throws SQLException
    {
        return createLO(READWRITE);
    }

    /**
     * This creates a large object, returning its OID
     *
     * @param mode a bitmask describing different attributes of the new object
     * @return oid of new object
     * @exception SQLException on error
     */
    public long createLO(int mode) throws SQLException
    {
        if (conn.getAutoCommit())
            throw new PSQLException(GT.tr("Large Objects may not be used in auto-commit mode."),
                                    PSQLState.NO_ACTIVE_SQL_TRANSACTION);
        FastpathArg args[] = new FastpathArg[1];
        args[0] = new FastpathArg(mode);
        return fp.getOID("lo_creat", args);
    }

    /**
     * This creates a large object, returning its OID
     *
     * @param mode a bitmask describing different attributes of the new object
     * @return oid of new object
     * @exception SQLException on error
     * @deprecated As of 8.3, replaced by {@link #createLO(int)}
     */
    public int create(int mode) throws SQLException
    {
        long oid = createLO(mode);
        return (int)oid;
    }

    /**
     * This deletes a large object.
     *
     * @param oid describing object to delete
     * @exception SQLException on error
     */
    public void delete(long oid) throws SQLException
    {
        FastpathArg args[] = new FastpathArg[1];
        args[0] = Fastpath.createOIDArg(oid);
        fp.fastpath("lo_unlink", false, args);
    }

    /**
     * This deletes a large object.
     *
     * <p>It is identical to the delete method, and is supplied as the C API uses
     * unlink.
     *
     * @param oid describing object to delete
     * @exception SQLException on error
     * @deprecated As of 8.3, replaced by {@link #unlink(long)}
     */
    public void unlink(int oid) throws SQLException
    {
        delete((long)oid);
    }

    /**
     * This deletes a large object.
     *
     * <p>It is identical to the delete method, and is supplied as the C API uses
     * unlink.
     *
     * @param oid describing object to delete
     * @exception SQLException on error
     */
    public void unlink(long oid) throws SQLException
    {
        delete(oid);
    }

    /**
     * This deletes a large object.
     *
     * @param oid describing object to delete
     * @exception SQLException on error
     * @deprecated As of 8.3, replaced by {@link #delete(long)}
     */
    public void delete(int oid) throws SQLException
    {
        delete((long)oid);
    }

}