Class LargeObject
- java.lang.Object
-
- org.postgresql.largeobject.LargeObject
-
- All Implemented Interfaces:
java.lang.AutoCloseable
public class LargeObject extends java.lang.Object implements java.lang.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)
-
-
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, BaseConnection conn, boolean commitOnClose)
This opens a large object.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
close()
This method closes the object.LargeObject
copy()
java.io.InputStream
getInputStream()
Returns anInputStream
from this object.java.io.InputStream
getInputStream(long limit)
Returns anInputStream
from this object, that will limit the amount of data that is visible.long
getLongOID()
int
getOID()
Deprecated.As of 8.3, replaced bygetLongOID()
java.io.OutputStream
getOutputStream()
Returns anOutputStream
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.
-
-
-
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, 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 useoid
- of the Large Object to openmode
- Mode of opening the large objectconn
- the connection to the database used to access this LOBcommitOnClose
- 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 useoid
- of the Large Object to openmode
- 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
@Deprecated public int getOID()
Deprecated.As of 8.3, replaced bygetLongOID()
- 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.- Specified by:
close
in interfacejava.lang.AutoCloseable
- 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 arrayoff
- offset within arraylen
- 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 arrayoff
- offset within arraylen
- 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 objectref
- Either SEEK_SET, SEEK_CUR or SEEK_END- Throws:
java.sql.SQLException
- if a database-access error occurs.
-
seek64
public void seek64(long pos, int ref) throws java.sql.SQLException
Sets the current position within the object using 64-bit value (9.3+).- Parameters:
pos
- position within objectref
- 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 beginning- 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.
-
tell64
public long tell64() 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.
-
size64
public long size64() throws java.sql.SQLException
See #size() for information about efficiency.- 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.- Parameters:
len
- given length in bytes- Throws:
java.sql.SQLException
- if something goes wrong
-
truncate64
public void truncate64(long 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.- Parameters:
len
- given length in bytes- Throws:
java.sql.SQLException
- if something goes wrong
-
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.- Returns:
InputStream
from this object- Throws:
java.sql.SQLException
- if a database-access error occurs.
-
getInputStream
public java.io.InputStream getInputStream(long limit) throws java.sql.SQLException
Returns anInputStream
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:
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.
- Returns:
OutputStream
from this object- Throws:
java.sql.SQLException
- if a database-access error occurs.
-
-