com.foundationdb.sql.jdbc.largeobject

## Class LargeObject

- java.lang.Object
- - com.foundationdb.sql.jdbc.largeobject.LargeObject

    public class LargeObject
    extends java.lang.Object

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
`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 begining of a file

### Constructor Summary

Constructors
`protected` `LargeObject(Fastpath fp, long oid, int mode)` This opens a large object.
`protected` `LargeObject(Fastpath fp, long oid, int mode, com.foundationdb.sql.jdbc.core.BaseConnection conn, boolean commitOnClose)` This opens a large object.

### Method Summary

Methods
`void` `close()` This method closes the object.
`LargeObject` `copy()`
`java.io.InputStream` `getInputStream()` Returns an InputStream from this object.
`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.
`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.
`int` `tell()`
`void` `truncate(int 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 begining 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,
               com.foundationdb.sql.jdbc.core.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

    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.

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.

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

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

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

Throws:
  `java.sql.SQLException`

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

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.

Throws:
  `java.sql.SQLException` - if a database-access error occurs.