tribble.util
Class RuntimeExec

java.lang.Object
  extended by tribble.util.RuntimeExec

public class RuntimeExec
extends java.lang.Object

Contains methods to execute a command shell in a separate process. This is designed to be a replacement for the java.lang.Runtime.exec() methods.

The java.lang.Runtime.exec() method is horribly designed. To use it, the calling program (i.e., the programmer writing the calling program) is burdened with handling all of the data written to the standard output and error streams. This takes an rather large amount of code, involving threads and being very difficult to do correctly.

Hence the need for this class. It provides a much more straightforward API method, exec(), which handles all of the nasty details of redirecting the standard I/O streams.

Implementation Notes

The exec() method(s) invoke the default command shell program for the native operating system. The name of this program is determined by examining the native operating system name, which is stored as the "os.name" system property, and using this to look up the command shell name in a hard-coded table (SHELL_PGMS[]). As coded, only a minimal set of operating systems are contained in the table, so it is likely that the table will need to be amended when porting this class to other systems.

Since:
2006-08-08
Version:
$Revision: 1.4 $ $Date: 2007/04/28 15:02:54 $
Author:
David R. Tribble (david@tribble.com).

Copyright 2007 by David R. Tribble, all rights reserved.
Permission is granted to any person or entity except those designated by by the United States Department of State as a terrorist, or terrorist government or agency, to use and distribute this source code provided that the original copyright notice remains present and unaltered.

If you find this software useful, please drop me a note describing how you used it.

See Also:
java.lang.Runtime.exec()

Constructor Summary
RuntimeExec()
           
 
Method Summary
static int exec(java.lang.String[] cmd, java.lang.String[] env, java.io.File dir, java.io.OutputStream out, java.io.OutputStream err)
          Execute a native shell command.
static int exec(java.lang.String cmd, java.lang.String[] env, java.io.File dir, java.io.OutputStream out, java.io.OutputStream err)
          Execute a native shell command.
static void main(java.lang.String[] args)
          Test driver.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RuntimeExec

public RuntimeExec()
Method Detail

exec

public static int exec(java.lang.String cmd,
                       java.lang.String[] env,
                       java.io.File dir,
                       java.io.OutputStream out,
                       java.io.OutputStream err)
                throws java.io.IOException
Execute a native shell command. The command is executed in a separate process using the native command shell. This method waits for the process to terminate and then returns the command's exit status.

Parameters:
cmd - Command line. The first word in the string is the name of the program to execute. Command line arguments containing spaces or tabs should be enclosed within quotes so that the command shell can handle them properly.
env - Environment variables. This is an array of strings of the form "name=value", where each name is the name of an environment variable and value is its value. If the array is null, the shell command inherits the environment from the calling program.
dir - Current working directory in which to execute the shell command. If this is null, the command executes within the current working directory of the calling program.
out - The standard output stream that the shell command writes to. This can be null, in which case any output the shell command writes is discarded.
err - The standard error output stream that the shell command writes to. This can be null, in which case any error output the shell command writes is discarded.
Returns:
The exit status of the shell command, which is typically a small integer value. Zero generally indicates success.
Throws:
java.io.IOException
Since:
1.2, 2007-04-21

exec

public static int exec(java.lang.String[] cmd,
                       java.lang.String[] env,
                       java.io.File dir,
                       java.io.OutputStream out,
                       java.io.OutputStream err)
                throws java.io.IOException
Execute a native shell command. The command is executed in a separate process using the native command shell. This method waits for the process to terminate and then returns the command's exit status.

Parameters:
cmd - Array of command line parameters. The first element (cmd[0]) is the name of the program to execute. Command line arguments containing spaces or tabs are enclosed within quotes (") so that the command shell can handle them properly.
env - Environment variables. This is an array of strings of the form "name=value", where each name is the name of an environment variable and value is its value. If the array is null, the shell command inherits the environment from the calling program.
dir - Current working directory in which to execute the shell command. If this is null, the command executes within the current working directory of the calling program.
out - The standard output stream that the shell command writes to. This can be null, in which case any output the shell command writes is discarded.
err - The standard error output stream that the shell command writes to. This can be null, in which case any error output the shell command writes is discarded.
Returns:
The exit status of the shell command, which is typically a small integer value. Zero generally indicates success.
Throws:
java.io.IOException
Since:
1.2, 2007-04-21

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception
Test driver. Execute a command using the native shell command program.

Parameters:
args - Command line args, specifying a shell command to execute.
Throws:
java.lang.Exception
Since:
1.1, 2007-04-19