Package org.postgresql.largeobject

Class LargeObject

java.lang.Object
org.postgresql.largeobject.LargeObject
All Implemented Interfaces:
AutoCloseable
public class LargeObject extends Object implements 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:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    SEEK_CUR
    Indicates a seek from the current position.
    static final int
    SEEK_END
    Indicates a seek from the end of a file.
    static final 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, @Nullable BaseConnection conn, boolean commitOnClose)
    This opens a large object.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    This method closes the object.
    LargeObject
    copy()
     
    InputStream
    getInputStream()
    Returns an InputStream from this object.
    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()
    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 Details

    • SEEK_SET

      public static final int SEEK_SET
      Indicates a seek from the beginning of a file.
      See Also:

    • SEEK_CUR

      public static final int SEEK_CUR
      Indicates a seek from the current position.
      See Also:

    • SEEK_END

      public static final int SEEK_END
      Indicates a seek from the end of a file.
      See Also:

  • Constructor Details

    • LargeObject

      protected LargeObject(Fastpath fp, long oid, int mode, @Nullable BaseConnection conn, boolean commitOnClose) throws 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:
      SQLException - if a database-access error occurs.
      See Also:

    • LargeObject

      protected LargeObject(Fastpath fp, long oid, int mode) throws 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:
      SQLException - if a database-access error occurs.
      See Also:

  • Method Details

    • copy

      public LargeObject copy() throws SQLException
      Throws:
      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 SQLException
      This method closes the object. You must not call methods in this object after this is called.
      Specified by:
      close in interface AutoCloseable
      Throws:
      SQLException - if a database-access error occurs.

    • read

      public byte[] read(int len) throws 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:
      SQLException - if a database-access error occurs.

    • read

      public int read(byte[] buf, int off, int len) throws 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:
      SQLException - if a database-access error occurs.

    • write

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

    • write

      public void write(byte[] buf, int off, int len) throws 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:
      SQLException - if a database-access error occurs.

    • seek

      public void seek(int pos, int ref) throws 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:
      SQLException - if a database-access error occurs.

    • seek64

      public void seek64(long pos, int ref) throws 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:
      SQLException - if a database-access error occurs.

    • seek

      public void seek(int pos) throws 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:
      SQLException - if a database-access error occurs.

    • tell

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

    • tell64

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

    • size

      public int size() throws 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:
      SQLException - if a database-access error occurs.

    • size64

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

    • truncate

      public void truncate(int len) throws 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:
      SQLException - if something goes wrong

    • truncate64

      public void truncate64(long len) throws 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:
      SQLException - if something goes wrong

    • getInputStream

      public InputStream getInputStream() throws 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:
      SQLException - if a database-access error occurs.

    • getInputStream

      public InputStream getInputStream(long limit) throws 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:
      SQLException - if a database-access error occurs.

    • getOutputStream

      public OutputStream getOutputStream() throws 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:
      SQLException - if a database-access error occurs.