granicus.if.org Git - postgresql/blob - src/interfaces/jdbc/org/postgresql/largeobject/LargeObjectManager.java

   1 package org.postgresql.largeobject;
   2
   3 import org.postgresql.Driver;
   4 import java.io.*;
   5 import java.lang.*;
   6 import java.net.*;
   7 import java.util.*;
   8 import java.sql.*;
   9
  10 import org.postgresql.fastpath.*;
  11 import org.postgresql.util.*;
  12
  13 /*
  14  * This class implements the large object interface to org.postgresql.
  15  *
  16  * <p>It provides methods that allow client code to create, open and delete
  17  * large objects from the database. When opening an object, an instance of
  18  * org.postgresql.largeobject.LargeObject is returned, and its methods then allow
  19  * access to the object.
  20  *
  21  * <p>This class can only be created by org.postgresql.Connection
  22  *
  23  * <p>To get access to this class, use the following segment of code:
  24  * <br><pre>
  25  * import org.postgresql.largeobject.*;
  26  *
  27  * Connection  conn;
  28  * LargeObjectManager lobj;
  29  *
  30  * ... code that opens a connection ...
  31  *
  32  * lobj = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
  33  * </pre>
  34  *
  35  * <p>Normally, client code would use the getAsciiStream, getBinaryStream,
  36  * or getUnicodeStream methods in ResultSet, or setAsciiStream,
  37  * setBinaryStream, or setUnicodeStream methods in PreparedStatement to
  38  * access Large Objects.
  39  *
  40  * <p>However, sometimes lower level access to Large Objects are required,
  41  * that are not supported by the JDBC specification.
  42  *
  43  * <p>Refer to org.postgresql.largeobject.LargeObject on how to manipulate the
  44  * contents of a Large Object.
  45  *
  46  * @see org.postgresql.largeobject.LargeObject
  47  * @see org.postgresql.ResultSet#getAsciiStream
  48  * @see org.postgresql.ResultSet#getBinaryStream
  49  * @see org.postgresql.ResultSet#getUnicodeStream
  50  * @see org.postgresql.PreparedStatement#setAsciiStream
  51  * @see org.postgresql.PreparedStatement#setBinaryStream
  52  * @see org.postgresql.PreparedStatement#setUnicodeStream
  53  * @see java.sql.ResultSet#getAsciiStream
  54  * @see java.sql.ResultSet#getBinaryStream
  55  * @see java.sql.ResultSet#getUnicodeStream
  56  * @see java.sql.PreparedStatement#setAsciiStream
  57  * @see java.sql.PreparedStatement#setBinaryStream
  58  * @see java.sql.PreparedStatement#setUnicodeStream
  59  */
  60 public class LargeObjectManager
  61 {
  62         // the fastpath api for this connection
  63         private Fastpath fp;
  64
  65         /*
  66          * This mode indicates we want to write to an object
  67          */
  68         public static final int WRITE = 0x00020000;
  69
  70         /*
  71          * This mode indicates we want to read an object
  72          */
  73         public static final int READ = 0x00040000;
  74
  75         /*
  76          * This mode is the default. It indicates we want read and write access to
  77          * a large object
  78          */
  79         public static final int READWRITE = READ | WRITE;
  80
  81         /*
  82          * This prevents us being created by mere mortals
  83          */
  84         private LargeObjectManager()
  85         {}
  86
  87         /*
  88          * Constructs the LargeObject API.
  89          *
  90          * <p><b>Important Notice</b>
  91          * <br>This method should only be called by org.postgresql.Connection
  92          *
  93          * <p>There should only be one LargeObjectManager per Connection. The
  94          * org.postgresql.Connection class keeps track of the various extension API's
  95          * and it's advised you use those to gain access, and not going direct.
  96          */
  97         public LargeObjectManager(Connection conn) throws SQLException
  98         {
  99                 // We need Fastpath to do anything
 100                 this.fp = ((org.postgresql.PGConnection)conn).getFastpathAPI();
 101
 102                 // Now get the function oid's for the api
 103                 //
 104                 // This is an example of Fastpath.addFunctions();
 105                 //
 106                 String sql;
 107                 if (conn.getMetaData().supportsSchemasInTableDefinitions()) {
 108                         sql = "SELECT p.proname,p.oid "+
 109                                 " FROM pg_catalog.pg_proc p, pg_catalog.pg_namespace n "+
 110                                 " WHERE p.pronamespace=n.oid AND n.nspname='pg_catalog' AND ";
 111                 } else {
 112                         sql = "SELECT proname,oid FROM pg_proc WHERE ";
 113                 }
 114                 sql += " proname = 'lo_open'" +
 115                         " or proname = 'lo_close'" +
 116                         " or proname = 'lo_creat'" +
 117                         " or proname = 'lo_unlink'" +
 118                         " or proname = 'lo_lseek'" +
 119                         " or proname = 'lo_tell'" +
 120                         " or proname = 'loread'" +
 121                         " or proname = 'lowrite'";
 122
 123                 ResultSet res = conn.createStatement().executeQuery(sql);
 124
 125                 if (res == null)
 126                         throw new PSQLException("postgresql.lo.init");
 127
 128                 fp.addFunctions(res);
 129                 res.close();
 130                 if (Driver.logDebug)
 131                         Driver.debug("Large Object initialised");
 132         }
 133
 134         /*
 135          * This opens an existing large object, based on its OID. This method
 136          * assumes that READ and WRITE access is required (the default).
 137          *
 138          * @param oid of large object
 139          * @return LargeObject instance providing access to the object
 140          * @exception SQLException on error
 141          */
 142         public LargeObject open(int oid) throws SQLException
 143         {
 144                 return new LargeObject(fp, oid, READWRITE);
 145         }
 146
 147         /*
 148          * This opens an existing large object, based on its OID
 149          *
 150          * @param oid of large object
 151          * @param mode mode of open
 152          * @return LargeObject instance providing access to the object
 153          * @exception SQLException on error
 154          */
 155         public LargeObject open(int oid, int mode) throws SQLException
 156         {
 157                 return new LargeObject(fp, oid, mode);
 158         }
 159
 160         /*
 161          * This creates a large object, returning its OID.
 162          *
 163          * <p>It defaults to READWRITE for the new object's attributes.
 164          *
 165          * @return oid of new object
 166          * @exception SQLException on error
 167          */
 168         public int create() throws SQLException
 169         {
 170                 FastpathArg args[] = new FastpathArg[1];
 171                 args[0] = new FastpathArg(READWRITE);
 172                 return fp.getInteger("lo_creat", args);
 173         }
 174
 175         /*
 176          * This creates a large object, returning its OID
 177          *
 178          * @param mode a bitmask describing different attributes of the new object
 179          * @return oid of new object
 180          * @exception SQLException on error
 181          */
 182         public int create(int mode) throws SQLException
 183         {
 184                 FastpathArg args[] = new FastpathArg[1];
 185                 args[0] = new FastpathArg(mode);
 186                 return fp.getInteger("lo_creat", args);
 187         }
 188
 189         /*
 190          * This deletes a large object.
 191          *
 192          * @param oid describing object to delete
 193          * @exception SQLException on error
 194          */
 195         public void delete(int oid) throws SQLException
 196         {
 197                 FastpathArg args[] = new FastpathArg[1];
 198                 args[0] = new FastpathArg(oid);
 199                 fp.fastpath("lo_unlink", false, args);
 200         }
 201
 202         /*
 203          * This deletes a large object.
 204          *
 205          * <p>It is identical to the delete method, and is supplied as the C API uses
 206          * unlink.
 207          *
 208          * @param oid describing object to delete
 209          * @exception SQLException on error
 210          */
 211         public void unlink(int oid) throws SQLException
 212         {
 213                 delete(oid);
 214         }
 215
 216 }