34 */ |
34 */ |
35 public interface SqlClob extends AutoCloseable { |
35 public interface SqlClob extends AutoCloseable { |
36 |
36 |
37 /** |
37 /** |
38 * Return an {@link Operation} that will release the temporary resources |
38 * Return an {@link Operation} that will release the temporary resources |
39 * associated with this {@link SqlClob}. |
39 * associated with this {@code SqlClob}. |
40 * |
40 * |
41 * @return an {@link Operation} that will release the temporary resources |
41 * @return an {@link Operation} that will release the temporary resources |
42 * associated with this {@link SqlClob}. |
42 * associated with this {@code SqlClob}. |
43 */ |
43 */ |
44 public Operation<Void> closeOperation(); |
44 public Operation<Void> closeOperation(); |
45 |
45 |
|
46 /** |
|
47 * {@inheritDoc} |
|
48 */ |
46 @Override |
49 @Override |
47 public default void close() { |
50 public default void close() { |
48 this.closeOperation().submit(); |
51 this.closeOperation().submit(); |
49 } |
52 } |
50 |
53 |
51 /** |
54 /** |
52 * Return a {@link Operation} that fetches the position of this {@link SqlClob}. |
55 * Return a {@link Operation} that fetches the position of this {@code SqlClob}. |
53 * Position 0 is immediately before the first char in the {@link SqlClob}. |
56 * Position 0 is immediately before the first char in the {@code SqlClob}. |
54 * Position 1 is the first char in the {@link SqlClob}, etc. Position |
57 * Position 1 is the first char in the {@code SqlClob}, etc. Position |
55 * {@link length()} is the last char in the {@link SqlClob}. |
58 * {@link length()} is the last char in the {@code SqlClob}. |
56 * |
59 * |
57 * Position is between 0 and length + 1. |
60 * Position is between 0 and length + 1. |
58 * |
61 * |
59 * @return an {@link Operation} that returns the position of this {@link SqlClob} |
62 * @return an {@link Operation} that returns the position of this {@code SqlClob} |
60 * @throws IllegalStateException if the {@link Session} that created this |
63 * @throws IllegalStateException if the {@link Session} that created this |
61 * {@link SqlClob} is closed.; |
64 * {@code SqlClob} is closed.; |
62 */ |
65 */ |
63 public Operation<Long> getPositionOperation(); |
66 public Operation<Long> getPositionOperation(); |
64 |
67 |
65 /** |
68 /** |
66 * Get the position of this {@link SqlClob}. Position 0 is immediately before the |
69 * Get the position of this {@code SqlClob}. Position 0 is immediately before the |
67 * first char in the {@link SqlClob}. Position 1 is the first char in the |
70 * first char in the {@code SqlClob}. Position 1 is the first char in the |
68 * {@link SqlClob}, etc. Position {@link length()} is the last char in the SqlClob. |
71 * {@code SqlClob}, etc. Position {@link length()} is the last char in the SqlClob. |
69 |
72 |
70 Position is between 0 and length + 1. |
73 Position is between 0 and length + 1. |
71 |
74 |
72 ISSUE: Should position be 1-based as SQL seems to do or 0-based as Java |
75 ISSUE: Should position be 1-based as SQL seems to do or 0-based as Java |
73 does? |
76 does? |
74 * |
77 * |
75 * @return a future which value is the position of this {@link SqlClob} |
78 * @return a future which value is the position of this {@code SqlClob} |
76 * @throws IllegalStateException if the {@link Session} that created this |
79 * @throws IllegalStateException if the {@link Session} that created this |
77 * {@link SqlClob} is closed. |
80 * {@code SqlClob} is closed. |
78 */ |
81 */ |
79 public default CompletionStage<Long> getPosition() { |
82 public default CompletionStage<Long> getPosition() { |
80 return getPositionOperation().submit().getCompletionStage(); |
83 return getPositionOperation().submit().getCompletionStage(); |
81 } |
84 } |
82 |
85 |
83 /** |
86 /** |
84 * Return a {@link Operation} that fetches the length of this {@link SqlClob}. |
87 * Return a {@link Operation} that fetches the length of this {@code SqlClob}. |
85 * |
88 * |
86 * @return a {@link Operation} that returns the length of this {@link SqlClob} |
89 * @return a {@link Operation} that returns the length of this {@code SqlClob} |
87 * @throws IllegalStateException if the {@link Session} that created this |
90 * @throws IllegalStateException if the {@link Session} that created this |
88 * {@link SqlClob} is closed. |
91 * {@code SqlClob} is closed. |
89 */ |
92 */ |
90 public Operation<Long> lengthOperation(); |
93 public Operation<Long> lengthOperation(); |
91 |
94 |
92 /** |
95 /** |
93 * Get the length of this {@link SqlClob}. |
96 * Get the length of this {@code SqlClob}. |
94 * |
97 * |
95 * @return a {@link java.util.concurrent.Future} which value is the number of |
98 * @return a {@link java.util.concurrent.Future} which value is the number of |
96 * chars in this {@link SqlClob} |
99 * chars in this {@code SqlClob} |
97 * @throws IllegalStateException if the {@link Session} that created this |
100 * @throws IllegalStateException if the {@link Session} that created this |
98 * {@link SqlClob} is closed. |
101 * {@code SqlClob} is closed. |
99 */ |
102 */ |
100 public default CompletionStage<Long> length() { |
103 public default CompletionStage<Long> length() { |
101 return lengthOperation().submit().getCompletionStage(); |
104 return lengthOperation().submit().getCompletionStage(); |
102 } |
105 } |
103 |
106 |
104 /** |
107 /** |
105 * Return an {@link Operation} that sets the position of this {@link SqlClob}. If |
108 * Return an {@link Operation} that sets the position of this {@code SqlClob}. If |
106 * {@code offset} exceeds the length of this {@link SqlClob} set position to the |
109 * {@code offset} exceeds the length of this {@code SqlClob} set position to the |
107 * length + 1 of this {@link SqlClob}, ie one past the last char. |
110 * length + 1 of this {@code SqlClob}, ie one past the last char. |
108 * |
111 * |
109 * @param offset a non-negative number |
112 * @param offset a non-negative number |
110 * @return a {@link Operation} that sets the position of this {@link SqlClob} |
113 * @return a {@link Operation} that sets the position of this {@code SqlClob} |
111 * @throws IllegalArgumentException if {@code offset} is less than 0 |
114 * @throws IllegalArgumentException if {@code offset} is less than 0 |
112 * @throws IllegalStateException if the {@link Session} that created this |
115 * @throws IllegalStateException if the {@link Session} that created this |
113 * {@link SqlClob} is closed. |
116 * {@code SqlClob} is closed. |
114 */ |
117 */ |
115 public Operation<Long> setPositionOperation(long offset); |
118 public Operation<Long> setPositionOperation(long offset); |
116 |
119 |
117 /** |
120 /** |
118 * Set the position of this {@link SqlClob}. If {@code offset} exceeds the length |
121 * Set the position of this {@code SqlClob}. If {@code offset} exceeds the length |
119 * of this {@link SqlClob} set position to the length + 1 of this {@link SqlClob}, |
122 * of this {@code SqlClob} set position to the length + 1 of this {@code SqlClob}, |
120 * ie one past the last char. |
123 * ie one past the last char. |
121 * |
124 * |
122 * @param offset the 1-based position to set |
125 * @param offset the 1-based position to set |
123 * @return this {@link SqlClob} |
126 * @return this {@code SqlClob} |
124 * @throws IllegalArgumentException if {@code offset} is less than 0 |
127 * @throws IllegalArgumentException if {@code offset} is less than 0 |
125 * @throws IllegalStateException if the {@link Session} that created this |
128 * @throws IllegalStateException if the {@link Session} that created this |
126 * {@link SqlClob} is closed. |
129 * {@code SqlClob} is closed. |
127 */ |
130 */ |
128 public default SqlClob setPosition(long offset) { |
131 public default SqlClob setPosition(long offset) { |
129 setPositionOperation(offset).submit(); |
132 setPositionOperation(offset).submit(); |
130 return this; |
133 return this; |
131 } |
134 } |
133 /** |
136 /** |
134 * Return an {@link Operation} to set the position to the beginning of the |
137 * Return an {@link Operation} to set the position to the beginning of the |
135 * next occurrence of the target after the position. If there is no such |
138 * next occurrence of the target after the position. If there is no such |
136 * occurrence set the position to 0. |
139 * occurrence set the position to 0. |
137 * |
140 * |
138 * @param target a {@link SqlClob} created by the same {@link Session} |
141 * @param target a {@code SqlClob} created by the same {@link Session} |
139 * containing the char sequence to search for |
142 * containing the char sequence to search for |
140 * @return an {@link Operation} that locates {@code target} in this |
143 * @return an {@link Operation} that locates {@code target} in this |
141 * {@link SqlClob} |
144 * {@code SqlClob} |
142 * @throws IllegalArgumentException if {@code target} was created by some |
145 * @throws IllegalArgumentException if {@code target} was created by some |
143 * other {@link Session} |
146 * other {@link Session} |
144 * @throws IllegalStateException if the {@link Session} that created this |
147 * @throws IllegalStateException if the {@link Session} that created this |
145 * {@link SqlClob} is closed. |
148 * {@code SqlClob} is closed. |
146 */ |
149 */ |
147 public Operation<Long> locateOperation(SqlClob target); |
150 public Operation<Long> locateOperation(SqlClob target); |
148 |
151 |
149 /** |
152 /** |
150 * Set the position to the beginning of the next occurrence of the target |
153 * Set the position to the beginning of the next occurrence of the target |
151 * after the position. If there is no such occurrence set the position to 0. |
154 * after the position. If there is no such occurrence set the position to 0. |
152 * |
155 * |
153 * @param target the char sequence to search for |
156 * @param target the char sequence to search for |
154 * @return this {@link SqlClob} |
157 * @return this {@code SqlClob} |
155 * @throws IllegalArgumentException if {@code target} was created by some |
158 * @throws IllegalArgumentException if {@code target} was created by some |
156 * other {@link Session} |
159 * other {@link Session} |
157 * @throws IllegalStateException if the {@link Session} that created this |
160 * @throws IllegalStateException if the {@link Session} that created this |
158 * {@link SqlClob} is closed |
161 * {@code SqlClob} is closed |
159 */ |
162 */ |
160 public default SqlClob locate(SqlClob target) { |
163 public default SqlClob locate(SqlClob target) { |
161 locateOperation(target).submit(); |
164 locateOperation(target).submit(); |
162 return this; |
165 return this; |
163 } |
166 } |
167 * next occurrence of the target after the position. If there is no such |
170 * next occurrence of the target after the position. If there is no such |
168 * occurrence set the position to 0. |
171 * occurrence set the position to 0. |
169 * |
172 * |
170 * @param target the char sequence to search for. Not {@code null}. Captured. |
173 * @param target the char sequence to search for. Not {@code null}. Captured. |
171 * @return an {@link Operation} that locates {@code target} in this |
174 * @return an {@link Operation} that locates {@code target} in this |
172 * {@link SqlClob} |
175 * {@code SqlClob} |
173 * @throws IllegalStateException if the {@link Session} that created this |
176 * @throws IllegalStateException if the {@link Session} that created this |
174 * {@link SqlClob} is closed. |
177 * {@code SqlClob} is closed. |
175 */ |
178 */ |
176 public Operation<Long> locateOperation(CharSequence target); |
179 public Operation<Long> locateOperation(CharSequence target); |
177 |
180 |
178 /** |
181 /** |
179 * Set the position to the beginning of the next occurrence of the target |
182 * Set the position to the beginning of the next occurrence of the target |
180 * after the position. If there is no such occurrence set the position to 0. |
183 * after the position. If there is no such occurrence set the position to 0. |
181 * |
184 * |
182 * @param target the char sequence to search for |
185 * @param target the char sequence to search for |
183 * @return this {@link SqlClob} |
186 * @return this {@code SqlClob} |
184 * @throws IllegalStateException if the {@link Session} that created this |
187 * @throws IllegalStateException if the {@link Session} that created this |
185 * {@link SqlClob} is closed. |
188 * {@code SqlClob} is closed. |
186 */ |
189 */ |
187 public default SqlClob locate(CharSequence target) { |
190 public default SqlClob locate(CharSequence target) { |
188 locateOperation(target).submit(); |
191 locateOperation(target).submit(); |
189 return this; |
192 return this; |
190 } |
193 } |
191 |
194 |
192 /** |
195 /** |
193 * Return an {@link Operation} that truncates this {@link SqlClob} so that the |
196 * Return an {@link Operation} that truncates this {@code SqlClob} so that the |
194 * current position is the end of the {@link SqlClob}. If the position is N, then |
197 * current position is the end of the {@code SqlClob}. If the position is N, then |
195 * after trim() the length is N - 1. The position is still N. This will fail |
198 * after trim() the length is N - 1. The position is still N. This will fail |
196 * if position is 0. |
199 * if position is 0. |
197 * |
200 * |
198 * @return an {@link Operation} that trims the length of this {@link SqlClob} |
201 * @return an {@link Operation} that trims the length of this {@code SqlClob} |
199 * @throws IllegalStateException if the {@link Session} that created this |
202 * @throws IllegalStateException if the {@link Session} that created this |
200 * {@link SqlClob} is closed or position is 0. |
203 * {@code SqlClob} is closed or position is 0. |
201 */ |
204 */ |
202 public Operation<Long> trimOperation(); |
205 public Operation<Long> trimOperation(); |
203 |
206 |
204 /** |
207 /** |
205 * Truncate this {@link SqlClob} so that the current position is the end of the |
208 * Truncate this {@code SqlClob} so that the current position is the end of the |
206 * {@link SqlClob}. If the position is N, then after {@link trim()} the length is |
209 * {@code SqlClob}. If the position is N, then after {@link trim()} the length is |
207 * N - 1. The position is still N. This will fail if position is 0. |
210 * N - 1. The position is still N. This will fail if position is 0. |
208 * |
211 * |
209 * @return this {@link SqlClob} |
212 * @return this {@code SqlClob} |
210 * @throws IllegalStateException if the {@link Session} that created this |
213 * @throws IllegalStateException if the {@link Session} that created this |
211 * {@link SqlClob} is closed or position is 0. |
214 * {@code SqlClob} is closed or position is 0. |
212 */ |
215 */ |
213 public default SqlClob trim() { |
216 public default SqlClob trim() { |
214 trimOperation().submit(); |
217 trimOperation().submit(); |
215 return this; |
218 return this; |
216 } |
219 } |
217 |
220 |
218 /** |
221 /** |
219 * Returns a {@link Reader} for the characters in this {@link SqlClob}. |
222 * Returns a {@link Reader} for the characters in this {@code SqlClob}. |
220 * Characters are read starting at the current position. Each character read |
223 * Characters are read starting at the current position. Each character read |
221 * advances the position by one. |
224 * advances the position by one. |
222 * |
225 * |
223 * ISSUE: There is no character analog to |
226 * ISSUE: There is no character analog to |
224 * {@link java.nio.channels.AsynchronousByteChannel}. It is trivial to |
227 * {@link java.nio.channels.AsynchronousByteChannel}. It is trivial to |