Executing external command from within JVM often causes problems- be it in terms of the code to write and manage or in the ease of implementation. I had similar requirement in my Major project for my Under Graduate Degree, where in I had to launch a C program from the Java code. I ran into different issues like- the Main thread getting blocked, the GUI freezing, or reading the output streams and so on. Finally I had to give up the idea and stick with launching the external command externally 😛 Had I found the Exec library from Apache Commons then, my work would have been lot easier. Anyways better late then never. I will quickly go through how one can use Exec library to launch external programs from JVM- Its a wrapper over Java’s ProcessBuilder, Runtime.getRuntime().exe(). The Javadoc shows lots of classes- but important one among them- which the end user would mostly be using are:
- DefaultExecutor (A default implementation for Executor Interface)
- DefaultExecuteResultHandler (A default implementation for ExecuteResultHandler interface)
- ExecuteWatchdog
- PumpStreamHandler
- CommandLine
- EnvironmentUtils
There are other CommandLauncher classes which are internally called by when one uses DefaultExecutor, though the methods of these classes are available for one to use them directly.
Using Exec helps us to:
- Set environment variables- Current Java implementation provides- System.getEnv() or System.getEnv(String) but no System.setEnv(). Yet the exec() method of Runtime class is overloaded to accept the Environment variables. This can at time lead to confusion. Exec provides an EnvironmentUtils class which takes care of environment variable related tasks.
- Easily set the Stream handlers- There’s a class PumpStreamHandler which can take- Output Stream, Input Stream and error stream. It captures the data in different streams via creating different Threads for each stream. So one need not worry about creating threads for each stream.
- Build the Command using CommandLine class.
- Execute the command- Synchronously or Asynchronously.
- Associate watchdogs for each command- So that these commands dont take too much of time.
- Destroying the process when the JVM exits.
Lets have a look at the implementation of the library.
Building the Command-Uses CommandLine class.
//Just the Executable, No arguments
CommandLine command = new CommandLine("ls");
command.addArgument(String) //Adding a String argument
command.addArgument("${arg1}"); //Expands the arg1 value from the Map
//map used to expand the arguments like above
command.setSubstitutionMap(Map);
command.addArguments(String[]) //Adding all the arguments at one go
Now we need to set the Stream handler- PumpStreamHandler
//Takes System.out for dumping the output and System.err for Error PumpStreamHandler streamHandler = new PumpStreamHander(); //Create a new FileOutputStream instance //Sends the output and error to the file streamHandler = new PumpStreamHandler(FileOutputStream);
In this way PumpStreamHandler provides overloaded Constructors. Also note that internally it creates different Threads for each Stream viz Output, Input, Error.
Now we should be executing the command- DefaultExecutor– There are lot of variations in this. Lets start with the Simple-
DefaultExecutor executor = new DefaultExecutor(); executor.setStreamHandler(PumpStreamHandler); //Sets the stream handler executor.execute(CommandLine);//Executes the command
Lets apply the above to create a simple “ls” on Linux systems.
CommandLine command = new CommandLine("ls");
PumpStreamHandler streamHandler = new PumpStreamHandler();
DefaultExecutor executor = new DefaultExecutor();
executor.setStreamHandler(streamHandler);
executor.execute(command);
Now lets execute the same Asynchronously- uses DefaultExeuteResultHandler class. I would be using the sleep command as that will clearly show the difference
CommandLine command = new CommandLine("sleep");
command.addArgument("10");//Number of seconds to sleep
System.out.println("Before Sleep");
DefaultExecuteResultHandler resultHandler
= new DefaultExecuteResultHandler();
DefaultExecutor executor = new DefaultExecutor();
PumpStreamHandler streamHandler = new PumpStreamHandler();
executor.setStreamHandler(streamHandler);
executor.execute(command,resultHandler);
System.out.println("After Sleep");
//Use of resultHandler makes this a Asynch process
You can see that there’s now time interval between the two print statements. If we add this line after Line 09-
//Wait for the command to finish execution. resultHandler.waitFor(); //Obtain the exit value of the command. int exitValue = resultHandler.getExitValue();
Then there’s a delay- which means the main thread waits for the sub process to complete before proceeding- waitFor() internally uses Thread.sleep(time). Also the exitValue is captured which can be used for:
//testing if the exitValue indicates failure
if(executor.isFailure(exitValue){
System.out.println("Command execution failed");
}else{
System.out.println("Command execution Successful");
}
ifFailure() checks if the exitValue obtained after executing the command denotes a Success (exitValue=0) or a Failure (any other exitValue). One can also set exitValue for the executor using setExitValue(int) or setExitValues(int[]) in that case the exitValue for success will not be “0” but the value specified. One can use waitFor() if the command has to be executed before the program continues execution. Otherwise in cases where the user wants to execute the command and store the result in a File waitFor() will not be required.
Sometimes the command might continue executing for a long time and we need to keep a check to see that it doesnt exceed the time. In those cases ExecuteWatchdog class can be used. Whenever the process terminates due to the timeout specified in WatchDog, the exit value returned will be for that of a failure.
ExecuteWatchdog watchDog = new ExecuteWatchdog(timeout); exeuctor.setWatchDog(watchDog);//setting the watchdog for the executor //The time out can also be ExecuteWatchdog.INFINITE_TIMEOUT
Summarizing:
- DefaultExecutor– Class for launching/executing the commands. Can set TIME_OUT, StreamHandler, ResultHandler, Working Directory for the command.
- DefaultExecuteResultHandler– Monitors the process when its launched Asynchronously. Can be used to get the Exception, Exit_Value for the process.
- PumpStreamHandler– Manager the Output,Error,Input Stream of the Process- Each of them in a separate thread.
- ExecuteWatchdog– Used for setting the timeout for the command.
- EnvironmentUtils– Utility class to work with the Environment variables
- CommandLine– For setting up the executable, and its arguments. Can take the argument values from a Map.
Note: Most of the classes are default implementations of their interfaces
Let me give a sample code which uses all of the above:
//Command to be executed
CommandLine command = new CommandLine("ls");
//Adding its arguments
command.addArguments(new String[]{"-l","-t","-R"});
//Infinite timeout
ExecuteWatchdog watchDog = new ExecuteWatchdog(ExecuteWatchdog.INFINITE_TIMEOUT);
//Result Handler for executing the process in a Asynch way
DefaultExecuteResultHandler resultHandler = new DefaultExecuteResultHandler();
//Using Std out for the output/error stream
PumpStreamHandler streamHandler = new PumpStreamHandler();
//This is used to end the process when the JVM exits
ShutdownHookProcessDestroyer processDestroyer = new ShutdownHookProcessDestroyer();
//Our main command executor
DefaultExecutor executor = new DefaultExecutor();
//Setting the properties
executor.setStreamHandler(streamHandler);
executor.setWatchdog(watchDog);
//Setting the working directory
//Use of recursion along with the ls makes this a long running process
executor.setWorkingDirectory(new File("/home"));
executor.setProcessDestroyer(processDestroyer);
//Executing the command
executor.execute(command,resultHandler);
//The below section depends on your need
//Anything after this will be executed only when the command completes the execution
resultHandler.waitFor();
int exitValue = resultHandler.getExitValue();
System.out.println(exitValue);
if(executor.isFailure(exitValue)){
System.out.println("Execution failed");
}else{
System.out.println("Execution Successful");
}
Note: The Exec library has to be in your classpath- Either add it in CLASSPATH env variable or use java -cp
Please drop in any corrections, additional information as comments. I will update the post accordingly