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 and 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 and 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 and 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 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,
                      @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 Detail

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.