1. /*
  2. * @(#)Clob.java 1.28 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.sql;
  8. /**
  9. * The mapping in the Java<sup><font size=-2>TM</font></sup> programming language
  10. * for the SQL <code>CLOB</code> type.
  11. * An SQL <code>CLOB</code> is a built-in type
  12. * that stores a Character Large Object as a column value in a row of
  13. * a database table.
  14. * By default drivers implement a <code>Clob</code> object using an SQL
  15. * <code>locator(CLOB)</code>, which means that a <code>Clob</code> object
  16. * contains a logical pointer to the SQL <code>CLOB</code> data rather than
  17. * the data itself. A <code>Clob</code> object is valid for the duration
  18. * of the transaction in which it was created.
  19. * <P>The <code>Clob</code> interface provides methods for getting the
  20. * length of an SQL <code>CLOB</code> (Character Large Object) value,
  21. * for materializing a <code>CLOB</code> value on the client, and for
  22. * searching for a substring or <code>CLOB</code> object within a
  23. * <code>CLOB</code> value.
  24. * Methods in the interfaces {@link ResultSet},
  25. * {@link CallableStatement}, and {@link PreparedStatement}, such as
  26. * <code>getClob</code> and <code>setClob</code> allow a programmer to
  27. * access an SQL <code>CLOB</code> value. In addition, this interface
  28. * has methods for updating a <code>CLOB</code> value.
  29. *
  30. * @since 1.2
  31. */
  32. public interface Clob {
  33. /**
  34. * Retrieves the number of characters
  35. * in the <code>CLOB</code> value
  36. * designated by this <code>Clob</code> object.
  37. *
  38. * @return length of the <code>CLOB</code> in characters
  39. * @exception SQLException if there is an error accessing the
  40. * length of the <code>CLOB</code> value
  41. * @since 1.2
  42. */
  43. long length() throws SQLException;
  44. /**
  45. * Retrieves a copy of the specified substring
  46. * in the <code>CLOB</code> value
  47. * designated by this <code>Clob</code> object.
  48. * The substring begins at position
  49. * <code>pos</code> and has up to <code>length</code> consecutive
  50. * characters.
  51. *
  52. * @param pos the first character of the substring to be extracted.
  53. * The first character is at position 1.
  54. * @param length the number of consecutive characters to be copied
  55. * @return a <code>String</code> that is the specified substring in
  56. * the <code>CLOB</code> value designated by this <code>Clob</code> object
  57. * @exception SQLException if there is an error accessing the
  58. * <code>CLOB</code> value
  59. * @since 1.2
  60. */
  61. String getSubString(long pos, int length) throws SQLException;
  62. /**
  63. * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
  64. * object as a <code>java.io.Reader</code> object (or as a stream of
  65. * characters).
  66. *
  67. * @return a <code>java.io.Reader</code> object containing the
  68. * <code>CLOB</code> data
  69. * @exception SQLException if there is an error accessing the
  70. * <code>CLOB</code> value
  71. * @see #setCharacterStream
  72. * @since 1.2
  73. */
  74. java.io.Reader getCharacterStream() throws SQLException;
  75. /**
  76. * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
  77. * object as an ascii stream.
  78. *
  79. * @return a <code>java.io.InputStream</code> object containing the
  80. * <code>CLOB</code> data
  81. * @exception SQLException if there is an error accessing the
  82. * <code>CLOB</code> value
  83. * @see #setAsciiStream
  84. * @since 1.2
  85. */
  86. java.io.InputStream getAsciiStream() throws SQLException;
  87. /**
  88. * Retrieves the character position at which the specified substring
  89. * <code>searchstr</code> appears in the SQL <code>CLOB</code> value
  90. * represented by this <code>Clob</code> object. The search
  91. * begins at position <code>start</code>.
  92. *
  93. * @param searchstr the substring for which to search
  94. * @param start the position at which to begin searching; the first position
  95. * is 1
  96. * @return the position at which the substring appears or -1 if it is not
  97. * present; the first position is 1
  98. * @exception SQLException if there is an error accessing the
  99. * <code>CLOB</code> value
  100. * @since 1.2
  101. */
  102. long position(String searchstr, long start) throws SQLException;
  103. /**
  104. * Retrieves the character position at which the specified
  105. * <code>Clob</code> object <code>searchstr</code> appears in this
  106. * <code>Clob</code> object. The search begins at position
  107. * <code>start</code>.
  108. *
  109. * @param searchstr the <code>Clob</code> object for which to search
  110. * @param start the position at which to begin searching; the first
  111. * position is 1
  112. * @return the position at which the <code>Clob</code> object appears
  113. * or -1 if it is not present; the first position is 1
  114. * @exception SQLException if there is an error accessing the
  115. * <code>CLOB</code> value
  116. * @since 1.2
  117. */
  118. long position(Clob searchstr, long start) throws SQLException;
  119. //---------------------------- jdbc 3.0 -----------------------------------
  120. /**
  121. * Writes the given Java <code>String</code> to the <code>CLOB</code>
  122. * value that this <code>Clob</code> object designates at the position
  123. * <code>pos</code>.
  124. *
  125. * @param pos the position at which to start writing to the <code>CLOB</code>
  126. * value that this <code>Clob</code> object represents
  127. * @param str the string to be written to the <code>CLOB</code>
  128. * value that this <code>Clob</code> designates
  129. * @return the number of characters written
  130. * @exception SQLException if there is an error accessing the
  131. * <code>CLOB</code> value
  132. *
  133. * @since 1.4
  134. */
  135. int setString(long pos, String str) throws SQLException;
  136. /**
  137. * Writes <code>len</code> characters of <code>str</code>, starting
  138. * at character <code>offset</code>, to the <code>CLOB</code> value
  139. * that this <code>Clob</code> represents.
  140. *
  141. * @param pos the position at which to start writing to this
  142. * <code>CLOB</code> object
  143. * @param str the string to be written to the <code>CLOB</code>
  144. * value that this <code>Clob</code> object represents
  145. * @param offset the offset into <code>str</code> to start reading
  146. * the characters to be written
  147. * @param len the number of characters to be written
  148. * @return the number of characters written
  149. * @exception SQLException if there is an error accessing the
  150. * <code>CLOB</code> value
  151. *
  152. * @since 1.4
  153. */
  154. int setString(long pos, String str, int offset, int len) throws SQLException;
  155. /**
  156. * Retrieves a stream to be used to write Ascii characters to the
  157. * <code>CLOB</code> value that this <code>Clob</code> object represents,
  158. * starting at position <code>pos</code>.
  159. *
  160. * @param pos the position at which to start writing to this
  161. * <code>CLOB</code> object
  162. * @return the stream to which ASCII encoded characters can be written
  163. * @exception SQLException if there is an error accessing the
  164. * <code>CLOB</code> value
  165. * @see #getAsciiStream
  166. *
  167. * @since 1.4
  168. */
  169. java.io.OutputStream setAsciiStream(long pos) throws SQLException;
  170. /**
  171. * Retrieves a stream to be used to write a stream of Unicode characters
  172. * to the <code>CLOB</code> value that this <code>Clob</code> object
  173. * represents, at position <code>pos</code>.
  174. *
  175. * @param pos the position at which to start writing to the
  176. * <code>CLOB</code> value
  177. *
  178. * @return a stream to which Unicode encoded characters can be written
  179. * @exception SQLException if there is an error accessing the
  180. * <code>CLOB</code> value
  181. * @see #getCharacterStream
  182. *
  183. * @since 1.4
  184. */
  185. java.io.Writer setCharacterStream(long pos) throws SQLException;
  186. /**
  187. * Truncates the <code>CLOB</code> value that this <code>Clob</code>
  188. * designates to have a length of <code>len</code>
  189. * characters.
  190. * @param len the length, in bytes, to which the <code>CLOB</code> value
  191. * should be truncated
  192. * @exception SQLException if there is an error accessing the
  193. * <code>CLOB</code> value
  194. *
  195. * @since 1.4
  196. */
  197. void truncate(long len) throws SQLException;
  198. }