org.das2.util

Class Expect

java.lang.Object

org.das2.util.Expect

public class Expect
extends java.lang.Object

Provides similar functions as the Unix Expect tool.
There are two ways to create an Expect object: a constructor that takes an InputStream handle and OutputStream handle; or spawning a process by providing a command String.

The API is loosely based on Perl Expect library:
http://search.cpan.org/~rgiersig/Expect-1.15/Expect.pod
If you are not familiar with the Tcl version of Expect, take a look at:
http://oreilly.com/catalog/expect/chapter/ch03.html

Expect uses a thread to convert InputStream to a SelectableChannel; other than this, no multi-threading is used.
A call to expect() will block for at most timeout seconds. Expect is not designed to be thread-safe, in other words, do not call methods of the same Expect object in different threads.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Expect.EOFException
static class	Expect.TimeoutException

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	before String before the last match(if there was a match), updated after each expect() call
boolean	isSuccess Whether the last match was successful, updated after each expect() call
java.lang.String	match String representing the last match(if there was a match), updated after each expect() call
static int	RETV_EOF
static int	RETV_IOEXCEPTION
static int	RETV_TIMEOUT

Constructor Summary

Constructors

Constructor and Description
Expect(java.io.InputStream input, java.io.OutputStream output)

Method Summary

Modifier and Type	Method and Description
static java.lang.String	bytesToPrintableString(byte[] bytes) Static method used for convert byte array to string, each byte is converted to an ASCII character, if the byte represents a control character, it is replaced by a printable caret notation http://en.wikipedia.org/wiki/ASCII , or an escape code if possible.
static java.lang.String	byteToPrintableString(byte b)
void	close() The OutputStream passed to Expect constructor is closed; the InputStream is not closed (there is no need to close the InputStream). It is suggested that this method be called after the InputStream has come to EOF.
int	expect(int timeout, java.util.List<java.util.regex.Pattern> list) Expect will wait for the input handle to produce one of the patterns in the list.
int	expect(int timeout, java.lang.Object... patterns) Convenience method, internally it constructs a List<Pattern> using the object array, and call expect(int, List) using the List.
int	expect(java.lang.Object... patterns) Convenience method, same as calling expect(default_timeout, patterns)
int	expectEOF() Convenience method, same as calling expectEOF(default_timeout)
int	expectEOF(int timeout) Convenience method, internally it calls expect(timeout, new ArrayList<Pattern>()).
int	expectEOFOrThrow() Convenience method, same as calling expectEOF(default_timeout)
int	expectEOFOrThrow(int timeout) Throws checked exceptions when expectEOF was not successful.
int	expectOrThrow(int timeout, java.lang.Object... patterns) This method calls expect(timeout, patterns), and throws checked exceptions when expect was not successful.
int	expectOrThrow(java.lang.Object... patterns) Convenience method, same as calling expectOrThrow(default_timeout, patterns)
static void	forwardInputStreamTo(java.io.PrintStream duplicatedTo) While performing expect operations on the InputStream provided, duplicate the contents obtained from InputStream to a PrintStream (you can use System.err or System.out).
int	getDefault_timeout()
java.lang.Process	getProcess()
boolean	isNotransfer()
boolean	isRestart_timeout_upon_receive()
void	printDebugInfo() print internal debug information to stderr.
void	send(byte[] toWrite)
void	send(java.lang.String str)
void	setDefault_timeout(int default_timeout)
void	setNotransfer(boolean notransfer)
void	setRestart_timeout_upon_receive(boolean restart_timeout_upon_receive)
static Expect	spawn(java.lang.String command) Creates an Expect object by spawning a command. To Linux users, perhaps you need to use "bash -i" if you want to spawn Bash. Note: error stream of the process is redirected to output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

before

public java.lang.String before

String before the last match(if there was a match), updated after each expect() call

match

public java.lang.String match

String representing the last match(if there was a match), updated after each expect() call

isSuccess

public boolean isSuccess

Whether the last match was successful, updated after each expect() call

RETV_TIMEOUT

public static final int RETV_TIMEOUT

See Also:

Constant Field Values

RETV_EOF

public static final int RETV_EOF

See Also:

Constant Field Values

RETV_IOEXCEPTION

public static final int RETV_IOEXCEPTION

See Also:

Constant Field Values

Constructor Detail

Expect

public Expect(java.io.InputStream input,
              java.io.OutputStream output)

Method Detail

getProcess

public java.lang.Process getProcess()

Returns:

the spawned process, if this Expect object is created by spawning a process

spawn

public static Expect spawn(java.lang.String command)

Creates an Expect object by spawning a command.
To Linux users, perhaps you need to use "bash -i" if you want to spawn Bash.
Note: error stream of the process is redirected to output stream.

Parameters:

command -

Returns:

Expect object created using the input and output handles from the spawned process

send

public void send(java.lang.String str)

Parameters:

str - Convenience method to send a string to output handle

send

public void send(byte[] toWrite)

Parameters:

toWrite - Write a byte array to the output handle, notice flush()

expect

public int expect(java.lang.Object... patterns)

Convenience method, same as calling expect(default_timeout, patterns)

Parameters:

patterns -

Returns:

expect

public int expect(int timeout,
                  java.lang.Object... patterns)

