: Class SystemInputStream

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.dalsemi.shell.server
Class SystemInputStream

    java.lang.Object
      |
      +--java.io.InputStream
            |
            +--com.dalsemi.shell.server.SystemInputStream

Direct Known Subclasses:
  SerialInputStream, TelnetInputStream

public class SystemInputStream
extends InputStream

This is an implementation of an `InputStream` for use as `System.in`. Since the underlying root `InputStream` for a TINI program can come from a serial port, a socket, or any other kind of input, the differing behaviors of these input devices must be reconciled by this class. This class must ensure that input becomes available only after an end of line sequence is received, and that the amount available does not represent any 'inaccessible' data (if the data has not been followed by an end of line character). It must also handle '\r', '\n', and '\r\n' as end of line sequences.

See Also:
  `SystemPrintStream`, `Session`

Field Summary
`protected byte[]` | `buffer` The internal buffer that holds all the data that has been received and not yet read by an application.
`protected boolean` | `ECHO` Indicates whether or not to echo the character just read.
`protected int` | `endPos` The ending position in the internal buffer where valid data ends.
`protected static byte[]` | `ERASE` Byte sequence for a backspace.
`String` | `fileInName` If this `SystemInputStream` reads from a file, this represents the name of the file.
`protected PrintStream` | `out` The 'echo' stream.
`protected boolean` | `rawMode` Indicates that the `SystemInputStream` should return data as soon as it is available, and not wait until an end of line sequence is received.
`protected InputStream` | `root` The underlying `InputStream` that this reads from.
`protected Session` | `session` The user session that owns this `SystemInputStream`.
`protected int` | `startPos` The starting position in the internal buffer where valid data is located.

Constructor Summary
`SystemInputStream(InputStream in, PrintStream out)` Creates a new `SystemPrintStream` with the specified underlying root stream and echo stream.
`SystemInputStream(InputStream in, PrintStream out, String fileInName)` Creates a new `SystemInputStream` with the specified underlying root stream and echo stream.

Method Summary
`int` | `available()` Returns the number of bytes that can be read from this input stream without blocking.
`boolean` | `errorOccurred()`
`InputStream` | `getRootStream()` Returns the underlying root `InputStream` of this stream.
`protected void` | `increaseBuffer(int newDataSize)` Ensures the internal buffer is large enough for more data.
`protected int` | `rawAvailable()` This method should be overridden by subclassing `InputStream`s.
`protected int` | `rawRead()` This method should be overridden by subclassing `InputStream`s.
`protected int` | `rawRead(byte[] buff, int off, int len)` Reads from the underlying stream and returns data even if an end of line sequence is not received.
`int` | `read()` Reads the next character from the stream.
`int` | `read(byte[] buff, int off, int len)` Tries to read `len` bytes from the stream.
`String` | `readLine()` Reads a line of text up to but not including the end of line sequence.
`void` | `setEcho(boolean echo)` Turns on and off echoing back characters read by this stream.
`void` | `setEchoStream(PrintStream echo)` Sets the `PrintStream` to echo back characters read by this stream.
`void` | `setRawMode(boolean rawMode)` Sets the mode for reading data from the underlying stream.
`void` | `setRootStream(InputStream newIn)` Sets the underlying `InputStream` to use.
`void` | `setSession(Session session)` Informs this stream of its owning session.

Methods inherited from class java.io.InputStream
`close, mark, markSupported, read, reset, skip`

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

Field Detail

### session

    protected Session session

  The user session that owns this `SystemInputStream`.

### root

    protected InputStream root

  The underlying `InputStream` that this reads from.

### out

    protected PrintStream out

  The 'echo' stream. If `ECHO` is `true`, this `PrintStream` will write everything it reads. This is useful in a telnet session, for instance, when a user types something and it needs to be echoed back to the telnet client.
  See Also:
    `ECHO`

### rawMode

    protected boolean rawMode

  Indicates that the `SystemInputStream` should return data as soon as it is available, and not wait until an end of line sequence is received.
  See Also:
    `rawRead()`, `rawRead(byte[],int,int)`

### buffer

    protected byte[] buffer

  The internal buffer that holds all the data that has been received and not yet read by an application.

### startPos

    protected int startPos

  The starting position in the internal buffer where valid data is located.

### endPos

    protected int endPos

  The ending position in the internal buffer where valid data ends. This is the next available offset for new data into the internal buffer.

### fileInName

    public String fileInName

  If this `SystemInputStream` reads from a file, this represents the name of the file.

### ECHO

    protected boolean ECHO

  Indicates whether or not to echo the character just read.
  See Also:
    `out`

### ERASE

    protected static final byte[] ERASE

  Byte sequence for a backspace. (Arrow back, overwrite next character, then arrow back again.)

Constructor Detail

### SystemInputStream

    public SystemInputStream(InputStream in,
                             PrintStream out)

  Creates a new `SystemPrintStream` with the specified underlying root stream and echo stream.
  Parameters:
    `in` - underlying InputStream to use
    `out` - stream for echo characters

### SystemInputStream

    public SystemInputStream(InputStream in,
                             PrintStream out,
                             String fileInName)

  Creates a new `SystemInputStream` with the specified underlying root stream and echo stream. Calling this constructor signifies that the underlying `InputStream` is reading from a file.
  Parameters:
    `in` - underlying InputStream to use
    `out` - stream for echo characters
    `fileInName` - name of the file this stream is reading from

Method Detail

