net.sf.eclipseexeditor.textfilter
Class Filter

java.lang.Object
  net.sf.eclipseexeditor.textfilter.Filter

Direct Known Subclasses:

ProgressFilter

public class Filter

extends Object

Filter runs a Unix style filter on an input string, returning the result as a String.

 
 Filter myFilter = new Filter("my-filter-command"};
 

Invoke the filter with input:

 String result = myFilter.filter("some text to process");
 

Filter then runs an external process, piping the input string to the process and returning the output.

You can also invoke the filter with an array of Strings to get an array of strings back (possibly of a different length, depending on the output of the filter) or simply provide an input stream.

Filter currently uses the default system encoding to transcode Unicode Java strings into byte arrays and back - the filter pipeline works on byte data.

Currently, any standard error output is lost.

Currently, there is no handling of return codes. The command may not exist or it may receive an error, but this information is lost, unless there is an exception reading the output.

This class (despite its package name) is meant to be usable outside of Eclipse and thus does not use any Eclipse API. Notably, it supports a callback API, intended for subclasses to override, for a progress monitor.

• #startFilterProgress()
• progress(int)
• finishFilterMonitor()

Author:

David Biesack David.Biesack@mindspring.com

Constructor Summary

Filter(String filter)
Construct a Filter that will run the filter command.

Method Summary

protected void	finishFilterMonitor() Called when the filter process finishes running.
String	getFilterCommand()
protected void	interrupt() Interrupt the running process, if it exists.
protected void	progress(int i) Called as the filter process makes progress, notably, for each character processed.
String	run(String text) Run the filter on text and return the filtered output.
String[]	run(String[] lines) Run the filter over an array of strings, returning an array of text lines as the result
protected void	startFilterProgess() Called when the filter process begins running.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Filter

public Filter(String filter)

Construct a Filter that will run the filter command. Note that if you wish the command to use redirection or other special shell command syntax

Parameters:

filter - the name of an operating system command that accepts standard input and writes standard output.

Method Detail

getFilterCommand

public String getFilterCommand()

run

public String[] run(String[] lines)
             throws FilterException

Run the filter over an array of strings, returning an array of text lines as the result

Parameters:

lines - an array of input lines. This parameter may not be null, nor may any of the elements.

Returns:

an array of ouput text lines from running the filter.

Throws:

FilterException - if there was a problem running the exception or reading its output.

finishFilterMonitor

protected void finishFilterMonitor()

Called when the filter process finishes running. This is a Template method which subclasses can override if they wish to monitor the filter process execution.

progress

protected void progress(int i)

Called as the filter process makes progress, notably, for each character processed. (This is of course approximate, as the process may buffer input and/or output.) This is a Template method which subclasses can override if they wish to monitor the filter process execution.

startFilterProgess

protected void startFilterProgess()

Called when the filter process begins running. This is a Template method which subclasses can override if they wish to monitor the filter process execution.

run

public String run(String text)
           throws FilterException

Run the filter on text and return the filtered output.

Parameters:

text - some input text

Returns:

the result of running the filter on the text.

Throws:

FilterException - if there was a problem running the exception or reading its output.

interrupt

protected void interrupt()

Interrupt the running process, if it exists. Subclasses may call this, i.e. if a progress monitor or user input determines the process is a runaway or is not terminating as soon as expected.