equal
deleted
inserted
replaced
1 /* |
1 /* |
2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
5 * This code is free software; you can redistribute it and/or modify it |
6 * under the terms of the GNU General Public License version 2 only, as |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
172 * <p> |
172 * <p> |
173 * The state moves from readable to not readable once free() or any of the |
173 * The state moves from readable to not readable once free() or any of the |
174 * reading APIs are called: getBinaryStream(), getCharacterStream(), getSource(), and getString(). |
174 * reading APIs are called: getBinaryStream(), getCharacterStream(), getSource(), and getString(). |
175 * Implementations may also change the state to not writable when this occurs. |
175 * Implementations may also change the state to not writable when this occurs. |
176 * <p> |
176 * <p> |
177 * The state moves from writable to not writeable once free() or any of the |
177 * The state moves from writable to not writable once free() or any of the |
178 * writing APIs are called: setBinaryStream(), setCharacterStream(), setResult(), and setString(). |
178 * writing APIs are called: setBinaryStream(), setCharacterStream(), setResult(), and setString(). |
179 * Implementations may also change the state to not readable when this occurs. |
179 * Implementations may also change the state to not readable when this occurs. |
180 * |
180 * |
181 * <p> |
181 * <p> |
182 * All methods on the <code>SQLXML</code> interface must be fully implemented if the |
182 * All methods on the <code>SQLXML</code> interface must be fully implemented if the |
190 */ |
190 */ |
191 public interface SQLXML |
191 public interface SQLXML |
192 { |
192 { |
193 /** |
193 /** |
194 * This method closes this object and releases the resources that it held. |
194 * This method closes this object and releases the resources that it held. |
195 * The SQL XML object becomes invalid and neither readable or writeable |
195 * The SQL XML object becomes invalid and neither readable or writable |
196 * when this method is called. |
196 * when this method is called. |
197 * |
197 * |
198 * After <code>free</code> has been called, any attempt to invoke a |
198 * After <code>free</code> has been called, any attempt to invoke a |
199 * method other than <code>free</code> will result in a <code>SQLException</code> |
199 * method other than <code>free</code> will result in a <code>SQLException</code> |
200 * being thrown. If <code>free</code> is called multiple times, the subsequent |
200 * being thrown. If <code>free</code> is called multiple times, the subsequent |
229 * The stream begins at position 0. |
229 * The stream begins at position 0. |
230 * The bytes of the stream are interpreted according to appendix F of the XML 1.0 specification |
230 * The bytes of the stream are interpreted according to appendix F of the XML 1.0 specification |
231 * The behavior of this method is the same as ResultSet.updateBinaryStream() |
231 * The behavior of this method is the same as ResultSet.updateBinaryStream() |
232 * when the designated column of the ResultSet has a type java.sql.Types of SQLXML. |
232 * when the designated column of the ResultSet has a type java.sql.Types of SQLXML. |
233 * <p> |
233 * <p> |
234 * The SQL XML object becomes not writeable when this method is called and |
234 * The SQL XML object becomes not writable when this method is called and |
235 * may also become not readable depending on implementation. |
235 * may also become not readable depending on implementation. |
236 * |
236 * |
237 * @return a stream to which data can be written. |
237 * @return a stream to which data can be written. |
238 * @throws SQLException if there is an error processing the XML value. |
238 * @throws SQLException if there is an error processing the XML value. |
239 * An exception is thrown if the state is not writable. |
239 * An exception is thrown if the state is not writable. |
275 * Although an encoding declaration other than unicode may be present, |
275 * Although an encoding declaration other than unicode may be present, |
276 * the encoding of the stream is unicode. |
276 * the encoding of the stream is unicode. |
277 * The behavior of this method is the same as ResultSet.updateCharacterStream() |
277 * The behavior of this method is the same as ResultSet.updateCharacterStream() |
278 * when the designated column of the ResultSet has a type java.sql.Types of SQLXML. |
278 * when the designated column of the ResultSet has a type java.sql.Types of SQLXML. |
279 * <p> |
279 * <p> |
280 * The SQL XML object becomes not writeable when this method is called and |
280 * The SQL XML object becomes not writable when this method is called and |
281 * may also become not readable depending on implementation. |
281 * may also become not readable depending on implementation. |
282 * |
282 * |
283 * @return a stream to which data can be written. |
283 * @return a stream to which data can be written. |
284 * @throws SQLException if there is an error processing the XML value. |
284 * @throws SQLException if there is an error processing the XML value. |
285 * The getCause() method of the exception may provide a more detailed exception, for example, |
285 * The getCause() method of the exception may provide a more detailed exception, for example, |
323 * Although an encoding declaration other than unicode may be present, |
323 * Although an encoding declaration other than unicode may be present, |
324 * the encoding of the String is unicode. |
324 * the encoding of the String is unicode. |
325 * The behavior of this method is the same as ResultSet.updateString() |
325 * The behavior of this method is the same as ResultSet.updateString() |
326 * when the designated column of the ResultSet has a type java.sql.Types of SQLXML. |
326 * when the designated column of the ResultSet has a type java.sql.Types of SQLXML. |
327 * <p> |
327 * <p> |
328 * The SQL XML object becomes not writeable when this method is called and |
328 * The SQL XML object becomes not writable when this method is called and |
329 * may also become not readable depending on implementation. |
329 * may also become not readable depending on implementation. |
330 * |
330 * |
331 * @param value the XML value |
331 * @param value the XML value |
332 * @throws SQLException if there is an error processing the XML value. |
332 * @throws SQLException if there is an error processing the XML value. |
333 * The getCause() method of the exception may provide a more detailed exception, for example, |
333 * The getCause() method of the exception may provide a more detailed exception, for example, |
385 /** |
385 /** |
386 * Returns a Result for setting the XML value designated by this SQLXML instance. |
386 * Returns a Result for setting the XML value designated by this SQLXML instance. |
387 * <p> |
387 * <p> |
388 * The systemID of the Result is implementation dependent. |
388 * The systemID of the Result is implementation dependent. |
389 * <p> |
389 * <p> |
390 * The SQL XML object becomes not writeable when this method is called and |
390 * The SQL XML object becomes not writable when this method is called and |
391 * may also become not readable depending on implementation. |
391 * may also become not readable depending on implementation. |
392 * <p> |
392 * <p> |
393 * Note that SAX is a callback architecture and the returned |
393 * Note that SAX is a callback architecture and the returned |
394 * SAXResult has a content handler assigned that will receive the |
394 * SAXResult has a content handler assigned that will receive the |
395 * SAX events based on the contents of the XML. Call the content |
395 * SAX events based on the contents of the XML. Call the content |