Top Description Fields Constructors Methods
org.postgresql.largeobject

public Class LargeObject

extends Object
implements AutoCloseable
Class Inheritance
All Implemented Interfaces
java.lang.AutoCloseable
Annotations
@SuppressWarnings:deprecation
Imports
org.postgresql.core.BaseConnection, org.postgresql.fastpath.Fastpath, .FastpathArg, org.postgresql.util.ByteStreamWriter, .PSQLException, .PSQLState, org.checkerframework.checker.nullness.qual.Nullable, java.io.IOException, .InputStream, .OutputStream, java.sql.SQLException

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
org.postgresql.largeobject.LargeObjectManager, java.sql.ResultSet#getAsciiStream, java.sql.ResultSet#getBinaryStream, java.sql.ResultSet#getUnicodeStream, java.sql.PreparedStatement#setAsciiStream, java.sql.PreparedStatement#setBinaryStream, java.sql.PreparedStatement#setUnicodeStream

Field Summary

Modifier and TypeField and Description
private boolean
closed

private final boolean
commitOnClose

private @Nullable BaseConnection
conn

private static final byte[]
EMPTY_BYTE_ARRAY

private final int
fd

private final Fastpath
fp

References Deprecated Fastpath is deprecated or references (maybe indirectly) at least one deprecated element.
private final int
mode

private final long
oid

private @Nullable BlobOutputStream
os

public static final int
SEEK_CUR

Indicates a seek from the current position.

public static final int
SEEK_END

Indicates a seek from the end of a file.

public static final int
SEEK_SET

Indicates a seek from the beginning of a file.

Constructor Summary

AccessConstructor and Description
protected
LargeObject(Fastpath
FastPath API for the connection to use
fp, long
of the Large Object to open
oid, int
Mode of opening the large object
mode, @Nullable BaseConnection
the connection to the database used to access this LOB
conn, boolean
commit the transaction when this LOB will be closed (defined in LargeObjectManager)
commitOnClose)
References Deprecated Fastpath is deprecated or references (maybe indirectly) at least one deprecated element.

This opens a large object.

protected
LargeObject(Fastpath
FastPath API for the connection to use
fp, long
of the Large Object to open
oid, int
Mode of opening the large object (defined in LargeObjectManager)
mode)
References Deprecated Fastpath is deprecated or references (maybe indirectly) at least one deprecated element.

This opens a large object.

Method Summary

Modifier and TypeMethod and Description
public void
close()

Implements java.lang.AutoCloseable.close.

This method closes the object.

public LargeObject
copy()

public InputStream

Returns:

InputStream from this object
getInputStream()

Returns an InputStream from this object.

public InputStream

Returns:

InputStream from this object
getInputStream(long
maximum number of bytes the resulting stream will serve
limit)

Returns an InputStream from this object, that will limit the amount of data that is visible.

public InputStream

Returns:

InputStream from this object
getInputStream(int
buffer size for the stream
bufferSize, long
maximum number of bytes the resulting stream will serve
limit)

Returns an InputStream from this object, that will limit the amount of data that is visible.

public long

Returns:

the OID of this LargeObject
getLongOID()

public int

Returns:

the OID of this LargeObject
getOID()
Deprecated As of 8.3, replaced by getLongOID()

public OutputStream

Returns:

OutputStream from this object
getOutputStream()

Returns an OutputStream to this object.

public byte[]

Returns:

byte[] array containing data read
read(int
number of bytes to read
len)

Reads some data from the object, and return as a byte[] array.

public int

Returns:

the number of bytes actually read
read(byte[]
destination array
buf, int
offset within array
off, int
number of bytes to read
len)

Reads some data from the object into an existing array.

public void
seek(int
position within object
pos, int
Either SEEK_SET, SEEK_CUR or SEEK_END
ref)

Sets the current position within the object.

public void
seek(int
position within object from beginning
pos)

Sets the current position within the object.

public void
seek64(long
position within object
pos, int
Either SEEK_SET, SEEK_CUR or SEEK_END
ref)

Sets the current position within the object using 64-bit value (9.3+).

public int

Returns:

the size of the large object
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.

public long

Returns:

the size of the large object
size64()

See #size() for information about efficiency.

public int

Returns:

the current position within the object
tell()

public long

Returns:

the current position within the object
tell64()

public void
truncate(int
given length in bytes
len)

Truncates the large object to the given length in bytes.

public void
truncate64(long
given length in bytes
len)

Truncates the large object to the given length in bytes.

public void
write(byte[]
array to write
buf)

Writes an array to the object.

public void
write(byte[]
destination array
buf, int
offset within array
off, int
number of bytes to write
len)

Writes some data from an array to the object.

public void
write(ByteStreamWriter
the source of the data to write
writer)

Writes some data from a given writer to the object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

closedback to summary
private boolean closed
commitOnCloseback to summary
private final boolean commitOnClose
connback to summary
private @Nullable BaseConnection conn
EMPTY_BYTE_ARRAYback to summary
private static final byte[] EMPTY_BYTE_ARRAY
fdback to summary
private final int fd
fpback to summary
private final Fastpath fp

References Deprecated

Fastpath is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

modeback to summary
private final int mode
oidback to summary
private final long oid
osback to summary
private @Nullable BlobOutputStream os
SEEK_CURback to summary
public static final int SEEK_CUR

