Class UTF8Reader
- java.lang.Object
-
- java.io.Reader
-
- org.apache.derby.impl.jdbc.UTF8Reader
-
- All Implemented Interfaces:
java.io.Closeable
,java.lang.AutoCloseable
,java.lang.Readable
public final class UTF8Reader extends java.io.Reader
Class for reading characters from streams encoded in the modified UTF-8 format.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:
PositionedStoreStream
-
-
Field Summary
Fields Modifier and Type Field Description private char[]
buffer
Internal character buffer storing characters read from the stream.private int
charactersInBuffer
The number of characters in the internal buffer.private CharacterStreamDescriptor
csd
Descriptor containing information about the stream.private java.io.InputStream
in
The underlying data stream.private static int
MAXIMUM_BUFFER_SIZE
Maximum size in number of chars for the internal character buffer.private boolean
noMoreReads
Tells if this reader has been closed.private ConnectionChild
parent
A reference to the parent object of the stream.private PositionedStream
positionedIn
Stream that can reposition itself on request (may benull
).private long
rawStreamPos
Store the last visited position in the store stream, if it is capable of repositioning itself (positionedIn != null
).private static java.lang.String
READER_CLOSED
private long
readerCharCount
Number of characters read from the stream.private int
readPositionInBuffer
The position of the next character to read in the internal buffer.private long
utfCount
Number of bytes read from the stream, including any header bytes.
-
Constructor Summary
Constructors Constructor Description UTF8Reader(CharacterStreamDescriptor csd, ConnectionChild conChild, java.lang.Object sync)
Constructs a reader on top of the source UTF-8 encoded stream.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private int
calculateBufferSize(CharacterStreamDescriptor csd)
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
fillBuffer()
Fills the internal character buffer by decoding bytes from the stream.private 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(java.lang.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
resetUTF8Reader()
Resets the reader.long
skip(long len)
Skips characters.private java.io.IOException
utfFormatException(java.lang.String s)
Convenience method generating anUTFDataFormatException
and cleaning up the reader state.
-
-
-
Field Detail
-
READER_CLOSED
private static final java.lang.String READER_CLOSED
- See Also:
- Constant Field Values
-
MAXIMUM_BUFFER_SIZE
private static final int MAXIMUM_BUFFER_SIZE
Maximum size in number of chars for the internal character buffer.- See Also:
- Constant Field Values
-
in
private java.io.InputStream in
The underlying data stream.
-
positionedIn
private final PositionedStream positionedIn
Stream that can reposition itself on request (may benull
).
-
rawStreamPos
private long rawStreamPos
Store the last visited position in the store stream, if it is capable of repositioning itself (positionedIn != null
).
-
utfCount
private long utfCount
Number of bytes read from the stream, including any header bytes.
-
readerCharCount
private long readerCharCount
Number of characters read from the stream.
-
buffer
private final char[] buffer
Internal character buffer storing characters read from the stream.
-
charactersInBuffer
private int charactersInBuffer
The number of characters in the internal buffer.
-
readPositionInBuffer
private int readPositionInBuffer
The position of the next character to read in the internal buffer.
-
noMoreReads
private boolean noMoreReads
Tells if this reader has been closed.
-
parent
private ConnectionChild 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
private final CharacterStreamDescriptor 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 Detail
-
UTF8Reader
public UTF8Reader(CharacterStreamDescriptor csd, ConnectionChild conChild, java.lang.Object sync) throws java.io.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:
java.io.IOException
- if reading from the underlying stream fails
-
-
Method Detail
-
read
public int read() throws java.io.IOException
Reads a single character from the stream.- Overrides:
read
in classjava.io.Reader
- Returns:
- A character or
-1
if end of stream has been reached. - Throws:
java.io.IOException
- if the stream has been closed, or an exception is raised while reading from the underlying stream
-
read
public int read(char[] cbuf, int off, int len) throws java.io.IOException
Reads characters into an array.- Specified by:
read
in classjava.io.Reader
- Returns:
- The number of characters read, or
-1
if the end of the stream has been reached. - Throws:
java.io.IOException
-
skip
public long skip(long len) throws java.io.IOException
Skips characters.- Overrides:
skip
in classjava.io.Reader
- Parameters:
len
- the numbers of characters to skip- Returns:
- The number of characters actually skipped.
- Throws:
java.lang.IllegalArgumentException
- if the number of characters to skip is negativejava.io.IOException
- if accessing the underlying stream fails
-
close
public void close()
Close the reader, disallowing further reads.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Specified by:
close
in classjava.io.Reader
-
readInto
public int readInto(java.lang.StringBuffer sb, int len) throws java.io.IOException
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:
java.io.IOException
-
readAsciiInto
int readAsciiInto(byte[] abuf, int off, int len) throws java.io.IOException
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:
java.io.IOException
-
closeIn
private void closeIn()
Close the underlying stream if it is open.
-
utfFormatException
private java.io.IOException utfFormatException(java.lang.String s)
Convenience method generating anUTFDataFormatException
and cleaning up the reader state.
-
fillBuffer
private boolean fillBuffer() throws java.io.IOException
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:
java.io.IOException
-
resetUTF8Reader
private void resetUTF8Reader() throws java.io.IOException, StandardException
Resets the reader.This method is used internally to achieve better performance.
- Throws:
java.io.IOException
- if resetting or reading from the stream failsStandardException
- if resetting the stream fails- See Also:
reposition(long)
-
reposition
void reposition(long requestedCharPos) throws java.io.IOException, StandardException
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:
java.io.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
private final int calculateBufferSize(CharacterStreamDescriptor csd)
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
private final void persistentSkip(long toSkip) throws java.io.IOException
Skips the requested number of characters.- Parameters:
toSkip
- number of characters to skip- Throws:
java.io.EOFException
- if there are too few characters in the streamjava.io.IOException
- if reading from the stream fails
-
-