ProcessHandler

The ProcessHandler class allows to:

• Listen to the output and error streams of a Process
• Write to the Process input stream

This class defer the actual work to a listener.

Architecture

The ProcessHandler will redirect the output and error streams of the Process to the listener:

If the constructor was set to allow writing to the Process input, it will also allow to write Strings to the input:

ProcessListener interface

The ProcessHandler.ProcessListener interface has three methods:

• The ProcessHandler.ProcessListener.close() method is called when the streams of the underlying Process are closed
• The ProcessHandler.ProcessListener.readOut(String) method is called when the Process emits a line of text on its output
• The ProcessHandler.ProcessListener.readErr(String) method is called when the Process emits a line of text on its error output

Usage

Creation

The constructor of the ProcessHandler can use a Process or a ProcessBuilder. In the case where a ProcessBuilder has been used, the ProcessHandler will create the Process when starting the handler

The constructor allows to specify if the handler will allow to write to the input stream of the Process.

For example:

   ProcessBuilder pb = new ProcessBuilder("my_executable.exe");
   ProcessHandler phandler = new ProcessHandler(pb, true);

Configuration

After the creation:

• You set the listener with the ProcessHandler.setListener(ProcessListener) method
• You can configure the behavior (see handling the listener in another thread and #handling_the_writing_in_another_threadfor more information)

Starting the handler

Two methods allow to start the ProcessHandler:

• The ProcessHandler.start() method start the handler. it will only do something if the Process already exist (depending on the constructor used too create the ProcessHandler)
• The ProcessHandler.createProcessAndStart() method will create the Process (if it does not already exists (depending on the constructor used too create the ProcessHandler), and start the handler

For example with a Process:

   ProcessBuilder pb = new ProcessBuilder("my_executable.exe");
   try {
      Process process = pb.start();
      ProcessHandler phandler = new ProcessHandler(process);
      List<String> lines = new ArrayList<>
      phandler.setListener(new ProcessHandler.ProcessListener() {
      @Override
      public void readOut(String line) {
        lines.add(line);
      }
      
      @Override
      public void readOut(String line) {
      }      

      @Override
      public void close() {
      }
   });
   } catch (IOException e) {
   }
   phandler.start();

And with a ProcessBuilder:

   ProcessBuilder pb = new ProcessBuilder("my_executable.exe");
   try {
      ProcessHandler phandler = new ProcessHandler(pb);
      List<String> lines = new ArrayList<>
      phandler.setListener(new ProcessHandler.ProcessListener() {
      @Override
      public void readOut(String line) {
        lines.add(line);
      }
      
      @Override
      public void readOut(String line) {
      }      

      @Override
      public void close() {
      }
   });
   } catch (IOException e) {
   }
   phandler.start();

Handling the listener in another thread

By default for each stream the listener is called in the same Thread as the reading of the InputStream, which means that if the stream receives a lot of inputs in a short time, some of them could be discarded by the listener, leading to problems.

The following methods allow to handle the ProcessHandler.ProcessListener.readOut(String) and ProcessHandler.ProcessListener.readOut(String) methods in another Thread using a Queue, which ensures that no event in the InputStream readings will be discarded:

• The ProcessHandler.setInputQueued(boolean, int, int) will queue the InputStream reading events and use them in the listener in another Thread. Between each even, there will be a delay of x ms, and a polling of y ms
• The ProcessHandler.setInputQueued(boolean, int) will queue the InputStream reading events and use them in the listener in another Thread. Between each even, there will be a delay of x ms
• The ProcessHandler.setInputQueued(boolean) will queue the InputStream reading events and use them in the listener in another Thread, with no delay

Handling the writing in another thread

The following methods allow to handle the ProcessHandler.writeIn(String, boolean) method in another Thread using a Queue, which ensures that to event in the OutputStream writings will be discarded:

• The ProcessHandler.setOutputQueued(boolean, int, int) will queue the OutputStream writing events in another Thread. Between each even, there will be a delay of x ms, and a polling of y ms
• The ProcessHandler.setOutputQueued(boolean, int) will queue the OutputStream writing events in another Thread. Between each even, there will be a delay of x ms
• The ProcessHandler.setOutputQueued(boolean) will queue the OutputStream writing events in another Thread, with no delay

Example

The following code will redirect the output of an executable (normally on the console) to a List of Strings:

   ProcessBuilder pb = new ProcessBuilder("my_executable.exe");
      
   ProcessHandler phandler = new ProcessHandler(pb);
   List<String> lines = new ArrayList<>
   phandler.setListener(new ProcessHandler.ProcessListener() {
      @Override
      public void readOut(String line) {
        lines.add(line);
      }
      
      @Override
      public void readOut(String line) {
      }      

      @Override
      public void close() {
      }
   });
   phandler.start();