Class UTF8Reader
- All Implemented Interfaces:
Closeable
,AutoCloseable
,Readable
Note that we often operate on a special Derby stream.
A Derby stream is possibly different from a "normal" stream in two ways;
an encoded length is inserted at the head of the stream, and if the encoded
length is 0
a Derby-specific end of stream marker is appended
to the data.
If the underlying stream is capable of repositioning itself on request, this class supports multiple readers on the same source stream in such a way that the various readers do not interfere with each other (except for serializing access). Each reader instance will have its own pointer into the stream, and request that the stream repositions itself before calling read/skip on the stream.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final char[]
Internal character buffer storing characters read from the stream.private int
The number of characters in the internal buffer.private final CharacterStreamDescriptor
Descriptor containing information about the stream.private InputStream
The underlying data stream.private static final int
Maximum size in number of chars for the internal character buffer.private boolean
Tells if this reader has been closed.private ConnectionChild
A reference to the parent object of the stream.private final PositionedStream
Stream that can reposition itself on request (may benull
).private long
Store the last visited position in the store stream, if it is capable of repositioning itself (positionedIn != null
).private static final String
private long
Number of characters read from the stream.private int
The position of the next character to read in the internal buffer.private long
Number of bytes read from the stream, including any header bytes. -
Constructor Summary
ConstructorsConstructorDescriptionUTF8Reader
(CharacterStreamDescriptor csd, ConnectionChild conChild, Object sync) Constructs a reader on top of the source UTF-8 encoded stream. -
Method Summary
Modifier and TypeMethodDescriptionprivate final int
Calculates an optimized buffer size.void
close()
Close the reader, disallowing further reads.private void
closeIn()
Close the underlying stream if it is open.private boolean
Fills the internal character buffer by decoding bytes from the stream.private final void
persistentSkip
(long toSkip) Skips the requested number of characters.int
read()
Reads a single character from the stream.int
read
(char[] cbuf, int off, int len) Reads characters into an array.(package private) int
readAsciiInto
(byte[] abuf, int off, int len) Reads characters into an array as ASCII characters.int
readInto
(StringBuffer sb, int len) Reads characters from the stream.(package private) void
reposition
(long requestedCharPos) Repositions the stream so that the next character read will be the character at the requested position.private void
Resets the reader.long
skip
(long len) Skips characters.private IOException
Convenience method generating anUTFDataFormatException
and cleaning up the reader state.Methods inherited from class java.io.Reader
mark, markSupported, nullReader, read, read, ready, reset, transferTo
-
Field Details
-
READER_CLOSED
- See Also:
-
MAXIMUM_BUFFER_SIZE
private static final int MAXIMUM_BUFFER_SIZEMaximum size in number of chars for the internal character buffer.- See Also:
-
in
The underlying data stream. -
positionedIn
Stream that can reposition itself on request (may benull
). -
rawStreamPos
private long rawStreamPosStore the last visited position in the store stream, if it is capable of repositioning itself (positionedIn != null
). -
utfCount
private long utfCountNumber of bytes read from the stream, including any header bytes. -
readerCharCount
private long readerCharCountNumber of characters read from the stream. -
buffer
private final char[] bufferInternal character buffer storing characters read from the stream. -
charactersInBuffer
private int charactersInBufferThe number of characters in the internal buffer. -
readPositionInBuffer
private int readPositionInBufferThe position of the next character to read in the internal buffer. -
noMoreReads
private boolean noMoreReadsTells if this reader has been closed. -
parent
A reference to the parent object of the stream.The reference is kept so that the parent object can't get garbage collected until we are done with the stream.
-
csd
Descriptor containing information about the stream. Except for the current positions, the information in this object is considered permanent and valid for the life-time of the stream.
-
-
Constructor Details
-
UTF8Reader
public UTF8Reader(CharacterStreamDescriptor csd, ConnectionChild conChild, Object sync) throws IOException Constructs a reader on top of the source UTF-8 encoded stream.- Parameters:
csd
- a description of and reference to the source streamconChild
- the parent object / connection childsync
- synchronization object used when accessing the underlying data stream- Throws:
IOException
- if reading from the underlying stream fails
-
-
Method Details
-
read
Reads a single character from the stream.- Overrides:
read
in classReader
- Returns:
- A character or
-1
if end of stream has been reached. - Throws:
IOException
- if the stream has been closed, or an exception is raised while reading from the underlying stream
-
read
Reads characters into an array.- Specified by:
read
in classReader
- Returns:
- The number of characters read, or
-1
if the end of the stream has been reached. - Throws:
IOException
-
skip
Skips characters.- Overrides:
skip
in classReader
- Parameters:
len
- the numbers of characters to skip- Returns:
- The number of characters actually skipped.
- Throws:
IllegalArgumentException
- if the number of characters to skip is negativeIOException
- if accessing the underlying stream fails
-
close
public void close()Close the reader, disallowing further reads. -
readInto
Reads characters from the stream.Due to internal buffering a smaller number of characters than what is requested might be returned. To ensure that the request is fulfilled, call this method in a loop until the requested number of characters is read or
-1
is returned.- Parameters:
sb
- the destination bufferlen
- maximum number of characters to read- Returns:
- The number of characters read, or
-1
if the end of the stream is reached. - Throws:
IOException
-
readAsciiInto
Reads characters into an array as ASCII characters.Due to internal buffering a smaller number of characters than what is requested might be returned. To ensure that the request is fulfilled, call this method in a loop until the requested number of characters is read or
-1
is returned.Characters outside the ASCII range are replaced with an out of range marker.
- Parameters:
abuf
- the buffer to read intooff
- the offset into the destination bufferlen
- maximum number of characters to read- Returns:
- The number of characters read, or
-1
if the end of the stream is reached. - Throws:
IOException
-
closeIn
private void closeIn()Close the underlying stream if it is open. -
utfFormatException
Convenience method generating anUTFDataFormatException
and cleaning up the reader state. -
fillBuffer
Fills the internal character buffer by decoding bytes from the stream.- Returns:
true
if the end of the stream is reached,false
if there is apparently more data to be read.- Throws:
IOException
-
resetUTF8Reader
Resets the reader.This method is used internally to achieve better performance.
- Throws:
IOException
- if resetting or reading from the stream failsStandardException
- if resetting the stream fails- See Also:
-
reposition
Repositions the stream so that the next character read will be the character at the requested position.There are three types of repositioning, ordered after increasing cost:
- Reposition within current character buffer (small hops forwards
and potentially backwards - in range 1 char to
MAXIMUM_BUFFER_SIZE
chars) - Forward stream from current position (hops forwards)
- Reset stream and skip data (hops backwards)
- Parameters:
requestedCharPos
- 1-based requested character position- Throws:
IOException
- if resetting or reading from the stream failsStandardException
- if resetting the stream fails
- Reposition within current character buffer (small hops forwards
and potentially backwards - in range 1 char to
-
calculateBufferSize
Calculates an optimized buffer size.The maximum size allowed is returned if the specified values don't give enough information to say a smaller buffer size is preferable.
- Parameters:
csd
- stream descriptor- Returns:
- An (sub)optimal buffer size.
-
persistentSkip
Skips the requested number of characters.- Parameters:
toSkip
- number of characters to skip- Throws:
EOFException
- if there are too few characters in the streamIOException
- if reading from the stream fails
-