net.sf.expectit

Class ExpectBuilder

java.lang.Object

net.sf.expectit.ExpectBuilder

public class ExpectBuilder
extends Object

A class used to construct Expect instances.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BUFFER_SIZE The default buffer size in bytes.
static int	DEFAULT_TIMEOUT_MS The default timeout value of 30000 milliseconds.

Constructor Summary

Constructors

Constructor and Description
ExpectBuilder() Default constructor.

Method Summary

Modifier and Type	Method and Description
Expect	build() Creates a ready to use Expect instance.
ExpectBuilder	withAutoFlushEcho(boolean autoFlushEcho) Enables automatic flushing of the echo input and output after each match operation if the given echo object(s) implements Flushable interface.
ExpectBuilder	withBufferSize(int bufferSize) Sets the size of the input buffer in bytes.
ExpectBuilder	withCharset(Charset charset) Sets the character encoding used to covert bytes when working with byte streams.
ExpectBuilder	withCombineInputs(boolean combineInputs) Combines input streaming data into one input.
ExpectBuilder	withEchoInput(Appendable firstInput, Appendable... otherInputs) Enables printing of all the received data.
ExpectBuilder	withEchoOutput(Appendable echoOutput) Enables printing of all the sent data.
ExpectBuilder	withEchoOutput(EchoOutput echoOutput) Deprecated.
ExpectBuilder	withErrorOnTimeout(boolean errorOnTimeout) Deprecated. This method is deprecated and will be removed. Use withExceptionOnFailure() instead.
ExpectBuilder	withExceptionOnFailure() Enables throwing an ExpectIOException if an expect operation was not successful.
ExpectBuilder	withExecutor(ExecutorService executor) Set the executor used to create internal thread.
ExpectBuilder	withInfiniteTimeout() Sets the default timeout to infinity.
ExpectBuilder	withInputFilters(Filter filter, Filter... moreFilters) Sets a filter for the input.
ExpectBuilder	withInputs(InputStream... inputs) Sets the input streams for expect operations.
ExpectBuilder	withLineSeparator(String lineSeparator) Sets the line separator used by the Expect.sendLine() method.
ExpectBuilder	withOutput(OutputStream output) Sets the output stream where Expect sends command to.
ExpectBuilder	withTimeout(long duration, TimeUnit unit) Sets the default timeout in the given unit for expect operations.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_TIMEOUT_MS

public static final int DEFAULT_TIMEOUT_MS

The default timeout value of 30000 milliseconds.

See Also:

Constant Field Values

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The default buffer size in bytes.

See Also:

Constant Field Values

Constructor Detail

ExpectBuilder

public ExpectBuilder()

Default constructor.

Method Detail

withOutput

public final ExpectBuilder withOutput(OutputStream output)

Sets the output stream where Expect sends command to. Optional, if not set then all the send method are expected to throw NullPointerException.

Parameters:

output - the output stream

Returns:

this

withInputs

public final ExpectBuilder withInputs(InputStream... inputs)

Sets the input streams for expect operations. Required.

Parameters:

inputs - the input stream

Returns:

this

withTimeout

public final ExpectBuilder withTimeout(long duration,
                                       TimeUnit unit)

Sets the default timeout in the given unit for expect operations. Optional, the default value is 30 seconds.

Parameters:

duration - the timeout value

unit - the time unit

Returns:

this

Throws:

IllegalArgumentException - if the timeout <= 0

withInfiniteTimeout

public final ExpectBuilder withInfiniteTimeout()

Sets the default timeout to infinity.

Returns:

this

withEchoOutput

@Deprecated
public final ExpectBuilder withEchoOutput(EchoOutput echoOutput)

Deprecated.

Sets the echo output to print all the sent and received data. Useful for debugging to monitor I/O activity. Optional, by default is unset.

Parameters:

echoOutput - an instance of echo output. Refer to .EchoAdapters for adapter static methods for common use cases.

Returns:

this

withEchoOutput

public final ExpectBuilder withEchoOutput(Appendable echoOutput)

Enables printing of all the sent data. Useful for debugging to monitor I/O activity. Optional, by default is unset.

Parameters:

