org.mpr.util
Class StreamSplitter

java.lang.Object
  java.lang.Thread
      org.mpr.util.StreamSplitter

All Implemented Interfaces:

java.lang.Runnable

public class StreamSplitter
extends java.lang.Thread

Continuously funnels the data from an InputStream to a group of OutputStreams.

StreamSplitter is a thread, so you can call run() to block until the InputStream is exhausted, or Thread.start() to have the splitter work continuously in the background. You can control the size of the internal buffer and read latency to fine tune for bulk throughput and smooth updating. You'll get decent performance from this class with the right fiddling.

You can also use StreamSplitter from a command line, though you are limited to files and standard in/out/err. The examples below show several useful scenarios:

• Copying a file (cp):

              (new StreamSplitter(
                  new FileInputStream(srcfile),
                  new FileOutputStream(dstfile)))
                .run();

  From the command line: java org.mpr.util.StreamSplitter srcfile dstfile
  For a large file (almost as fast as cp!): java org.mpr.util.StreamSplitter -b 500000 srcfile dstfile

• Splitting input to a file and output (tee):

              (new StreamSplitter(
                  System.in,
                  System.out,
                  new FileOutputStream(file)))
                .run();

  From the command line: java org.mpr.util.StreamSplitter in out file

• Following a log file as it grows (tail -f):

              StreamSplitter splitter =
                  new StreamSplitter(
                      new FileInputStream(file),
                      System.out);
              splitter.setHaltOnEOF(false);
              splitter.run();

  From the command line: java org.mpr.util.StreamSplitter -f file out
  For much smoother output than tail -f, try: java org.mpr.util.StreamSplitter -f -l 2 file out

• See TCPTunnel for an interesting network example.

Maturity: This is mature code. It has worked nicely in real-world settings.

Plans: There are no current plans to expand or revise this class's functionality. High-volume performance testing and tuning might be useful in the future.

Version:

May 10 2001

Author:

Paul Cantrell

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

StreamSplitter(java.io.InputStream in, java.util.Collection outs)
Creates a new splitter from an input stream to an arbitrary number of output streams.

StreamSplitter(java.io.InputStream in, java.io.OutputStream out)
Creates a new splitter from an input stream to a single output stream.

StreamSplitter(java.io.InputStream in, java.io.OutputStream[] out)
Creates a new splitter from an input stream to an arbitrary number of output streams.

StreamSplitter(java.io.InputStream in, java.io.OutputStream out1, java.io.OutputStream out2)
Creates a new splitter from an input stream to two output streams.

Method Summary

int	getBufferSize() Returns the maximum number of bytes the splitter will read or write at once.
long	getByteCount() Returns the number of bytes this splitter has read from its input.
boolean	getHaltOnEOF() Determines whether the splitter will halt when it reads EOF, or will wait for more input.
int	getLatency() Returns the time in milliseconds which this splitter will sleep waiting for new input.
boolean	getVerbose() Turns debugging output on and off, including exception stack traces.
void	halt() Asks this splitter to halt at its earliest convenience.
boolean	isDone() Returns true if the splitter has run and has halted.
static void	main(java.lang.String[] args) Command line handling
void	run() Reads bytes from the input stream and writes them to the output streams until one of the following happens: The input stream terminates and the haltOnEOF property is true.
void	setBufferSize(int bufferSize) Sets the maximum number of bytes the splitter will read or write at once.
void	setHaltOnEOF(boolean haltOnEOF) Determines whether the splitter will halt when it reads EOF, or will wait for more input.
void	setLatency(int latency) Sets the time in milliseconds which this splitter will sleep waiting for new input.
void	setVerbose(boolean verbose) Turns debugging output on and off, including exception stack traces.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StreamSplitter

public StreamSplitter(java.io.InputStream in,
                      java.io.OutputStream[] out)

Creates a new splitter from an input stream to an arbitrary number of output streams. The out parameter may be empty.

StreamSplitter

public StreamSplitter(java.io.InputStream in,
                      java.util.Collection outs)

Creates a new splitter from an input stream to an arbitrary number of output streams. The out parameter may be empty.

StreamSplitter

public StreamSplitter(java.io.InputStream in,
                      java.io.OutputStream out)

Creates a new splitter from an input stream to a single output stream. The out parameter may be null.

StreamSplitter

public StreamSplitter(java.io.InputStream in,
                      java.io.OutputStream out1,
                      java.io.OutputStream out2)

Creates a new splitter from an input stream to two output streams. Both out1 and out2 may be null.

Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException

Command line handling

Throws:

java.io.IOException

run

public void run()

Reads bytes from the input stream and writes them to the output streams until one of the following happens:

• The input stream terminates and the haltOnEOF property is true.
• An exception occurs (i.e. socket closed).
• The thread is interrupted.

If splitting terminates due to an exception, and if verbose property is true, then the exception goes to System.err; otherwise, this method fails quietly.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

halt

public void halt()

Asks this splitter to halt at its earliest convenience. If the splitter is blocked waiting for input, it will continue to block; if you need to stop it immediately, use Thread.interrupt(). To check whether the splitter has halted, use isDone().

isDone

public boolean isDone()

Returns true if the splitter has run and has halted.

getHaltOnEOF

public boolean getHaltOnEOF()

Determines whether the splitter will halt when it reads EOF, or will wait for more input. This property is true by default.

setHaltOnEOF

public void setHaltOnEOF(boolean haltOnEOF)

Determines whether the splitter will halt when it reads EOF, or will wait for more input. True by default.

getVerbose

public boolean getVerbose()

Turns debugging output on and off, including exception stack traces. True by default.

setVerbose

public void setVerbose(boolean verbose)

Turns debugging output on and off, including exception stack traces. True by default.

getBufferSize

public int getBufferSize()

Returns the maximum number of bytes the splitter will read or write at once. The default buffer size is 32k.

setBufferSize

public void setBufferSize(int bufferSize)

Sets the maximum number of bytes the splitter will read or write at once. This only affects future calls to run(); if the splitter is already running, it will continue to use its current buffer size.

getLatency

public int getLatency()

Returns the time in milliseconds which this splitter will sleep waiting for new input. The default latency is 30ms.

setLatency

public void setLatency(int latency)

Sets the time in milliseconds which this splitter will sleep waiting for new input. A longer latency may speed things up if a lot of data is moving through the pipe, but may slow things down if the data is arriving slowly or in bursts.

getByteCount

public long getByteCount()

Returns the number of bytes this splitter has read from its input.