Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javolution.io
Class UTF8StreamReader

    java.lang.Object
      java.io.Reader
          javolution.io.UTF8StreamReader

All Implemented Interfaces:
  java.io.Closeable, java.lang.Readable, Reusable

    public final class UTF8StreamReader

extends java.io.Reader
implements Reusable

This class represents a UTF-8 stream reader.

This reader supports surrogate `char` pairs (representing characters in the range [U+10000 .. U+10FFFF]). It can also be used to read characters unicodes (31 bits) directly (ref. `read()`).

Each invocation of one of the `read()` methods may cause one or more bytes to be read from the underlying byte-input stream. To enable the efficient conversion of bytes to characters, more bytes may be read ahead from the underlying stream than are necessary to satisfy the current read operation.

Instances of this class can be reused for different input streams and can be part of a higher level component (e.g. parser) in order to avoid dynamic buffer allocation when the input source changes. Also wrapping using a `java.io.BufferedReader` is unnescessary as instances of this class embed their own data buffers.

Note: This reader is unsynchronized and does not test if the UTF-8 encoding is well-formed (e.g. UTF-8 sequences longer than necessary to encode a character).

Version:
  2.0, December 9, 2004
Author:
  Jean-Marie Dautelle
See Also:
  `UTF8StreamWriter`

Field Summary

Fields inherited from class java.io.Reader
`lock`

Constructor Summary
`UTF8StreamReader()` Creates a UTF-8 reader having a byte buffer of moderate capacity (2048).
`UTF8StreamReader(int capacity)` Creates a UTF-8 reader having a byte buffer of specified capacity.

Method Summary
`void` | `close()` Closes and `resets` this reader for reuse.
`int` | `read()` Reads a single character.
`void` | `read(java.lang.Appendable dest)` Reads characters into the specified appendable.
`int` | `read(char[] cbuf, int off, int len)` Reads characters into a portion of an array.
`boolean` | `ready()` Indicates if this stream is ready to be read.
`void` | `reset()` Resets the internal state of this object to its default values.
`UTF8StreamReader` | `setInput(java.io.InputStream inStream)` Sets the input stream to use for reading until this reader is closed.
`UTF8StreamReader` | `setInputStream(java.io.InputStream inStream)` Deprecated. Replaced by `setInput(InputStream)`

Methods inherited from class java.io.Reader
`mark, markSupported, read, read, skip`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### UTF8StreamReader

    public UTF8StreamReader()

  Creates a UTF-8 reader having a byte buffer of moderate capacity (2048).

### UTF8StreamReader

    public UTF8StreamReader(int capacity)

  Creates a UTF-8 reader having a byte buffer of specified capacity.

  Parameters:
    `capacity` - the capacity of the byte buffer.

Method Detail

### setInput

    public UTF8StreamReader setInput(java.io.InputStream inStream)

  Sets the input stream to use for reading until this reader is closed. For example:`

           Reader reader = new UTF8StreamReader().setInput(inStream);

  ` is equivalent but reads twice as fast as `

           Reader reader = new java.io.InputStreamReader(inStream, "UTF-8");

  `

  Parameters:
    `inStream` - the input stream.
  Returns:
    this UTF-8 reader.
  Throws:
    `java.lang.IllegalStateException` - if this reader is being reused and it has not been `closed` or `reset`.

### ready

    public boolean ready()
                  throws java.io.IOException

  Indicates if this stream is ready to be read.

  Overrides:
    `ready` in class `java.io.Reader`
  Returns:
    `true` if the next read() is guaranteed not to block for input; `false` otherwise.
  Throws:
    `java.io.IOException` - if an I/O error occurs.

### close

    public void close()
               throws java.io.IOException

  Closes and `resets` this reader for reuse.

  Specified by:
    `close` in interface `java.io.Closeable`
  Specified by:
    `close` in class `java.io.Reader`
  Throws:
    `java.io.IOException` - if an I/O error occurs.

### read

    public int read()
             throws java.io.IOException

  Reads a single character. This method will block until a character is available, an I/O error occurs or the end of the stream is reached.

  Overrides:
    `read` in class `java.io.Reader`
  Returns:
    the 31-bits Unicode of the character read, or -1 if the end of the stream has been reached.
  Throws:
    `java.io.IOException` - if an I/O error occurs.

### read

    public int read(char[] cbuf,
                    int off,
                    int len)
             throws java.io.IOException

  Reads characters into a portion of an array. This method will block until some input is available, an I/O error occurs or the end of the stream is reached.

  Note: Characters between U+10000 and U+10FFFF are represented by surrogate pairs (two `char`).

  Specified by:
    `read` in class `java.io.Reader`
  Parameters:
    `cbuf` - the destination buffer.
    `off` - the offset at which to start storing characters.
    `len` - the maximum number of characters to read
  Returns:
    the number of characters read, or -1 if the end of the stream has been reached
  Throws:
    `java.io.IOException` - if an I/O error occurs.

### read

    public void read(java.lang.Appendable dest)
              throws java.io.IOException

  Reads characters into the specified appendable. This method will block until the end of the stream is reached.

  Parameters:
    `dest` - the destination buffer.
  Throws:
    `java.io.IOException` - if an I/O error occurs.

### reset

    public void reset()

  Description copied from interface: `Reusable`
  Resets the internal state of this object to its default values.

  Specified by:
    `reset` in interface `Reusable`
  Overrides:
    `reset` in class `java.io.Reader`

### setInputStream

    public UTF8StreamReader setInputStream(java.io.InputStream inStream)

  Deprecated. Replaced by `setInput(InputStream)`

Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2005 - 2007 Javolution.