--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.impl.jdbc.InternalClob\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one\r
+ or more contributor license agreements. See the NOTICE file\r
+ distributed with this work for additional information\r
+ regarding copyright ownership. The ASF licenses this file\r
+ to you under the Apache License, Version 2.0 (the\r
+ "License"); you may not use this file except in compliance\r
+ with the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing,\r
+ software distributed under the License is distributed on an\r
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\r
+ KIND, either express or implied. See the License for the\r
+ specific language governing permissions and limitations\r
+ under the License.\r
+\r
+ */\r
+package org.apache.derby.impl.jdbc;\r
+\r
+import java.io.IOException;\r
+import java.io.InputStream;\r
+import java.io.Reader;\r
+import java.io.Writer;\r
+\r
+import java.sql.SQLException;\r
+\r
+/**\r
+ * A set of operations available on internal Clob content representations.\r
+ * <p>\r
+ * The methods defined by {@link java.sql.Clob} must be implemented on top of\r
+ * this interface. In addition, there are some methods to aid internal tasks and\r
+ * organization, like transferring one internal Clob representation to another\r
+ * one.\r
+ */\r
+interface InternalClob {\r
+\r
+ /**\r
+ * Gets the number of bytes contained in the Clob.\r
+ *\r
+ * @return Number of bytes in the Clob.\r
+ * @throws IOException if accessing underlying I/O resources fail\r
+ * @throws SQLException if accessing underlying resources fail\r
+ */\r
+ long getByteLength() throws IOException, SQLException;\r
+\r
+ /**\r
+ * Obtains the byte position for the given character position.\r
+ * <p>\r
+ * The range of valid character positions is \r
+ * <code>1 - Clob.getCharLength() +1</code>, inclusive. The upper bound is\r
+ * used when appending to the Clob. Note that specifying a character\r
+ * position that is more than one longer than the Clob raises an exception.\r
+ *\r
+ * @param charPos character position. The first position is <code>1</code>.\r
+ * @return A 0-based byte position.\r
+ * @throws EOFException if the position is bigger than the Clob\r
+ * @throws IOException if accessing the underlying I/O resources fail\r
+ * @throws SQLException if the specified character position is invalid\r
+ */\r
+ long getBytePosition(long charPos) throws IOException, SQLException;\r
+\r
+ /**\r
+ * Gets the number of characters in the Clob.\r
+ *\r
+ * @return Number of characters in the Clob.\r
+ * @throws IOException if accessing underlying I/O resources fail\r
+ * @throws SQLException if accessing underlying resources fail\r
+ */\r
+ long getCharLength() throws IOException, SQLException;\r
+\r
+ /**\r
+ * Returns a stream serving the raw bytes of the Clob.\r
+ * <p>\r
+ * Note that it is up to the caller of this method to handle the issue of\r
+ * encoding. There is no predetermined encoding associated with this byte\r
+ * stream, it is up to the Clob representation which one it uses.\r
+ * <p>\r
+ * This stream may be an internal store stream, and should not be directly\r
+ * published to the end user (returned through the JDBC API). There are two\r
+ * motivations for this; the stream may be closed by the end user when it is\r
+ * not supposed to, and operations on the stream might throw exceptions we\r
+ * do not want to present to the end user unwrapped.\r
+ * <p>\r
+ * The primary use of this method is to clone the Clob contents without\r
+ * going via char (or String). Make sure the clone uses the same encoding\r
+ * as the original Clob representation.\r
+ *\r
+ * @return A stream of bytes representing the content of the Clob,\r
+ * initialized at byte position 0.\r
+ * @throws IOException if accessing underlying I/O resources fail\r
+ * @throws SQLException if accessing underlying resources fail\r
+ */\r
+ InputStream getRawByteStream() throws IOException, SQLException;\r
+\r
+ /**\r
+ * Returns a reader for the Clob content, initialized at the specified\r
+ * character position.\r
+ *\r
+ * @param characterPosition character position. The first character is at\r
+ * position <code>1</code>.\r
+ * @return A <code>Reader</coder> serving the content of the Clob.\r
+ * @throws EOFException if the position is larger then the Clob\r
+ * @throws IOException if accessing underlying I/O resources fail\r
+ * @throws SQLException if accessing underlying resources fail\r
+ */\r
+ Reader getReader(long characterPosition) throws IOException, SQLException;\r
+\r
+ /**\r
+ * Returns a writer to write data into the Clob.\r
+ * <p>\r
+ * The semantics of the writer is the same as for {@link #insertString}.\r
+ *\r
+ * @param charPos the starting character position. The first character is\r
+ * at position <code>1</code>.\r
+ * @return A writer initialized at the specified character position.\r
+ * @throws IOException if writing to the Clob fails\r
+ * @throws SQLException if accessing underlying resources fail\r
+ * @throws UnsupportedOperationException if the Clob representation is\r
+ * read-only\r
+ */\r
+ Writer getWriter(long charPos) throws IOException, SQLException;\r
+\r
+ /**\r
+ * Inserts the given string at the specified character position.\r
+ * <p>\r
+ * The behavior of this method can be defined by the following examples on\r
+ * the Clob <code>clob</code> with value <code>"ABCDEFG"</code>;\r
+ * <ul> <li><code>clob.setString(2, "XX")</code> - "AXXDEFG"\r
+ * <li><code>clob.setString(1, "XX")</code> - "XXCDEFG"\r
+ * <li><code>clob.setString(8, "XX")</code> - "ABCDEFGXX"\r
+ * <li><code>clob.setString(7, "XX")</code> - "ABCDEFXX"\r
+ * <li><code>clob.setString(9, "XX")</code> - throws exception\r
+ * </ul>\r
+ *\r
+ * @param str the string to insert\r
+ * @param pos the character position the string will be inserted at. Must be\r
+ * between <code>1</code> and <code>clob.length() +1</code>, inclusive.\r
+ * @return The number of characters inserted.\r
+ * @throws IOException if writing to the I/O resources fail\r
+ * @throws SQLException it the position is invalid\r
+ * @throws IllegalArgumentException if the string is <code>null</code>\r
+ * @throws UnsupportedOperationException if the Clob representation is\r
+ * read-only\r
+ */\r
+ long insertString(String str, long pos) throws IOException, SQLException;\r
+\r
+ /**\r
+ * Tells if the Clob representation is intended to be writable.\r
+ * <p>\r
+ * Note that even if this method returns <code>true</true>, it might not be\r
+ * possible to write to the Clob. If this happens, it is because the\r
+ * assoicated database is read-only, and the internal Clob representation is\r
+ * unable to obtain the resources it require (could be an area on disk to\r
+ * write temporary data).\r
+ *\r
+ * @return <code>true</code> if the Clob is intended to be writable, \r
+ * <code>false</code> if modifying the Clob is definitely not possible.\r
+ */\r
+ boolean isWritable();\r
+\r
+ /**\r
+ * Frees the resources held by the internal Clob representation.\r
+ * <p>\r
+ * After calling this method, all other operations on the Clob will be\r
+ * invalid and throw an exception.\r
+ *\r
+ * @throws IOException if freeing associated I/O resources fails\r
+ * @throws SQLException if freeing associated resources fails\r
+ */\r
+ void release() throws IOException, SQLException;\r
+\r
+ /**\r
+ *\r
+ * @param newLength the length in characters to truncate to\r
+ *\r
+ * @throws IOException if accessing the underlying I/O resources fails\r
+ * @throws SQLException if accessing underlying resources fail\r
+ * @throws UnsupportedOperationException if the Clob representation is\r
+ * read-only\r
+ */\r
+ void truncate(long newLength) throws IOException, SQLException;\r
+} // End interface InternalClob\r
projects / Benchmarks_CSolver.git / blobdiff