Source code: postgresql/largeobject/LargeObjectManager.java
1 package postgresql.largeobject;
2
3 import java.io.*;
4 import java.lang.*;
5 import java.net.*;
6 import java.util.*;
7 import java.sql.*;
8
9 import postgresql.fastpath.*;
10 import postgresql.util.*;
11
12 /**
13 * This class implements the large object interface to postgresql.
14 *
15 * <p>It provides methods that allow client code to create, open and delete
16 * large objects from the database. When opening an object, an instance of
17 * postgresql.largeobject.LargeObject is returned, and its methods then allow
18 * access to the object.
19 *
20 * <p>This class can only be created by postgresql.Connection
21 *
22 * <p>To get access to this class, use the following segment of code:
23 * <br><pre>
24 * import postgresql.largeobject.*;
25 *
26 * Connection conn;
27 * LargeObjectManager lobj;
28 *
29 * ... code that opens a connection ...
30 *
31 * lobj = ((postgresql.Connection)myconn).getLargeObjectAPI();
32 * </pre>
33 *
34 * <p>Normally, client code would use the getAsciiStream, getBinaryStream,
35 * or getUnicodeStream methods in ResultSet, or setAsciiStream,
36 * setBinaryStream, or setUnicodeStream methods in PreparedStatement to
37 * access Large Objects.
38 *
39 * <p>However, sometimes lower level access to Large Objects are required,
40 * that are not supported by the JDBC specification.
41 *
42 * <p>Refer to postgresql.largeobject.LargeObject on how to manipulate the
43 * contents of a Large Object.
44 *
45 * @see postgresql.largeobject.LargeObject
46 * @see postgresql.ResultSet#getAsciiStream
47 * @see postgresql.ResultSet#getBinaryStream
48 * @see postgresql.ResultSet#getUnicodeStream
49 * @see postgresql.PreparedStatement#setAsciiStream
50 * @see postgresql.PreparedStatement#setBinaryStream
51 * @see postgresql.PreparedStatement#setUnicodeStream
52 * @see java.sql.ResultSet#getAsciiStream
53 * @see java.sql.ResultSet#getBinaryStream
54 * @see java.sql.ResultSet#getUnicodeStream
55 * @see java.sql.PreparedStatement#setAsciiStream
56 * @see java.sql.PreparedStatement#setBinaryStream
57 * @see java.sql.PreparedStatement#setUnicodeStream
58 */
59 public class LargeObjectManager
60 {
61 // the fastpath api for this connection
62 private Fastpath fp;
63
64 /**
65 * This mode indicates we want to write to an object
66 */
67 public static final int WRITE = 0x00020000;
68
69 /**
70 * This mode indicates we want to read an object
71 */
72 public static final int READ = 0x00040000;
73
74 /**
75 * This mode is the default. It indicates we want read and write access to
76 * a large object
77 */
78 public static final int READWRITE = READ | WRITE;
79
80 /**
81 * This prevents us being created by mere mortals
82 */
83 private LargeObjectManager()
84 {
85 }
86
87 /**
88 * Constructs the LargeObject API.
89 *
90 * <p><b>Important Notice</b>
91 * <br>This method should only be called by postgresql.Connection
92 *
93 * <p>There should only be one LargeObjectManager per Connection. The
94 * postgresql.Connection class keeps track of the various extension API's
95 * and it's advised you use those to gain access, and not going direct.
96 */
97 public LargeObjectManager(postgresql.Connection conn) throws SQLException
98 {
99 // We need Fastpath to do anything
100 this.fp = conn.getFastpathAPI();
101
102 // Now get the function oid's for the api
103 //
104 // This is an example of Fastpath.addFunctions();
105 //
106 java.sql.ResultSet res = (java.sql.ResultSet)conn.createStatement().executeQuery("select proname, oid from pg_proc" +
107 " where proname = 'lo_open'" +
108 " or proname = 'lo_close'" +
109 " or proname = 'lo_creat'" +
110 " or proname = 'lo_unlink'" +
111 " or proname = 'lo_lseek'" +
112 " or proname = 'lo_tell'" +
113 " or proname = 'loread'" +
114 " or proname = 'lowrite'");
115
116 if(res==null)
117 throw new PSQLException("postgresql.lo.init");
118
119 fp.addFunctions(res);
120 res.close();
121 DriverManager.println("Large Object initialised");
122 }
123
124 /**
125 * This opens an existing large object, based on its OID. This method
126 * assumes that READ and WRITE access is required (the default).
127 *
128 * @param oid of large object
129 * @return LargeObject instance providing access to the object
130 * @exception SQLException on error
131 */
132 public LargeObject open(int oid) throws SQLException
133 {
134 return new LargeObject(fp,oid,READWRITE);
135 }
136
137 /**
138 * This opens an existing large object, based on its OID
139 *
140 * @param oid of large object
141 * @param mode mode of open
142 * @return LargeObject instance providing access to the object
143 * @exception SQLException on error
144 */
145 public LargeObject open(int oid,int mode) throws SQLException
146 {
147 return new LargeObject(fp,oid,mode);
148 }
149
150 /**
151 * This creates a large object, returning its OID.
152 *
153 * <p>It defaults to READWRITE for the new object's attributes.
154 *
155 * @return oid of new object
156 * @exception SQLException on error
157 */
158 public int create() throws SQLException
159 {
160 FastpathArg args[] = new FastpathArg[1];
161 args[0] = new FastpathArg(READWRITE);
162 return fp.getInteger("lo_creat",args);
163 }
164
165 /**
166 * This creates a large object, returning its OID
167 *
168 * @param mode a bitmask describing different attributes of the new object
169 * @return oid of new object
170 * @exception SQLException on error
171 */
172 public int create(int mode) throws SQLException
173 {
174 FastpathArg args[] = new FastpathArg[1];
175 args[0] = new FastpathArg(mode);
176 return fp.getInteger("lo_creat",args);
177 }
178
179 /**
180 * This deletes a large object.
181 *
182 * @param oid describing object to delete
183 * @exception SQLException on error
184 */
185 public void delete(int oid) throws SQLException
186 {
187 FastpathArg args[] = new FastpathArg[1];
188 args[0] = new FastpathArg(oid);
189 fp.fastpath("lo_unlink",false,args);
190 }
191
192 /**
193 * This deletes a large object.
194 *
195 * <p>It is identical to the delete method, and is supplied as the C API uses
196 * unlink.
197 *
198 * @param oid describing object to delete
199 * @exception SQLException on error
200 */
201 public void unlink(int oid) throws SQLException
202 {
203 delete(oid);
204 }
205
206 }