jdk/src/java.sql/share/classes/java/sql/SQLXML.java
changeset 25991 e48157b42439
parent 25976 4de01a56e3ee
parent 25859 3317bb8137f4
equal deleted inserted replaced
25876:d06a6d3c66c0 25991:e48157b42439
     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