A buffered source of characters.
A Source is very similar to a Reader, like:
new InputStreamReader (connection.getInputStream (), charset)
It differs from the above, in three ways:
- the fetching of bytes may be asynchronous
- the character set may be changed, which resets the input stream
- characters may be requested more than once, so in general they
will be buffered
available
public abstract int available()
Get the number of available characters.
- The number of characters that can be read without blocking.
close
public abstract void close()
throws IOException
Does nothing.
It's supposed to close the source, but use
destroy()
instead.
destroy
public abstract void destroy()
throws IOException
getCharacter
public abstract char getCharacter(int offset)
throws IOException
Retrieve a character again.
offset
- The offset of the character.
getCharacters
public abstract void getCharacters(StringBuffer buffer,
int offset,
int length)
throws IOException
Append characters already read into a StringBuffer
.
buffer
- The buffer to append to.offset
- The offset of the first character.length
- The number of characters to retrieve.
getCharacters
public abstract void getCharacters(char[] array,
int offset,
int start,
int end)
throws IOException
Retrieve characters again.
array
- The array of characters.offset
- The starting position in the array where characters are to be placed.start
- The starting position, zero based.end
- The ending position
(exclusive, i.e. the character at the ending position is not included),
zero based.
getEncoding
public abstract String getEncoding()
Get the encoding being used to convert characters.
getString
public abstract String getString(int offset,
int length)
throws IOException
Retrieve a string comprised of characters already read.
offset
- The offset of the first character.length
- The number of characters to retrieve.
- A string containing the
length
characters at offset
.
mark
public abstract void mark(int readAheadLimit)
throws IOException
Mark the present position.
Subsequent calls to
reset()
will attempt to reposition the source to this point. Not all
sources support the mark() operation.
readAheadLimit
- The minimum number of characters that can be read
before this mark becomes invalid.
markSupported
public abstract boolean markSupported()
Tell whether this source supports the mark() operation.
true
if and only if this source supports the mark
operation.
offset
public abstract int offset()
Get the position (in characters).
- The number of characters that have already been read, or
EOF
if the source is closed.
read
public abstract int read()
throws IOException
Read a single character.
This method will block until a character is available,
an I/O error occurs, or the source is exhausted.
- The character read, as an integer in the range 0 to 65535
(0x00-0xffff), or
EOF
if the source is exhausted.
read
public abstract int read(char[] cbuf)
throws IOException
Read characters into an array.
This method will block until some input is available, an I/O error occurs,
or the source is exhausted.
cbuf
- Destination buffer.
- The number of characters read, or
EOF
if the source is
exhausted.
read
public abstract int read(char[] cbuf,
int off,
int len)
throws IOException
Read characters into a portion of an array. This method will block
until some input is available, an I/O error occurs, or the source is
exhausted.
cbuf
- Destination bufferoff
- Offset at which to start storing characterslen
- Maximum number of characters to read
- The number of characters read, or
EOF
if the source is
exhausted.
ready
public abstract boolean ready()
throws IOException
Tell whether this source is ready to be read.
true
if the next read() is guaranteed not to block
for input, false
otherwise.
Note that returning false does not guarantee that the next read will block.
reset
public abstract void reset()
Reset the source.
Repositions the read point to begin at zero.
setEncoding
public abstract void setEncoding(String character_set)
throws ParserException
Set the encoding to the given character set.
If the current encoding is the same as the requested encoding,
this method is a no-op. Otherwise any subsequent characters read from
this source will have been decoded using the given character set.
If characters have already been consumed from this source, it is expected
that an exception will be thrown if the characters read so far would
be different if the encoding being set was used from the start.
character_set
- The character set to use to convert characters.
ParserException
- If a character mismatch occurs between
characters already provided and those that would have been returned
had the new character set been in effect from the beginning. An
exception is also thrown if the character set is not recognized.
skip
public abstract long skip(long n)
throws IOException
Skip characters.
This method will block until some characters are available,
an I/O error occurs, or the source is exhausted.
Note: n is treated as an int
n
- The number of characters to skip.
- The number of characters actually skipped
unread
public abstract void unread()
throws IOException
Undo the read of a single character.