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

Class LargeObject

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

SEEK_SET

SEEK_CUR

SEEK_END

Constructor Details

LargeObject

LargeObject

Method Details

copy

getOID

getLongOID

close

read

read

write

write

write

seek

seek64

seek

tell

tell64

size

size64

truncate

truncate64

getInputStream

getInputStream

getInputStream

getOutputStream