1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
/*
* Copyright 2006-2012 Amazon Technologies, Inc. or its affiliates.
* Amazon, Amazon.com and Carbonado are trademarks or registered trademarks
* of Amazon Technologies, Inc. or its affiliates. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.amazon.carbonado.lob;
import java.io.Reader;
import java.io.Writer;
import com.amazon.carbonado.FetchException;
import com.amazon.carbonado.PersistException;
/**
* Provides access to CLOBs, which are Character Large OBjects. Consider
* accessing Clobs within a {@link com.amazon.carbonado.Transaction
* transaction} scope, to prevent unexpected updates.
*
* @author Brian S O'Neill
* @see Blob
*/
public interface Clob extends Lob {
/**
* Returns a Reader for reading Clob data, positioned at the start. The
* Clob implementation selects an appropriate buffer size for the reader.
*
* @return Reader for this Blob, which is not guaranteed to be thread-safe
* @throws IllegalArgumentException if position is negative
*/
Reader openReader() throws FetchException;
/**
* Returns a Reader for reading Clob data. The Clob implementation selects
* an appropriate buffer size for the reader.
*
* @param pos desired zero-based position to read from
* @return Reader for this Blob, which is not guaranteed to be thread-safe
* @throws IllegalArgumentException if position is negative
*/
Reader openReader(long pos) throws FetchException;
/**
* Returns a Reader for reading Clob data. A suggested buffer size must be
* provided, but it might be ignored by the Clob implementation.
*
* @param pos desired zero-based position to read from
* @param bufferSize suggest that the reader buffer be at least this large (in characters)
* @return Reader for this Blob, which is not guaranteed to be thread-safe
* @throws IllegalArgumentException if position is negative
*/
Reader openReader(long pos, int bufferSize) throws FetchException;
/**
* Returns the length of this Clob, in characters.
*/
long getLength() throws FetchException;
/**
* Convenience method to capture all the Clob data as a single String. Call
* within a transaction scope to ensure the data does not change while the
* String is being built.
*
* @throws IllegalArgumentException if Clob length is greater than Integer.MAX_VALUE
* @throws OutOfMemoryError if not enough memory to hold Clob as a single String
*/
String asString() throws FetchException;
/**
* Returns a Writer for writing Clob data, positioned at the start. The
* Clob implementation selects an appropriate buffer size for the writer.
*
* @return Writer for this Blob, which is not guaranteed to be thread-safe
* @throws IllegalArgumentException if position is negative
*/
Writer openWriter() throws PersistException;
/**
* Returns a Writer for writing Clob data. The Clob implementation selects
* an appropriate buffer size for the writer.
*
* @param pos desired zero-based position to write to
* @return Writer for this Blob, which is not guaranteed to be thread-safe
* @throws IllegalArgumentException if position is negative
*/
Writer openWriter(long pos) throws PersistException;
/**
* Returns a Writer for writing Clob data. A suggested buffer size must be
* provided, but it might be ignored by the Clob implementation.
*
* @param pos desired zero-based position to write to
* @param bufferSize suggest that the writer buffer be at least this large (in characters)
* @return Writer for this Blob, which is not guaranteed to be thread-safe
* @throws IllegalArgumentException if position is negative
*/
Writer openWriter(long pos, int bufferSize) throws PersistException;
/**
* Set the length of this Clob, in characters. If the new length is
* shorter, the Clob is truncated. If the new length is longer, the Clob is
* padded with '\0' characters.
*
* @param length new length to set to
* @throws IllegalArgumentException if length is negative
* @throws com.amazon.carbonado.PersistDeniedException if Clob is read-only
*/
void setLength(long length) throws PersistException;
/**
* Convenience method to overwrite all Clob data with the value of a single
* String. The Clob length may grow or shrink, to match the String
* value. Call within a transaction scope to ensure the data and length
* does not change while the value is set.
*
* @param value Clob is overwritten with this value
* @throws IllegalArgumentException if value is null
*/
void setValue(String value) throws PersistException;
}
|
