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:
  - `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 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(int bufferSize, long limit)`
  Returns an `InputStream` from this object, that will limit the amount of data that is visible.
  `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.
  `void`
  `write(ByteStreamWriter writer)`
  Writes some data from a given writer 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:
      - 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 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:
      - `LargeObjectManager`

  - ### 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:
      - `LargeObjectManager`

- ## 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.

  - ### write

    public void write(ByteStreamWriter writer) throws SQLException
    Writes some data from a given writer to the object.
    Parameters:
      `writer` - the source of the data 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.

  - ### getInputStream

    public InputStream getInputStream(int bufferSize, long limit) throws SQLException
    Returns an `InputStream` from this object, that will limit the amount of data that is visible. Added mostly for testing
    Parameters:
      `bufferSize` - buffer size for the stream
      `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.