ExpectJ
1.0 User Documentation
Every documented bug becomes a
feature
- Introduction
ExpectJ is a Java implementation of the Unix expect utility. ExpectJ provides a Unix expect like support to write Java Programs that communicate with other programs and perform some operation on them.
If you are not familiar with working of the Unix expect utility, please refer to man page of expect. Usage of ExpectJ requires a proper understanding of the Unix expect utility.
For example using ExpectJ you can write a Java program that telnets to a host machine and deletes the contents of /tmp. This program when configured as a cron job will always keep the /tmp under the specified limit.
- API
Specification
Package Structure:
All ExpectJ classes are located in expectj package.
Classes:
Following classes will be used:
expectj.ExpectJ
ExpectJ is the entry point to API. ExpectJ acts as a single point factory container for spawning processes and performing other ExpectJ related functions.
Constructor:
ExpectJ(String sLogFile, long lDefaultTimeOut)
This constructor creates an ExpectJ object. This object can further be used to spawn different processes and communicate with them. sLogFile is location of the log file where ExpectJ write debug messages. lDefaultTimeOut is default timeout value for expect commands. A default value of -1 means indefinite timeout.
Methods:
spawn(String sCommand)
This method spawns a process sCommand in a different thread from the invoker thread and returns an object SpawnedProcess which can be use to further communicate with the process spawned by the spawn command. A single ExpectJ object can be used to spawn an many processes and possible, but a SpawnedProcess object represents only one process.
expectj.SpawnedProcess
This class represents a SpawnedProcess and all communication with the process can be done using this object. ExpectJ.spawn returns an instance of SpawnedProcess.
Methods:
expect( String pattern, long lTimeOut) throws ExpectJException
This method functions exactly like the Unix expect command. It waits untill a string is read from the standard output stream of the spawned process that matches the string pattern. SpawnedProcess does a cases insensitive substring match for pattern against the output of the spawned process. lTimeOut is the timeout in seconds that the expect command should wait for the pattern to match. This function returns when a match is found or after lTimOut seconds. You can use the SpawnedProcess.isLastExpectTimeOut() to identify the return path of the method. A timeout of -1 will make the expect method wait indefinitely untill the supplied pattern matches with the Standard Out. This method throws an ExpectJException when some error occurrs.
expect( String pattern) throws JExpectException
This method functions exactly like expect described above, but uses the default timeout specified in the ExpectJ constructor.
expectErr( String pattern, long lTimeOut) throws JExpectException
This method functions exactly like the corresponding expect function except for it tries to match the pattern with the output of standard error stream of the spawned process.
expectErr(String pattern) throws JExpectException
This method functions exactly like the corresponding expect function except for it tries to match the pattern with the output of standard error stream of the spawned process.
isLastExpectTimeOut()
This method returns true if the last expect() or expectErr() method returned because of a time out rather then a match against the output of the process. This method is common to both expect and expectErr.
send(String line) throws JExpectException
This method writes the string line to the standard input of the spawned process. It throws a JExpectException if the spawned process has already exited.
isClosed()
This method returns true if the process has already exited. This method shoud be use use to check the process status before invoking send()
getExitValue()
This method returns the exit code of the process if the process has already exited.
stop()
This method kills the process represented by SpawnedProcess object.
interact()
This method functions like exactly the Unix interact command. It allows the user to interact with the spawned process.
Known Issues: User input is echoed twice on the screen, need to fix this ;)
- Example
Consider a simple example of a writing an application that telnets to a host machine and deletes a particular file '/tmp/my.log' on the host machine. The code snippet would look something like this.
JExpect exp = new JExpect("/tmp/expectJ.log", 20);
String command = "telnet myhost";
SpawnedProcess sp = exp.spawn(command);
sp.expect("login");
sp.send("myhost\n");
System.out.println("Expect Status " + sp.isLastExpectTimeOut());
if (sp.isLastExpectTimeOut()) {
System.err.println("Did not match");
System.exit(1);
}
sp.expect("Password");
sp.send("mypass\n");
sp.send("rm /tmp/my.log\n");
sp.interact();
System.out.println("Started Interacting");
// Play with telnet session here, you can use send("exit\n") if you dont want to interact.
Thread.sleep(10000000000);
System.out.println("Thread Woken Up, killing the telnet session");
sp.stop();
- Known Issues
1. If spawning of process does not work on windows use "cmd /c" to spawn the process. For example to spawn the label command using ExpectJ use "cmd /c label"
2. Make sure you use the line feed characters wherever necessary in send methods.
3. Telnet does not seem to work on my windows box, if you can make it work please let me know.
4. In interact mode, the input from the user is echoed twice on the screen to fix this I need to swich off the echo on Standard Input, if anybody knows how to do it in java please let me know.