Indicates a seek from the current position.

SEEK_ENDback to summary
public static final int SEEK_END

Indicates a seek from the end of a file.

SEEK_SETback to summary
public static final int SEEK_SET

Indicates a seek from the beginning of a file.

Constructor Detail

LargeObjectback to summary
protected LargeObject(Fastpath fp, long oid, int mode, @Nullable BaseConnection conn, boolean commitOnClose) throws SQLException

References Deprecated

Fastpath is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

This opens a large object.

If the object does not exist, then an SQLException is thrown.

Parameters
fp:Fastpath

FastPath API for the connection to use

oid:long

of the Large Object to open

mode:int

Mode of opening the large object

conn:@Nullable BaseConnection

the connection to the database used to access this LOB

commitOnClose:boolean

commit the transaction when this LOB will be closed (defined in LargeObjectManager)

Exceptions
SQLException:
if a database-access error occurs.
See Also
org.postgresql.largeobject.LargeObjectManager
LargeObjectback to summary
protected LargeObject(Fastpath fp, long oid, int mode) throws SQLException

References Deprecated

Fastpath is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

This opens a large object.

If the object does not exist, then an SQLException is thrown.

Parameters
fp:Fastpath

FastPath API for the connection to use

oid:long

of the Large Object to open

mode:int

Mode of opening the large object (defined in LargeObjectManager)

Exceptions
SQLException:
if a database-access error occurs.
See Also
org.postgresql.largeobject.LargeObjectManager

Method Detail

closeback to summary
public void close() throws SQLException

Implements java.lang.AutoCloseable.close.

This method closes the object. You must not call methods in this object after this is called.

Annotations
@Override
Exceptions
SQLException:
if a database-access error occurs.
copyback to summary
public LargeObject copy() throws SQLException
getInputStreamback to summary
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

InputStream from this object

Exceptions
SQLException:
if a database-access error occurs.
getInputStreamback to summary
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:long

maximum number of bytes the resulting stream will serve

Returns:InputStream

InputStream from this object

Exceptions
SQLException:
if a database-access error occurs.
getInputStreamback to summary
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:int

buffer size for the stream

limit:long

maximum number of bytes the resulting stream will serve

Returns:InputStream

InputStream from this object

Exceptions
SQLException:
if a database-access error occurs.
getLongOIDback to summary
public long getLongOID()
Returns:long

the OID of this LargeObject

getOIDback to summary
public int getOID()

Deprecated

As of 8.3, replaced by getLongOID()

Returns:int

the OID of this LargeObject

Annotations
@Deprecated
getOutputStreamback to summary
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

OutputStream from this object

Exceptions
SQLException:
if a database-access error occurs.
readback to summary
public byte[] read(int len) throws SQLException

Reads some data from the object, and return as a byte[] array.

Parameters
len:int

number of bytes to read

Returns:byte[]

byte[] array containing data read

Exceptions
SQLException:
if a database-access error occurs.
readback to summary
public int read(byte[] buf, int off, int len) throws SQLException

Reads some data from the object into an existing array.

Parameters
buf:byte[]

destination array

off:int

offset within array

len:int

number of bytes to read

Returns:int

the number of bytes actually read

Exceptions
SQLException:
if a database-access error occurs.
seekback to summary
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:int

position within object

ref:int

Either SEEK_SET, SEEK_CUR or SEEK_END

Exceptions
SQLException:
if a database-access error occurs.
seekback to summary
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:int

position within object from beginning

Exceptions
SQLException:
if a database-access error occurs.
seek64back to summary
public void seek64(long pos, int ref) throws SQLException

Sets the current position within the object using 64-bit value (9.3+).

Parameters
pos:long

position within object

ref:int

Either SEEK_SET, SEEK_CUR or SEEK_END

Exceptions
SQLException:
if a database-access error occurs.
sizeback to summary
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:int

the size of the large object

Exceptions
SQLException:
if a database-access error occurs.
size64back to summary
public long size64() throws SQLException

See #size() for information about efficiency.

Returns:long

the size of the large object

Exceptions
SQLException:
if a database-access error occurs.
tellback to summary
public int tell() throws SQLException
Returns:int

the current position within the object

Exceptions
SQLException:
if a database-access error occurs.
tell64back to summary
public long tell64() throws SQLException
Returns:long

the current position within the object

Exceptions
SQLException:
if a database-access error occurs.
truncateback to summary
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:int

given length in bytes

Exceptions
SQLException:
if something goes wrong
truncate64back to summary
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:long

given length in bytes

Exceptions
SQLException:
if something goes wrong
writeback to summary
public void write(byte[] buf) throws SQLException

Writes an array to the object.

Parameters
buf:byte[]

array to write

Exceptions
SQLException:
if a database-access error occurs.
writeback to summary
public void write(byte[] buf, int off, int len) throws SQLException

Writes some data from an array to the object.

Parameters
buf:byte[]

destination array

off:int

offset within array

len:int

number of bytes to write

Exceptions
SQLException:
if a database-access error occurs.
writeback to summary
public void write(ByteStreamWriter writer) throws SQLException

Writes some data from a given writer to the object.

Parameters
writer:ByteStreamWriter

the source of the data to write

Exceptions
SQLException:
if a database-access error occurs.