echoOutput - where to echo the sent data.

Returns:

this

withEchoInput

public final ExpectBuilder withEchoInput(Appendable firstInput,
                                         Appendable... otherInputs)

Enables printing of all the received data. Useful for debugging to monitor I/O activity. Optional, by default is unset.

If the only firstInput is specified then the data received from all the inputs is echoed to it.

The build method throws an IllegalArgumentException if the number of the otherInputs parameters does not correspond to the number of the input streams. That is, if otherInputs is specified, the number of them must be equal to the number of inputs minus 1.

The byte data received from the input streams is converted to strings using the builder's charset. See withCharset(java.nio.charset.Charset) for more information.

Parameters:

firstInput - where to echo the received data for the first input. If otherInputs are empty, then all the data will be echoed to it.

otherInputs - where to echo the received data for other inputs.

Returns:

this

withCharset

public final ExpectBuilder withCharset(Charset charset)

Sets the character encoding used to covert bytes when working with byte streams. Optional, the default is Charset.defaultCharset.

Parameters:

charset - the charset

Returns:

this

withInputFilters

public final ExpectBuilder withInputFilters(Filter filter,
                                            Filter... moreFilters)

Sets a filter for the input. Optional, by default no filter is applied.

Filters can be used to modify the input before performing expect operations. For example, to remove non-printable characters. Filters can be switched on and off while working with the expect instance.

Parameters:

filter - the filter

moreFilters - more filter to apply. if specified then all the filters are combined using the Filters.chain(Filter...) method.s

Returns:

this

withErrorOnTimeout

@Deprecated
public final ExpectBuilder withErrorOnTimeout(boolean errorOnTimeout)

Deprecated. This method is deprecated and will be removed. Use withExceptionOnFailure() instead.

Enables throwing an AssertionError if any expect operation times out. Optional, disabled by default.

Parameters:

errorOnTimeout - the error flag

Returns:

this

withExceptionOnFailure

public final ExpectBuilder withExceptionOnFailure()

Enables throwing an ExpectIOException if an expect operation was not successful. Optional, disabled by default.

Returns:

this

withLineSeparator

public final ExpectBuilder withLineSeparator(String lineSeparator)

Sets the line separator used by the Expect.sendLine() method. Optional, default is '\n'.

The default line separator was intentionally made non-system specific to avoid issues like when the tool is running on Windows and sending CRLF to a Unix system which threats them as two new lines.

Parameters:

lineSeparator - the line separator

Returns:

this

withBufferSize

public final ExpectBuilder withBufferSize(int bufferSize)

Sets the size of the input buffer in bytes. Optional, default is 1024.

Parameters:

bufferSize - the buffer size

Returns:

this

Throws:

IllegalArgumentException - if bufferSize is <= 0

withAutoFlushEcho

public final ExpectBuilder withAutoFlushEcho(boolean autoFlushEcho)

Enables automatic flushing of the echo input and output after each match operation if the given echo object(s) implements Flushable interface.

Parameters:

autoFlushEcho - the auto flushing flag.

Returns:

this

withCombineInputs

public final ExpectBuilder withCombineInputs(boolean combineInputs)

Combines input streaming data into one input. Data from all the inputs can be expected in the first input. Useful if you want to perform match operation on data that is coming from two input streams.

Parameters:

combineInputs - the combine inputs flag.

Returns:

this.

withExecutor

public final ExpectBuilder withExecutor(ExecutorService executor)

Set the executor used to create internal thread. If not specified, an executor with the number of threads corresponding to the number of inputs will be created internally.
IMPORTANT! Make sure that the given executor has the number of threads greater or equal than the number of input streams.
If the executor is passed form outside it won't be shutdown when the Expect instance is closed.

Parameters:

executor - the executor service to use.

Returns:

this.

build

public final Expect build()
                   throws IOException

Creates a ready to use Expect instance.

This method creates an instance and starts background threads that receive input data through NIO pipes. The created instance must be disposed after use by calling the .Expect#close() method,

The instance is not thread safe and intended to be used in a single thread.

Returns:

the instance

Throws:

IOException - if I/O error occurs

IllegalStateException - if the inputs are incorrect