Convenience method, internally it constructs a List<Pattern> using the object array, and call expect(int, List) using the List. The Strings in the object array will be treated as literals; meanwhile Patterns will be directly added to the List. If the array contains other objects, they will be converted by Object.toString() and then used as literal strings.

Parameters:

timeout - timeout in seconds

patterns - array of String regex, Pattern, or Object where toString() is called.

Returns:

expect

public int expect(int timeout,
                  java.util.List<java.util.regex.Pattern> list)

Expect will wait for the input handle to produce one of the patterns in the list. If a match is found, this method returns immediately; otherwise, the methods waits for up to timeout seconds, then returns. If timeout is less than or equal to 0 Expect will check one time to see if the internal buffer contains the pattern.

Parameters:

timeout - timeout in seconds

list - List of Java Patterns used for match the internal buffer obtained by reading the InputStream

Returns:

position of the matched pattern within the list (starting from 0); or a negative number if there is an IOException, EOF or timeout

printDebugInfo

public void printDebugInfo()

print internal debug information to stderr.

expectEOF

public int expectEOF(int timeout)

Convenience method, internally it calls expect(timeout, new ArrayList<Pattern>()). Given an empty list, expect(int, List) will not perform any regex matching, therefore the only conditions for it to return is EOF or timeout (or IOException). If EOF is detected, isSuccess and before are properly set.

Parameters:

timeout -

Returns:

same as return value of expect(int, List)

expectEOF

public int expectEOF()

Convenience method, same as calling expectEOF(default_timeout)

Returns:

same as return value of expect(int, List)

expectEOFOrThrow

public int expectEOFOrThrow(int timeout)
                     throws Expect.TimeoutException,
                            java.io.IOException

Throws checked exceptions when expectEOF was not successful.

Parameters:

timeout - timeout in seconds

Returns:

same as return value of expect(int, List)

Throws:

external.Expect.TimeoutException

java.io.IOException

Expect.TimeoutException

expectEOFOrThrow

public int expectEOFOrThrow()
                     throws Expect.TimeoutException,
                            java.io.IOException

Convenience method, same as calling expectEOF(default_timeout)

Returns:

same as return value of expect(int, List)

Throws:

java.io.IOException

Expect.TimeoutException

expectOrThrow

public int expectOrThrow(int timeout,
                         java.lang.Object... patterns)
                  throws Expect.TimeoutException,
                         Expect.EOFException,
                         java.io.IOException

This method calls expect(timeout, patterns), and throws checked exceptions when expect was not successful. Useful when you want to simplify error handling: for example, when you send a series of commands to an SSH server, you expect a prompt after each send, however the server may die or the prompt may take forever to appear, you would want to skip the following commands if those occurred. In such a case this method will be handy.

Parameters:

timeout -

patterns -

Returns:

same as expect(timeout, patterns)

Throws:

Expect.TimeoutException - when expect times out

Expect.EOFException - when EOF is encountered

java.io.IOException - when there is a problem reading from the InputStream

expectOrThrow

public int expectOrThrow(java.lang.Object... patterns)
                  throws Expect.TimeoutException,
                         Expect.EOFException,
                         java.io.IOException

Convenience method, same as calling expectOrThrow(default_timeout, patterns)

Parameters:

patterns -

Returns:

same as expect(timeout, patterns)

Throws:

external.Expect.TimeoutException

external.Expect.EOFException

java.io.IOException

Expect.TimeoutException

Expect.EOFException

close

public void close()

The OutputStream passed to Expect constructor is closed; the InputStream is not closed (there is no need to close the InputStream).
It is suggested that this method be called after the InputStream has come to EOF. For example, when you connect through SSH, send an "exit" command first, and then call this method.

When this method is called, the thread which write to the sink of the pipe will end.

getDefault_timeout

public int getDefault_timeout()

setDefault_timeout

public void setDefault_timeout(int default_timeout)

isRestart_timeout_upon_receive

public boolean isRestart_timeout_upon_receive()

setRestart_timeout_upon_receive

public void setRestart_timeout_upon_receive(boolean restart_timeout_upon_receive)

setNotransfer

public void setNotransfer(boolean notransfer)

isNotransfer

public boolean isNotransfer()

bytesToPrintableString

public static java.lang.String bytesToPrintableString(byte[] bytes)

Static method used for convert byte array to string, each byte is converted to an ASCII character, if the byte represents a control character, it is replaced by a printable caret notation http://en.wikipedia.org/wiki/ASCII , or an escape code if possible.

Parameters:

bytes - bytes to be printed

Returns:

String representation of the byte array

byteToPrintableString

public static java.lang.String byteToPrintableString(byte b)

forwardInputStreamTo

public static void forwardInputStreamTo(java.io.PrintStream duplicatedTo)

While performing expect operations on the InputStream provided, duplicate the contents obtained from InputStream to a PrintStream (you can use System.err or System.out). DO NOT call this function while there are live Expect objects as this may cause the piping thread to end due to unsynchronized code; if you need this feature, add the following to both inputStreamToSelectableChannel(InputStream) and forwardInputStreamTo(PrintStream):

 
 	synchronized(Expect.duplicatedTo) {...}
 
 

Parameters:

duplicatedTo - call with null if you want to turn off