Class LargeObject

  • All Implemented Interfaces:
    java.lang.AutoCloseable

    public class LargeObject
    extends java.lang.Object
    implements java.lang.AutoCloseable

    This class provides the basic methods required to run the interface, plus a pair of methods that provide InputStream and OutputStream classes for this object.

    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.

    However, sometimes lower level access to Large Objects are required, that are not supported by the JDBC specification.

    Refer to org.postgresql.largeobject.LargeObjectManager on how to gain access to a Large Object, or how to create one.

    See Also:
    LargeObjectManager, ResultSet.getAsciiStream(int), ResultSet.getBinaryStream(int), ResultSet.getUnicodeStream(int), PreparedStatement.setAsciiStream(int, java.io.InputStream, int), PreparedStatement.setBinaryStream(int, java.io.InputStream, int), PreparedStatement.setUnicodeStream(int, java.io.InputStream, int)
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int SEEK_CUR
      Indicates a seek from the current position.
      static int SEEK_END
      Indicates a seek from the end of a file.
      static int SEEK_SET
      Indicates a seek from the beginning of a file.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected LargeObject​(Fastpath fp, long oid, int mode)
      This opens a large object.
      protected LargeObject​(Fastpath fp, long oid, int mode, BaseConnection conn, boolean commitOnClose)
      This opens a large object.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void close()
      This method closes the object.
      LargeObject copy()  
      java.io.InputStream getInputStream()
      Returns an InputStream from this object.
      java.io.InputStream getInputStream​(long limit)
      Returns an InputStream from this object, that will limit the amount of data that is visible.
      long getLongOID()  
      int getOID()
      Deprecated.
      As of 8.3, replaced by getLongOID()
      java.io.OutputStream getOutputStream()
      Returns an OutputStream to this object.
      int read​(byte[] buf, int off, int len)
      Reads some data from the object into an existing array.
      byte[] read​(int len)
      Reads some data from the object, and return as a byte[] array.
      void seek​(int pos)
      Sets the current position within the object.
      void seek​(int pos, int ref)
      Sets the current position within the object.
      void seek64​(long pos, int ref)
      Sets the current position within the object using 64-bit value (9.3+).
      int size()
      This method is inefficient, as the only way to find out the size of the object is to seek to the end, record the current position, then return to the original position.
      long size64()
      See #size() for information about efficiency.
      int tell()  
      long tell64()  
      void truncate​(int len)
      Truncates the large object to the given length in bytes.
      void truncate64​(long len)
      Truncates the large object to the given length in bytes.
      void write​(byte[] buf)
      Writes an array to the object.
      void write​(byte[] buf, int off, int len)
      Writes some data from an array to the object.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • SEEK_SET

        public static final int SEEK_SET
        Indicates a seek from the beginning of a file.
        See Also:
        Constant Field Values
      • SEEK_CUR

        public static final int SEEK_CUR
        Indicates a seek from the current position.
        See Also:
        Constant Field Values
      • SEEK_END

        public static final int SEEK_END
        Indicates a seek from the end of a file.
        See Also:
        Constant Field Values
    • Constructor Detail

      • LargeObject

        protected LargeObject​(Fastpath fp,
                              long oid,
                              int mode,
                              BaseConnection conn,
                              boolean commitOnClose)
                       throws java.sql.SQLException

        This opens a large object.

        If the object does not exist, then an SQLException is thrown.

        Parameters:
        fp - FastPath API for the connection to use
        oid - of the Large Object to open
        mode - Mode of opening the large object
        conn - the connection to the database used to access this LOB
        commitOnClose - commit the transaction when this LOB will be closed (defined in LargeObjectManager)
        Throws:
        java.sql.SQLException - if a database-access error occurs.
        See Also:
        LargeObjectManager
      • LargeObject

        protected LargeObject​(Fastpath fp,
                              long oid,
                              int mode)
                       throws java.sql.SQLException

        This opens a large object.

        If the object does not exist, then an SQLException is thrown.

        Parameters:
        fp - FastPath API for the connection to use
        oid - of the Large Object to open
        mode - Mode of opening the large object (defined in LargeObjectManager)
        Throws:
        java.sql.SQLException - if a database-access error occurs.
        See Also:
        LargeObjectManager
    • Method Detail

      • copy

        public LargeObject copy()
                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException
      • getOID

        @Deprecated
        public int getOID()
        Deprecated.
        As of 8.3, replaced by getLongOID()
        Returns:
        the OID of this LargeObject
      • getLongOID

        public long getLongOID()
        Returns:
        the OID of this LargeObject
      • close

        public void close()
                   throws java.sql.SQLException
        This method closes the object. You must not call methods in this object after this is called.
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • read

        public byte[] read​(int len)
                    throws java.sql.SQLException
        Reads some data from the object, and return as a byte[] array.
        Parameters:
        len - number of bytes to read
        Returns:
        byte[] array containing data read
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • read

        public int read​(byte[] buf,
                        int off,
                        int len)
                 throws java.sql.SQLException
        Reads some data from the object into an existing array.
        Parameters:
        buf - destination array
        off - offset within array
        len - number of bytes to read
        Returns:
        the number of bytes actually read
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • write

        public void write​(byte[] buf)
                   throws java.sql.SQLException
        Writes an array to the object.
        Parameters:
        buf - array to write
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • write

        public void write​(byte[] buf,
                          int off,
                          int len)
                   throws java.sql.SQLException
        Writes some data from an array to the object.
        Parameters:
        buf - destination array
        off - offset within array
        len - number of bytes to write
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • seek

        public void seek​(int pos,
                         int ref)
                  throws java.sql.SQLException

        Sets the current position within the object.

        This is similar to the fseek() call in the standard C library. It allows you to have random access to the large object.

        Parameters:
        pos - position within object
        ref - Either SEEK_SET, SEEK_CUR or SEEK_END
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • seek64

        public void seek64​(long pos,
                           int ref)
                    throws java.sql.SQLException
        Sets the current position within the object using 64-bit value (9.3+).
        Parameters:
        pos - position within object
        ref - Either SEEK_SET, SEEK_CUR or SEEK_END
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • seek

        public void seek​(int pos)
                  throws java.sql.SQLException

        Sets the current position within the object.

        This is similar to the fseek() call in the standard C library. It allows you to have random access to the large object.

        Parameters:
        pos - position within object from beginning
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • tell

        public int tell()
                 throws java.sql.SQLException
        Returns:
        the current position within the object
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • tell64

        public long tell64()
                    throws java.sql.SQLException
        Returns:
        the current position within the object
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • size

        public int size()
                 throws java.sql.SQLException

        This method is inefficient, as the only way to find out the size of the object is to seek to the end, record the current position, then return to the original position.

        A better method will be found in the future.

        Returns:
        the size of the large object
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • size64

        public long size64()
                    throws java.sql.SQLException
        See #size() for information about efficiency.
        Returns:
        the size of the large object
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • truncate

        public void truncate​(int len)
                      throws java.sql.SQLException
        Truncates the large object to the given length in bytes. If the number of bytes is larger than the current large object length, the large object will be filled with zero bytes. This method does not modify the current file offset.
        Parameters:
        len - given length in bytes
        Throws:
        java.sql.SQLException - if something goes wrong
      • truncate64

        public void truncate64​(long len)
                        throws java.sql.SQLException
        Truncates the large object to the given length in bytes. If the number of bytes is larger than the current large object length, the large object will be filled with zero bytes. This method does not modify the current file offset.
        Parameters:
        len - given length in bytes
        Throws:
        java.sql.SQLException - if something goes wrong
      • getInputStream

        public java.io.InputStream getInputStream()
                                           throws java.sql.SQLException

        Returns an InputStream from this object.

        This InputStream can then be used in any method that requires an InputStream.

        Returns:
        InputStream from this object
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • getInputStream

        public java.io.InputStream getInputStream​(long limit)
                                           throws java.sql.SQLException
        Returns an InputStream from this object, that will limit the amount of data that is visible.
        Parameters:
        limit - maximum number of bytes the resulting stream will serve
        Returns:
        InputStream from this object
        Throws:
        java.sql.SQLException - if a database-access error occurs.
      • getOutputStream

        public java.io.OutputStream getOutputStream()
                                             throws java.sql.SQLException

        Returns an OutputStream to this object.

        This OutputStream can then be used in any method that requires an OutputStream.

        Returns:
        OutputStream from this object
        Throws:
        java.sql.SQLException - if a database-access error occurs.