net.sf.mmm.util.process.api.ProcessUtil Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mmm-util-io Show documentation
Utilities for input/output and streaming.
The newest version!
/* Copyright (c) The m-m-m Team, Licensed under the Apache License, Version 2.0
 * http://www.apache.org/licenses/LICENSE-2.0 */
package net.sf.mmm.util.process.api;

import java.io.IOException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

/**
 * This is the interface for a collection of utility functions to deal with {@link Process}es.
 *
 * @see net.sf.mmm.util.process.base.ProcessUtilImpl
 *
 * @author Joerg Hohwiller (hohwille at users.sourceforge.net)
 * @since 1.0.2
 */
public interface ProcessUtil {

  /**
   * This method executes the external {@link Process}es configured by the given {@code builders}. If more
   * than one {@link ProcessBuilder builder} is given, the according processes are piped. 

   *
   * @param context is the context of the process pipe (fist {@code stdin}, last {@code stdout} and
   *        {@code stderr} for all processes as well as a potential timeout).
   * @param builders are the configurations of the {@link Process}(es) to execute. The array needs to have a
   *        length greater than zero.
   * @return the {@link Process#waitFor() exit-code} of the {@link Process}-pipe configured by the given
   *         {@code builders}.
   * @throws IOException if an input/output-error occurred.
   * @throws InterruptedException if the calling {@link Thread} was interrupted while {@link Process#waitFor()
   *         waiting for} a {@link Process} to complete.
   */
  int execute(ProcessContext context, ProcessBuilder... builders) throws IOException, InterruptedException;

  /**
   * This method executes the external {@link Process}es configured by the given {@code builders}. If more
   * than one {@link ProcessBuilder builder} is given, the according processes are piped. 

   * ATTENTION:

   * This method spins up multiple {@link Thread threads}, especially when multiple processes are piped
   * (2*n+1[+1] threads). Therefore you should NOT use the
   * {@link net.sf.mmm.util.process.base.ProcessUtilImpl#getInstance() singleton} variant of this util except
   * you are writing a simple command-line client that does a simple job and then terminates. When writing a
   * server-application or library, that makes such calls repetitive, you should create your own instance of
   * {@link ProcessUtil} and configure a thread-pool as {@link java.util.concurrent.Executor}.
   *
   * @param context is the context of the process pipe (fist {@code stdin}, last {@code stdout} and
   *        {@code stderr} for all processes as well as a potential timeout).
   * @param timeout is the maximum amount of time to wait for the {@link Process}-pipe to finish.
   * @param unit is the {@link TimeUnit} of the given {@code timeout} argument.
   * @param builders are the configurations of the {@link Process}(es) to execute. The array needs to have a
   *        length greater than zero.
   * @return the {@link Process#waitFor() exit-code} of the {@link Process}-pipe configured by the given
   *         {@code builders}.
   * @throws IOException if an input/output-error occurred.
   * @throws TimeoutException if the {@link Process}-pipe did NOT complete before the given {@code timeout}
   *         (according to {@code unit}).
   * @throws InterruptedException if the calling {@link Thread} was interrupted while waiting for the
   *         {@link Process} -pipe to complete and before the {@code timeout} occurred.
   */
  int execute(ProcessContext context, long timeout, TimeUnit unit, ProcessBuilder... builders) throws IOException, TimeoutException, InterruptedException;

  /**
   * This method executes the external {@link Process}es configured by the given {@code builders} as async
   * task. If more than one {@link ProcessBuilder builder} is given, the according processes are piped. 

   * ATTENTION:

   * This method spins up multiple {@link Thread threads}, especially when multiple processes are piped
   * (2*n+1[+1] threads). Therefore you should NOT use the
   * {@link net.sf.mmm.util.process.base.ProcessUtilImpl#getInstance() singleton} variant of this util except
   * you are writing a simple command-line client that does a simple job and then terminates. When writing a
   * server-application or library, that makes such calls repetitive, you should create your own instance of
   * {@link ProcessUtil} and configure a thread-pool as {@link java.util.concurrent.Executor}.
   *
   * @param context is the context of the process pipe (fist {@code stdin}, last {@code stdout} and
   *        {@code stderr} for all processes as well as a potential timeout).
   * @param builders are the configurations of the {@link Process}(es) to execute. The array needs to have a
   *        length greater than zero.
   * @return the {@link Process#waitFor() exit-code} of the {@link Process}-pipe configured by the given
   *         {@code builders}.
   * @throws IOException if an input/output-error occurred while setting up the {@link Process}(es).
   */
  AsyncProcessExecutor executeAsync(ProcessContext context, ProcessBuilder... builders) throws IOException;

}