com.claritysys.io
Class SentinelInputStream

java.lang.Object
  extended by java.io.InputStream
      extended by java.io.FilterInputStream
          extended by com.claritysys.io.SentinelInputStream
All Implemented Interfaces:
java.io.Closeable

public class SentinelInputStream
extends java.io.FilterInputStream

An InputStream which allows for accumulating bytes from multiple reads until a specified byte is encountered.

The primary use for this class is as a wrapper in reading from a serial port input stream.

The idea is similar to using a BufferedReader to read a String (BufferedReader.readLine()), but this one does not block. The BufferedReader blocks so long as the underyling reader returns zero bytes read, which for the javax.comm.CommPort InputStream is everytime a ReceiveTimeout occurs, so that's not very handy.

Example:

   SentinelInputStream sis = new SentinelInputStream (port.getInputStream ());
   sis.setSentinel ((byte) '\n');
   byte[] buffer = new byte[1024];
   int bytes = sis.read (buffer);
   if (bytes != -1) {
     // Do something with newline terminated data.
   }
 

Version:
$Revision: 2348 $
See Also:
BufferedReader.readLine(boolean)

Field Summary
protected  byte[] buffer
          A buffer to construct Strings in.
protected  boolean dumpData
          A flag to indicate if, after a read, the stream should produce a hex dump of data to system.out.
protected  int sentinelByte
          The byte which indicates the end of the read.
 
Fields inherited from class java.io.FilterInputStream
in
 
Constructor Summary
SentinelInputStream(java.io.InputStream in)
          Create a new SentinalInputStream which performs reads from the underlying InputStream in.
 
Method Summary
 void clearSentinel()
          Clear the sentinel byte.
 boolean getDumpData()
          Get the current data dump status.
 void matchString(java.lang.String matchString)
          Receive data up to the length of the given String, if it does not match throw an IOException with the actual data received in the message.
 int read()
          Reads the next byte of data from this input stream.
 int read(byte[] b, int off, int len)
          Read a buffer full of data.
 java.lang.String readString(int sentinel, int maxChars)
          Read a String from the underlying stream.
 void setDumpData(boolean dumpData)
          Turn data dumping on or off.
 void setSentinel(byte b)
          Set the sentinel byte.
 
Methods inherited from class java.io.FilterInputStream
available, 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

sentinelByte

protected int sentinelByte
The byte which indicates the end of the read. If < 0, indicates to perform conventional read.


buffer

protected byte[] buffer
A buffer to construct Strings in.


dumpData

protected boolean dumpData
A flag to indicate if, after a read, the stream should produce a hex dump of data to system.out.

Constructor Detail

SentinelInputStream

public SentinelInputStream(java.io.InputStream in)
Create a new SentinalInputStream which performs reads from the underlying InputStream in. If no sentinal byte is set, this acts like the underlying stream in every respect.

Parameters:
in - The underlying InputStream.
Method Detail

setSentinel

public void setSentinel(byte b)
Set the sentinel byte.

Parameters:
b - The byte which should trigger a return from a blocking read().

clearSentinel

public void clearSentinel()
Clear the sentinel byte.


setDumpData

public void setDumpData(boolean dumpData)
Turn data dumping on or off.

Data dumping displays a hex dump to System.out as data is received.

Parameters:
dumpData -

getDumpData

public boolean getDumpData()
Get the current data dump status.

Data dumping displays a hex dump to System.out as data is received.

Returns:
Whether dumpData is enabled or not.

read

public int read()
         throws java.io.IOException
Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

This method simply performs in.read() and returns the result.

Overrides:
read in class java.io.FilterInputStream
Returns:
the next byte of data, or -1 if the end of the stream is reached.
Throws:
java.io.IOException - if an I/O error occurs.
See Also:
FilterInputStream.in

read

public int read(byte[] b,
                int off,
                int len)
         throws java.io.IOException
Read a buffer full of data. If the sentinel byte is set this will block until that byte is encountered or the underlying stream returns EOF (-1 from read()). If EOF is encountered in the underyling stream before the sentinel is encountered, this returns EOF (-1).

If no sentinal is set, simply calls the underyling stream's read (byte[], int, int) method.

Overrides:
read in class java.io.FilterInputStream
Parameters:
b - The byte[] to read data into.
off - The starting position in b to read data to.
len - The maximum number of bytes to read.
Returns:
The number of bytes read, which may be -1 if EOF was encountered even after reading some bytes but before the sentinel was encountered.
Throws:
java.io.IOException - If the underyling stream throws IOException.
See Also:
InputStream, FilterInputStream

readString

public java.lang.String readString(int sentinel,
                                   int maxChars)
                            throws java.io.IOException
Read a String from the underlying stream. The String is terminated (and includes) the given sentinel, and the String will be at most maxChars in length. If longer an IOException will be thrown.

Parameters:
sentinel - The byte that marks the end of the String.
maxChars - The maximum expected number of chars.
Returns:
the String that was read, never null.
Throws:
java.io.IOException - If an thrown by the underlying stream.

matchString

public void matchString(java.lang.String matchString)
                 throws java.io.IOException
Receive data up to the length of the given String, if it does not match throw an IOException with the actual data received in the message.

Parameters:
matchString - The string that should be received.
Throws:
java.io.IOException - If an error occurs on the underlying stream.


Copyright ? 2002 Clarity Systems Group, LLC. All Rights Reserved.