FileDocCategorySizeDatePackage
Reader.javaAPI DocAndroid 1.5 API10439Wed May 06 22:41:04 BST 2009java.io

Reader

public abstract class Reader extends Object implements Closeable, Readable
The base class for all readers. A reader is a means of reading data from a source in a character-wise manner. Some readers also support marking a position in the input and returning to this position later.

This abstract class does not provide a fully working implementation, so it needs to be subclassed, and at least the {@link #read(char[], int, int)} and {@link #close()} methods needs to be overridden. Overriding some of the non-abstract methods is also often advised, since it might result in higher efficiency.

Many specialized readers for purposes like reading from a file already exist in this package.

see
Writer
since
Android 1.0

Fields Summary
protected Object
lock
The object used to synchronize access to the reader.
Constructors Summary
protected Reader()
Constructs a new {@code Reader} with {@code this} as the object used to synchronize critical sections.

since
Android 1.0

        super();
        lock = this;
    
protected Reader(Object lock)
Constructs a new {@code Reader} with {@code lock} used to synchronize critical sections.

param
lock the {@code Object} used to synchronize critical sections.
throws
NullPointerException if {@code lock} is {@code null}.
since
Android 1.0

        if (lock == null) {
            throw new NullPointerException();
        }
        this.lock = lock;
    
Methods Summary
public abstract voidclose()
Closes this reader. Implementations of this method should free any resources associated with the reader.

throws
IOException if an error occurs while closing this reader.
since
Android 1.0

public voidmark(int readLimit)
Sets a mark position in this reader. The parameter {@code readLimit} indicates how many characters can be read before the mark is invalidated. Calling {@code reset()} will reposition the reader back to the marked position if {@code readLimit} has not been surpassed.

This default implementation simply throws an {@code IOException}; subclasses must provide their own implementation.

param
readLimit the number of characters that can be read before the mark is invalidated.
throws
IllegalArgumentException if {@code readLimit < 0}.
throws
IOException if an error occurs while setting a mark in this reader.
see
#markSupported()
see
#reset()
since
Android 1.0

        throw new IOException();
    
public booleanmarkSupported()
Indicates whether this reader supports the {@code mark()} and {@code reset()} methods. This default implementation returns {@code false}.

return
always {@code false}.
since
Android 1.0

        return false;
    
public intread(java.nio.CharBuffer target)
Reads characters and puts them into the {@code target} character buffer.

param
target the destination character buffer.
return
the number of characters put into {@code target} or -1 if the end of this reader has been reached before a character has been read.
throws
IOException if any I/O error occurs while reading from this reader.
throws
NullPointerException if {@code target} is {@code null}.
throws
ReadOnlyBufferException if {@code target} is read-only.
since
Android 1.0

        if (null == target) {
            throw new NullPointerException();
        }
        int length = target.length();
        char[] buf = new char[length];
        length = Math.min(length, read(buf));
        if (length > 0) {
            target.put(buf, 0, length);
        }
        return length;
    
public intread()
Reads a single character from this reader and returns it as an integer with the two higher-order bytes set to 0. Returns -1 if the end of the reader has been reached.

return
the character read or -1 if the end of the reader has been reached.
throws
IOException if this reader is closed or some other I/O error occurs.
since
Android 1.0

        synchronized (lock) {
            char charArray[] = new char[1];
            if (read(charArray, 0, 1) != -1) {
                return charArray[0];
            }
            return -1;
        }
    
public intread(char[] buf)
Reads characters from this reader and stores them in the character array {@code buf} starting at offset 0. Returns the number of characters actually read or -1 if the end of the reader has been reached.

param
buf character array to store the characters read.
return
the number of characters read or -1 if the end of the reader has been reached.
throws
IOException if this reader is closed or some other I/O error occurs.
since
Android 1.0

        // BEGIN android-note
        // changed array notation to be consistent with the rest of harmony
        // END android-note
        return read(buf, 0, buf.length);
    
public abstract intread(char[] buf, int offset, int count)
Reads at most {@code count} characters from this reader and stores them at {@code offset} in the character array {@code buf}. Returns the number of characters actually read or -1 if the end of the reader has been reached.

param
buf the character array to store the characters read.
param
offset the initial position in {@code buffer} to store the characters read from this reader.
param
count the maximum number of characters to read.
return
the number of characters read or -1 if the end of the reader has been reached.
throws
IOException if this reader is closed or some other I/O error occurs.
since
Android 1.0

public booleanready()
Indicates whether this reader is ready to be read without blocking. Returns {@code true} if this reader will not block when {@code read} is called, {@code false} if unknown or blocking will occur. This default implementation always returns {@code false}.

return
always {@code false}.
throws
IOException if this reader is closed or some other I/O error occurs.
see
#read()
see
#read(char[])
see
#read(char[], int, int)
since
Android 1.0

        return false;
    
public voidreset()
Resets this reader's position to the last {@code mark()} location. Invocations of {@code read()} and {@code skip()} will occur from this new location. If this reader has not been marked, the behavior of {@code reset()} is implementation specific. This default implementation throws an {@code IOException}.

throws
IOException always thrown in this default implementation.
see
#mark(int)
see
#markSupported()
since
Android 1.0

        throw new IOException();
    
public longskip(long count)
Skips {@code amount} characters in this reader. Subsequent calls of {@code read} methods will not return these characters unless {@code reset()} is used. This method may perform multiple reads to read {@code count} characters.

param
count the maximum number of characters to skip.
return
the number of characters actually skipped.
throws
IllegalArgumentException if {@code amount < 0}.
throws
IOException if this reader is closed or some other I/O error occurs.
see
#mark(int)
see
#markSupported()
see
#reset()
since
Android 1.0

        if (count < 0) {
            throw new IllegalArgumentException();
        }
        synchronized (lock) {
            long skipped = 0;
            int toRead = count < 512 ? (int) count : 512;
            char charsSkipped[] = new char[toRead];
            while (skipped < count) {
                int read = read(charsSkipped, 0, toRead);
                if (read == -1) {
                    return skipped;
                }
                skipped += read;
                if (read < toRead) {
                    return skipped;
                }
                if (count - skipped < toRead) {
                    toRead = (int) (count - skipped);
                }
            }
            return skipped;
        }