setXXXStream requests stream data between the application
and the database.
JDBC allows an IN parameter to be set to a Java input stream for
passing in large amounts of data in smaller chunks. When the statement is
executed, the JDBC driver makes repeated calls to this input stream, reading
its contents and transmitting those contents as the parameter data.
setBinaryStream supports
the three types of streams that JDBC 1.2 provides. These three streams are:
- setBinaryStreamsetBinaryStream
for streams
containing uninterpreted bytes
- setAsciiStreamsetAsciiStream
for
streams containing ASCII characters
- setUnicodeStreamUnicodesetUnicodeStreamsetUnicodeStream
for streams containing Unicode characters
StreamJDBC 2.0 and JDBC 3.0 require that you specify the
length of the stream and
enforces this requirement if your application runs on JDK 1.5 or earlier. If your application runs
on JDK 1.6, then exposes a JDBC
4.0 implementation, which
lets you use the streaming interfaces without having to specify the
stream length.
The stream object passed to these three methods can
be either a standard Java stream object or the user's own subclass that implements
the standard java.io.InputStream interface.
According to the JDBC standard, streams can be stored only in
columns of the data types shown in .
Streams cannot be stored in columns of the other built-in data types or of
user-defined data types.
Streamable JDBC Data Types
Column Values
Type Correspondent
AsciiStream
UnicodeStream
BinaryStream
CLOB
java.sql.Clob
x
x
CHAR
x
x
VARCHAR
x
x
LONGVARCHAR
X
X
BINARY
x
x
x
BLOB
java.sql.Blob
x
x
x
VARBINARY
x
x
x
LONGVARBINARY
x
x
X
A large X indicates the preferred target data type for the type
of stream. (See .)
If the stream is stored in a column of a type other than LONG VARCHAR
or LONG VARCHAR FOR BIT DATA, the entire stream must be able to fit into memory
at one time. Streams stored in LONG VARCHAR and LONG VARCHAR FOR BIT DATA
columns do not have this limitation.
The following example shows how a user can store a streamed java.io.File in
a LONG VARCHAR column: Statement s = conn.createStatement();
s.executeUpdate("CREATE TABLE atable (a INT, b LONG VARCHAR)");
conn.commit();
java.io.File file = new java.io.File("derby.txt");
int fileLength = (int) file.length();
// first, create an input stream
java.io.InputStream fin = new java.io.FileInputStream(file);
PreparedStatement ps = conn.prepareStatement(
"INSERT INTO atable VALUES (?, ?)");
ps.setInt(1, 1);
// set the value of the input parameter to the input stream
ps.setAsciiStream(2, fin, fileLength);
ps.execute();
conn.commit();