Clob


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