KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > jdbc > support > lob > LobCreator


1 /*
2  * Copyright 2002-2005 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.jdbc.support.lob;
18
19 import java.io.InputStream JavaDoc;
20 import java.io.Reader JavaDoc;
21 import java.sql.PreparedStatement JavaDoc;
22 import java.sql.SQLException JavaDoc;
23
24 /**
25  * Interface that abstracts potentially database-specific creation of large binary
26  * fields and large text fields. Does not work with java.sql.Blob and java.sql.Clob
27  * instances in the API, as some JDBC drivers do not support these types as such.
28  *
29  * <p>A LobCreator represents a session for creating BLOBs: It is <i>not</i>
30  * thread-safe and needs to be instantiated for each statement execution or for
31  * each transaction. Each LobCreator needs to be closed after completion.
32  *
33  * <p>For convenient working with a PreparedStatement and a LobCreator, consider
34  * JdbcTemplate with a AbstractLobCreatingPreparedStatementCallback implementation.
35  * See the latter's javadoc for details.
36  *
37  * @author Juergen Hoeller
38  * @since 04.12.2003
39  * @see #close
40  * @see LobHandler#getLobCreator
41  * @see org.springframework.jdbc.core.support.AbstractLobCreatingPreparedStatementCallback
42  * @see DefaultLobHandler.DefaultLobCreator
43  * @see OracleLobHandler.OracleLobCreator
44  * @see java.sql.PreparedStatement#setBlob
45  * @see java.sql.PreparedStatement#setClob
46  * @see java.sql.PreparedStatement#setBytes
47  * @see java.sql.PreparedStatement#setBinaryStream
48  * @see java.sql.PreparedStatement#setString
49  * @see java.sql.PreparedStatement#setAsciiStream
50  * @see java.sql.PreparedStatement#setCharacterStream
51  */
52 public interface LobCreator {
53
54     /**
55      * Set the given content as bytes on the given statement, using the given
56      * parameter index. Might simply invoke <code>PreparedStatement.setBytes</code>
57      * or create a Blob instance for it, depending on the database and driver.
58      * @param ps the PreparedStatement to the set the content on
59      * @param paramIndex the parameter index to use
60      * @param content the content as byte array, or <code>null</code> for SQL NULL
61      * @throws SQLException if thrown by JDBC methods
62      * @see java.sql.PreparedStatement#setBytes
63      */
64     void setBlobAsBytes(PreparedStatement JavaDoc ps, int paramIndex, byte[] content)
65         throws SQLException JavaDoc;
66
67     /**
68      * Set the given content as binary stream on the given statement, using the given
69      * parameter index. Might simply invoke <code>PreparedStatement.setBinaryStream</code>
70      * or create a Blob instance for it, depending on the database and driver.
71      * @param ps the PreparedStatement to the set the content on
72      * @param paramIndex the parameter index to use
73      * @param contentStream the content as binary stream, or <code>null</code> for SQL NULL
74      * @throws SQLException if thrown by JDBC methods
75      * @see java.sql.PreparedStatement#setBinaryStream
76      */
77     void setBlobAsBinaryStream(
78             PreparedStatement JavaDoc ps, int paramIndex, InputStream JavaDoc contentStream, int contentLength)
79         throws SQLException JavaDoc;
80
81     /**
82      * Set the given content as String on the given statement, using the given
83      * parameter index. Might simply invoke <code>PreparedStatement.setString</code>
84      * or create a Clob instance for it, depending on the database and driver.
85      * @param ps the PreparedStatement to the set the content on
86      * @param paramIndex the parameter index to use
87      * @param content the content as String, or <code>null</code> for SQL NULL
88      * @throws SQLException if thrown by JDBC methods
89      * @see java.sql.PreparedStatement#setBytes
90      */
91     void setClobAsString(PreparedStatement JavaDoc ps, int paramIndex, String JavaDoc content)
92         throws SQLException JavaDoc;
93
94     /**
95      * Set the given content as ASCII stream on the given statement, using the given
96      * parameter index. Might simply invoke <code>PreparedStatement.setAsciiStream</code>
97      * or create a Clob instance for it, depending on the database and driver.
98      * @param ps the PreparedStatement to the set the content on
99      * @param paramIndex the parameter index to use
100      * @param asciiStream the content as ASCII stream, or <code>null</code> for SQL NULL
101      * @throws SQLException if thrown by JDBC methods
102      * @see java.sql.PreparedStatement#setAsciiStream
103      */
104     void setClobAsAsciiStream(
105             PreparedStatement JavaDoc ps, int paramIndex, InputStream JavaDoc asciiStream, int contentLength)
106         throws SQLException JavaDoc;
107
108     /**
109      * Set the given content as character stream on the given statement, using the given
110      * parameter index. Might simply invoke <code>PreparedStatement.setCharacterStream</code>
111      * or create a Clob instance for it, depending on the database and driver.
112      * @param ps the PreparedStatement to the set the content on
113      * @param paramIndex the parameter index to use
114      * @param characterStream the content as character stream, or <code>null</code> for SQL NULL
115      * @throws SQLException if thrown by JDBC methods
116      * @see java.sql.PreparedStatement#setCharacterStream
117      */
118     void setClobAsCharacterStream(
119             PreparedStatement JavaDoc ps, int paramIndex, Reader JavaDoc characterStream, int contentLength)
120         throws SQLException JavaDoc;
121
122     /**
123      * Close this LobCreator session and free its temporarily created BLOBs and CLOBs.
124      * Will not need to do anything if using PreparedStatement's standard methods,
125      * but might be necessary to free database resources if using proprietary means.
126      * <p><b>NOTE</b>: Needs to be invoked after the involved PreparedStatements have
127      * been executed or the affected O/R mapping sessions have been flushed.
128      * Else, the database resources for the temporary BLOBs might stay allocated.
129      */
130     void close();
131
132 }
133
Popular Tags