### setEcho

    public void setEcho(boolean echo)

  Turns on and off echoing back characters read by this stream. This is useful if a session is reading a password, it will not be echoed back to the session.
  Parameters:
    `echo` - `true` to enable echoing, `false` to disable it
  See Also:
    `setEchoStream(java.io.PrintStream)`

### setEchoStream

    public void setEchoStream(PrintStream echo)

  Sets the `PrintStream` to echo back characters read by this stream. Note: you must call `setEcho(true)` to enable echoing.
  Parameters:
    `echo` - stream to echo back characters read
  See Also:
    `setEcho(boolean)`

### setSession

    public void setSession(Session session)

  Informs this stream of its owning session. This allows this stream to call into the session when needed.
  Parameters:
    `session` - the owning session

### rawRead

    protected int rawRead()
                   throws IOException

  This method should be overridden by subclassing `InputStream`s. It should only be called from within a `synchronized` block. It blocks until data is available and returns the first value it reads. It does not wait for an end of line sequence.
  Returns:
    the value read from the underlying stream
  Throws:
    IOException - if an error occurs reading from the underlying stream.
  See Also:
    `rawRead(byte[],int,int)`, `rawAvailable()`, `setRawMode(boolean)`

### rawRead

    protected int rawRead(byte[] buff,
                          int off,
                          int len)
                   throws IOException

  Reads from the underlying stream and returns data even if an end of line sequence is not received. If not operating in raw reading mode, it also checks and handles backspace events. Stops if it finds an end of stream.

  This method should only be called from within a `synchronized` block.

  Returns:
    number of bytes read
  Throws:
    IOException - if an error occurs reading from the underlying stream
  See Also:
    `rawRead()`, `setRawMode(boolean)`, `rawAvailable()`

### rawAvailable

    protected int rawAvailable()
                        throws IOException

  This method should be overridden by subclassing `InputStream`s. It returns the amount available from the underlying root stream. This is not the amount available if the `SystemInputStream` is not in raw mode.
  Returns:
    amount of data available directly from the underlying stream
  Throws:
    IOException - if an error occurs in the underlying stream.
  See Also:
    `setRawMode(boolean)`, `rawRead()`, `rawRead(byte[],int,int)`

### readLine

    public String readLine()

  Reads a line of text up to but not including the end of line sequence. This method will wait for more input if an end of line sequence or the end of the stream cannot be found. This method recognizes '\r', '\n', and '\r\n' and end of line sequences. If the end of the stream is reached, null is returned. Blank lines are returned as empty strings (a `String` of length 0).
  Returns:
    next line of text available from the underlying `InputStream`, or `null` if no more input will be available due to the end of the stream
  See Also:
    `read()`, `read(byte[],int,int)`

### read

    public final int read()
                   throws IOException

  Reads the next character from the stream. If raw mode is not enabled, this method will only return data that has been followed by an end of line sequence.
  Overrides:
    read in class InputStream
  Returns:
    the next character from the stream, or `-1` if the end of the stream has been reached
  Throws:
    IOException - if an error occurs in the underlying stream
  See Also:
    `setRawMode(boolean)`, `readLine()`, `read(byte[],int,int)`

### read

    public int read(byte[] buff,
                    int off,
                    int len)
             throws IOException

  Tries to read `len` bytes from the stream. If the end of stream is encountered, no more data will be read. If raw mode is not enabled, only data that has been followed by an end of line sequence or the end of the stream will be reported. This method will block until enough data is available to return or the end of the stream is reached.
  Overrides:
    read in class InputStream
  Parameters:
    `buff` - byte array to store the data read
    `off` - offset to begin storing data in the array
    `len` - amount of data requested
  Returns:
    the number of characters read, or `-1` if the end of the stream has been reached
  Throws:
    IOException - if an error occurs in the underlying stream
  See Also:
    `read()`, `readLine()`, `setRawMode(boolean)`

### increaseBuffer

    protected void increaseBuffer(int newDataSize)

  Ensures the internal buffer is large enough for more data. This method should only be called from within a `synchronized` block.
  Parameters:
    `newDataSize` - the amount of new data that is about to be copied into the buffer at location `endPos`

### available

    public final int available()
                        throws IOException

  Returns the number of bytes that can be read from this input stream without blocking. This is equivalent to the number of bytes that have been followed by end of line sequences (or by the end of the stream), including the end of line sequences.
  Overrides:
    available in class InputStream
  Returns:
    the number of bytes that can be read from this input stream without blocking
  Throws:
    IOException - if an error occurs in the underlying stream
  See Also:
    `setRawMode(boolean)`

### setRawMode

    public void setRawMode(boolean rawMode)

  Sets the mode for reading data from the underlying stream. If raw mode is set to `true`, any call to read data will return the next available data from the underlying stream. If raw mode is `false`, read calls only report data that has been followed by an end of line character, or the end of the stream, even if the read must block to do so.
  Parameters:
    `rawMode` - `false` to block for an end of line sequence, `true` to return any available data
  See Also:
    `rawRead()`, `rawRead(byte[],int,int)`, `rawAvailable()`, `read()`, `read(byte[],int,int)`, `available()`

### setRootStream

    public void setRootStream(InputStream newIn)

  Sets the underlying `InputStream` to use.
  Parameters:
    `newIn` - new root `InputStream` to use
  See Also:
    `getRootStream()`

### getRootStream

    public InputStream getRootStream()

  Returns the underlying root `InputStream` of this stream.
  Returns:
    the root stream
  See Also:
    `setRootStream(java.io.InputStream)`

### errorOccurred

    public boolean errorOccurred()

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD