org.postgresql.largeobject.LargeObjectManager Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of postgresql-holo Show documentation
Show all versions of postgresql-holo Show documentation
PostgreSQL JDBC Driver Postgresql
The newest version!
/*
* Copyright (c) 2003, PostgreSQL Global Development Group
* See the LICENSE file in the project root for more information.
*/
package org.postgresql.largeobject;
import org.postgresql.core.BaseConnection;
import org.postgresql.fastpath.Fastpath;
import org.postgresql.fastpath.FastpathArg;
import org.postgresql.util.GT;
import org.postgresql.util.PSQLException;
import org.postgresql.util.PSQLState;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.logging.Level;
/**
* This class implements the large object interface to org.postgresql.
*
* It provides methods that allow client code to create, open and delete large objects from the
* database. When opening an object, an instance of org.postgresql.largeobject.LargeObject is
* returned, and its methods then allow access to the object.
*
* This class can only be created by {@link BaseConnection}
*
* To get access to this class, use the following segment of code:
*
*
* import org.postgresql.largeobject.*;
*
* Connection conn;
* LargeObjectManager lobj;
*
* ... code that opens a connection ...
*
* lobj = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
*
*
* 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.LargeObject on how to manipulate the contents of a Large
* Object.
*
* @see java.sql.ResultSet#getAsciiStream
* @see java.sql.ResultSet#getBinaryStream
* @see java.sql.ResultSet#getUnicodeStream
* @see java.sql.PreparedStatement#setAsciiStream
* @see java.sql.PreparedStatement#setBinaryStream
* @see java.sql.PreparedStatement#setUnicodeStream
*/
public class LargeObjectManager {
// the fastpath api for this connection
private Fastpath fp;
private BaseConnection conn;
/**
* This mode indicates we want to write to an object.
*/
public static final int WRITE = 0x00020000;
/**
* This mode indicates we want to read an object.
*/
public static final int READ = 0x00040000;
/**
* This mode is the default. It indicates we want read and write access to a large object.
*/
public static final int READWRITE = READ | WRITE;
/**
* Constructs the LargeObject API.
*
* Important Notice
* This method should only be called by {@link BaseConnection}
*
* There should only be one LargeObjectManager per Connection. The {@link BaseConnection} class
* keeps track of the various extension API's and it's advised you use those to gain access, and
* not going direct.
*
* @param conn connection
* @throws SQLException if something wrong happens
*/
public LargeObjectManager(BaseConnection conn) throws SQLException {
this.conn = conn;
// We need Fastpath to do anything
this.fp = conn.getFastpathAPI();
// Now get the function oid's for the api
//
// This is an example of Fastpath.addFunctions();
//
String sql;
if (conn.getMetaData().supportsSchemasInTableDefinitions()) {
sql = "SELECT p.proname,p.oid "
+ " FROM pg_catalog.pg_proc p, pg_catalog.pg_namespace n "
+ " WHERE p.pronamespace=n.oid AND n.nspname='pg_catalog' AND (";
} else {
sql = "SELECT proname,oid FROM pg_proc WHERE ";
}
sql += " proname = 'lo_open'"
+ " or proname = 'lo_close'"
+ " or proname = 'lo_creat'"
+ " or proname = 'lo_unlink'"
+ " or proname = 'lo_lseek'"
+ " or proname = 'lo_lseek64'"
+ " or proname = 'lo_tell'"
+ " or proname = 'lo_tell64'"
+ " or proname = 'loread'"
+ " or proname = 'lowrite'"
+ " or proname = 'lo_truncate'"
+ " or proname = 'lo_truncate64'";
if (conn.getMetaData().supportsSchemasInTableDefinitions()) {
sql += ")";
}
Statement stmt = conn.createStatement();
ResultSet res = stmt.executeQuery(sql);
fp.addFunctions(res);
res.close();
stmt.close();
conn.getLogger().log(Level.FINE, "Large Object initialised");
}
/**
* This opens an existing large object, based on its OID. This method assumes that READ and WRITE
* access is required (the default).
*
* @param oid of large object
* @return LargeObject instance providing access to the object
* @throws SQLException on error
* @deprecated As of 8.3, replaced by {@link #open(long)}
*/
@Deprecated
public LargeObject open(int oid) throws SQLException {
return open((long) oid, false);
}
/**
* This opens an existing large object, same as previous method, but commits the transaction on
* close if asked. This is useful when the LOB is returned to a caller which won't take care of
* transactions by itself.
*
* @param oid of large object
* @param commitOnClose commit the transaction when this LOB will be closed
* @return LargeObject instance providing access to the object
* @throws SQLException on error
*/
public LargeObject open(int oid, boolean commitOnClose) throws SQLException {
return open((long) oid, commitOnClose);
}
/**
* This opens an existing large object, based on its OID. This method assumes that READ and WRITE
* access is required (the default).
*
* @param oid of large object
* @return LargeObject instance providing access to the object
* @throws SQLException on error
*/
public LargeObject open(long oid) throws SQLException {
return open(oid, READWRITE, false);
}
/**
* This opens an existing large object, same as previous method, but commits the transaction on
* close if asked.
*
* @param oid of large object
* @param commitOnClose commit the transaction when this LOB will be closed
* @return LargeObject instance providing access to the object
* @throws SQLException on error
*/
public LargeObject open(long oid, boolean commitOnClose) throws SQLException {
return open(oid, READWRITE, commitOnClose);
}
/**
* This opens an existing large object, based on its OID.
*
* @param oid of large object
* @param mode mode of open
* @return LargeObject instance providing access to the object
* @throws SQLException on error
* @deprecated As of 8.3, replaced by {@link #open(long, int)}
*/
@Deprecated
public LargeObject open(int oid, int mode) throws SQLException {
return open((long) oid, mode, false);
}
/**
* This opens an existing large object, same as previous method, but commits the transaction on
* close if asked.
*
* @param oid of large object
* @param mode mode of open
* @param commitOnClose commit the transaction when this LOB will be closed
* @return LargeObject instance providing access to the object
* @throws SQLException on error
*/
public LargeObject open(int oid, int mode, boolean commitOnClose) throws SQLException {
return open((long) oid, mode, commitOnClose);
}
/**
* This opens an existing large object, based on its OID.
*
* @param oid of large object
* @param mode mode of open
* @return LargeObject instance providing access to the object
* @throws SQLException on error
*/
public LargeObject open(long oid, int mode) throws SQLException {
return open(oid, mode, false);
}
/**
* This opens an existing large object, based on its OID.
*
* @param oid of large object
* @param mode mode of open
* @param commitOnClose commit the transaction when this LOB will be closed
* @return LargeObject instance providing access to the object
* @throws SQLException on error
*/
public LargeObject open(long oid, int mode, boolean commitOnClose) throws SQLException {
if (conn.getAutoCommit()) {
throw new PSQLException(GT.tr("Large Objects may not be used in auto-commit mode."),
PSQLState.NO_ACTIVE_SQL_TRANSACTION);
}
return new LargeObject(fp, oid, mode, conn, commitOnClose);
}
/**
* This creates a large object, returning its OID.
*
* It defaults to READWRITE for the new object's attributes.
*
* @return oid of new object
* @throws SQLException on error
* @deprecated As of 8.3, replaced by {@link #createLO()}
*/
@Deprecated
public int create() throws SQLException {
return create(READWRITE);
}
/**
* This creates a large object, returning its OID.
*
* It defaults to READWRITE for the new object's attributes.
*
* @return oid of new object
* @throws SQLException if something wrong happens
*/
public long createLO() throws SQLException {
return createLO(READWRITE);
}
/**
* This creates a large object, returning its OID.
*
* @param mode a bitmask describing different attributes of the new object
* @return oid of new object
* @throws SQLException on error
*/
public long createLO(int mode) throws SQLException {
if (conn.getAutoCommit()) {
throw new PSQLException(GT.tr("Large Objects may not be used in auto-commit mode."),
PSQLState.NO_ACTIVE_SQL_TRANSACTION);
}
FastpathArg[] args = new FastpathArg[1];
args[0] = new FastpathArg(mode);
return fp.getOID("lo_creat", args);
}
/**
* This creates a large object, returning its OID.
*
* @param mode a bitmask describing different attributes of the new object
* @return oid of new object
* @throws SQLException on error
* @deprecated As of 8.3, replaced by {@link #createLO(int)}
*/
@Deprecated
public int create(int mode) throws SQLException {
long oid = createLO(mode);
return (int) oid;
}
/**
* This deletes a large object.
*
* @param oid describing object to delete
* @throws SQLException on error
*/
public void delete(long oid) throws SQLException {
FastpathArg[] args = new FastpathArg[1];
args[0] = Fastpath.createOIDArg(oid);
fp.fastpath("lo_unlink", args);
}
/**
* This deletes a large object.
*
* It is identical to the delete method, and is supplied as the C API uses unlink.
*
* @param oid describing object to delete
* @throws SQLException on error
* @deprecated As of 8.3, replaced by {@link #unlink(long)}
*/
@Deprecated
public void unlink(int oid) throws SQLException {
delete((long) oid);
}
/**
* This deletes a large object.
*
* It is identical to the delete method, and is supplied as the C API uses unlink.
*
* @param oid describing object to delete
* @throws SQLException on error
*/
public void unlink(long oid) throws SQLException {
delete(oid);
}
/**
* This deletes a large object.
*
* @param oid describing object to delete
* @throws SQLException on error
* @deprecated As of 8.3, replaced by {@link #delete(long)}
*/
@Deprecated
public void delete(int oid) throws SQLException {
delete((long) oid);
}
}