randoop.sequence

Class ExecutableSequence

java.lang.Object

randoop.sequence.ExecutableSequence

public class ExecutableSequence
extends java.lang.Object

An ExecutableSequence wraps a Sequence with functionality for executing the sequence, via methods execute(ExecutionVisitor, TestCheckGenerator) and execute(ExecutionVisitor, TestCheckGenerator, boolean). It also lets the client add Checks that check expected behaviors of the execution.

An ExecutableSequence augments a sequence with three additional pieces of data:

• Execution results. An ExecutableSequence can be executed, and the results of the execution (meaning the objects created during execution, and any exceptions thrown) are made available to clients or execution visitors to inspect.
• Checks. A check is an object representing an expected runtime behavior of the sequence. Clients can add checks to specific indices of the sequence. For example, a client might add a NotNull check to the ith index of a sequence to signify that the value returned by the statement at index i should not be null.
• Check evaluation results. Corresponding to every check is a boolean value that represents whether the check passed or failed during the last execution of the sequence.

An ExecutableSequence only directly manages the execution results. Other data, including checks and check evaluation results, are added or removed by the client of the ExecutableSequence. One way of doing this is by implementing an ExecutionVisitor and passing it as an argument to the execute method.

Field Summary

Fields

Modifier and Type	Field and Description
private @MonotonicNonNull TestChecks<?>	checks The checks for the last statement in this sequence.
java.util.List<Sequence>	componentSequences The subsequences that were concatenated to create this sequence.
long	exectime How long it took to execute this sequence in nanoseconds.
private Execution	executionResults Contains the runtime objects created and exceptions thrown (if any) during execution of this sequence.
long	gentimeNanos How long it took to generate this sequence in nanoseconds, excluding execution time.
private boolean	hasNullInput Flag to record whether execution of sequence has a null input.
private static java.io.ByteArrayOutputStream	output_buffer Captures output from the executed sequence.
private static java.io.PrintStream	output_buffer_stream Used to populate output_buffer.
Sequence	sequence The underlying sequence.
private IdentityMultiMap<java.lang.Object,Variable>	variableMap Maps a value to the set of variables that hold it.

Constructor Summary

Constructors

Constructor and Description
ExecutableSequence(Sequence sequence) Create an executable sequence that executes the given sequence.

Method Summary

Modifier and Type	Method and Description
void	addCoveredClass(java.lang.Class<?> c) Adds a covered class to the most recent execution results of this sequence.
private void	addReferenceValue(Variable variable, java.lang.Object value, java.util.Set<ReferenceValue> refValues) If the variable has a non-String reference type, add its value to the set and also add a mapping to variableMap.
boolean	coversClass(java.lang.Class<?> c) Indicates whether the given class is covered by the most recent execution of this sequence.
boolean	equals(@Nullable java.lang.Object obj)
void	execute(ExecutionVisitor visitor, TestCheckGenerator gen) Executes sequence, stopping on exceptions.
private void	execute(ExecutionVisitor visitor, TestCheckGenerator gen, boolean ignoreException) Execute this sequence, invoking the given visitor as the execution unfolds.
private static void	executeStatement(Sequence s, java.util.List<ExecutionOutcome> outcome, int index, java.lang.Object[] inputVariables)
java.util.List<ReferenceValue>	getAllValues() Returns all values computed in the sequence.
TestChecks<?>	getChecks() Return the set of test checks for the most recent execution.
private int	getExceptionIndex(java.lang.Class<?> exceptionClass) Returns the index in the sequence at which an exception of the given class (or a class compatible with it) was thrown.
java.util.List<ReferenceValue>	getLastStatementValues() Returns the list of (reference type) values created and used by the last statement of this sequence.
int	getNonExecutedIndex() Returns the index i for a non-executed statement, or -1 if there is no such index.
int	getNonNormalExecutionIndex()
TypedOperation	getOperation() Return the operation from which this sequence was generated -- the operation of the last statement of this sequence.
ExecutionOutcome	getResult(int index) This method is typically used by ExecutionVisitors.
private java.lang.Object[]	getRuntimeInputs(java.util.List<ExecutionOutcome> outcome, java.util.List<Variable> inputs)
java.lang.Object[]	getRuntimeInputs(java.util.List<Variable> inputs)
static java.lang.Object[]	getRuntimeValuesForVars(java.util.List<Variable> vars, Execution execution) Returns the values for the given variables in the Execution object.
private static java.lang.Object[]	getRuntimeValuesForVars(java.util.List<Variable> vars, java.util.List<ExecutionOutcome> execution)
private java.lang.Object	getValue(int index) The result of executing the index-th element of the sequence.
Variable	getVariable(java.lang.Object value) Returns some variable that has the given value in the outcome of executing this sequence.
@Nullable java.util.List<Variable>	getVariables(java.lang.Object value) Returns the set of variables that have the given value in the outcome of executing this sequence.
boolean	hasFailure() Indicate whether checks are failing or passing.
int	hashCode()
boolean	hasInvalidBehavior() Indicate whether there are any invalid checks.
boolean	hasNonExecutedStatements() Returns whether the sequence contains a non-executed statement.
boolean	hasNullInput() Indicates whether the executed sequence has any null input values.
boolean	isNormalExecution()
private boolean	isNormalExecution(int i) This method is typically used by ExecutionVisitors.
private void	reset() Reset this object to its initial state.
int	size() Return the number of statements in this sequence.
java.lang.String	statementToCodeString(int i) Return the code representation of the i'th statement.
boolean	throwsException(java.lang.Class<?> exceptionClass) Return true if an exception of the given class (or a class compatible with it) was thrown during this sequence's execution.
private java.util.List<java.lang.String>	toCodeLines() Return this sequence as code.
java.lang.String	toCodeString() Return this sequence as code.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

sequence

public Sequence sequence

The underlying sequence.

checks

private @MonotonicNonNull TestChecks<?> checks

The checks for the last statement in this sequence.

executionResults

private transient Execution executionResults

Contains the runtime objects created and exceptions thrown (if any) during execution of this sequence. Invariant: sequence.size() == executionResults.size(). Transient because it can contain arbitrary objects that may not be serializable.

gentimeNanos

public long gentimeNanos

How long it took to generate this sequence in nanoseconds, excluding execution time. Must be directly set by the generator that creates this object. No code in this class sets its value.

exectime

public long exectime

How long it took to execute this sequence in nanoseconds. Is -1 until the sequence completes execution.

hasNullInput

private boolean hasNullInput

Flag to record whether execution of sequence has a null input.

TODO: This is wonky, it really belongs to execution.

output_buffer

private static java.io.ByteArrayOutputStream output_buffer

Captures output from the executed sequence.

output_buffer_stream

private static java.io.PrintStream output_buffer_stream

Used to populate output_buffer.

variableMap

private IdentityMultiMap<java.lang.Object,Variable> variableMap

Maps a value to the set of variables that hold it.

componentSequences

public java.util.List<Sequence> componentSequences

The subsequences that were concatenated to create this sequence.

Constructor Detail

ExecutableSequence

public ExecutableSequence(Sequence sequence)

Create an executable sequence that executes the given sequence.

Parameters:

sequence - the underlying sequence for this executable sequence

Method Detail

reset

private void reset()

Reset this object to its initial state.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

toCodeLines

private java.util.List<java.lang.String> toCodeLines()

Return this sequence as code. Similar to Sequence.toCodeString() except includes the checks.

If for a given statement there is a check of type ExceptionCheck, that check's pre-statement code is printed immediately before the statement, and its post-statement code is printed immediately after the statement.

Returns:

the sequence as a string

toCodeString

public java.lang.String toCodeString()

Return this sequence as code. Similar to Sequence.toCodeString() except includes the checks.

If for a given statement there is a check of type ExceptionCheck, that check's pre-statement code is printed immediately before the statement, and its post-statement code is printed immediately after the statement.

Returns:

the sequence as a string

statementToCodeString

public java.lang.String statementToCodeString(int i)

Return the code representation of the i'th statement.

Parameters:

i - the statement index

Returns:

the string representation of the statement

execute

public void execute(ExecutionVisitor visitor,
                    TestCheckGenerator gen)

Executes sequence, stopping on exceptions.

Parameters:

visitor - the ExecutionVisitor that collects checks from results

gen - the check generator for tests

See Also:

execute(ExecutionVisitor, TestCheckGenerator, boolean)

execute

private void execute(ExecutionVisitor visitor,
                     TestCheckGenerator gen,
                     boolean ignoreException)

Execute this sequence, invoking the given visitor as the execution unfolds. For example, the visitor may decorate the sequence with Checks about the execution.

This method operates as follows:

• Clear execution results and call visitor.initialize(this).
• For each statement in the sequence:
  • call visitor.visitBefore(this, i)
  • execute the i-th statement, using reflection
  • call visitor.visitAfter(this, i)
• For the last statement, check its specifications (pre-, post-, and throws-conditions).

Execution stops if one of the following conditions holds:

• All statements in the sequences have been executed.
• A pre-condition for the final statement fails
• A statement's execution results in an exception and ignoreException==false.
• A null input value is implicitly passed to the statement (i.e., not via explicit declaration like x = null)
• After executing the i-th statement and calling the visitor's visitAfter method, a ContractViolation check is present at index i.

After invoking this method, the client can query the outcome of executing each statement via the method getResult(int).

Parameters:

visitor - the ExecutionVisitor

gen - the initial check generator, which this augments then uses

ignoreException - if true, ignore exceptions thrown before the last statement

Throws:

java.lang.Error - if execution of the sequence throws an exception and ignoreException==false

getRuntimeInputs

public java.lang.Object[] getRuntimeInputs(java.util.List<Variable> inputs)

getRuntimeInputs

private java.lang.Object[] getRuntimeInputs(java.util.List<ExecutionOutcome> outcome,
                                            java.util.List<Variable> inputs)

getRuntimeValuesForVars

public static java.lang.Object[] getRuntimeValuesForVars(java.util.List<Variable> vars,
                                                         Execution execution)

Returns the values for the given variables in the Execution object. The variables are Variable objects in the Sequence of this ExecutableSequence object.

Parameters:

vars - a list of Variable objects

execution - the object representing outcome of executing this sequence

Returns:

array of values corresponding to variables

getRuntimeValuesForVars

private static java.lang.Object[] getRuntimeValuesForVars(java.util.List<Variable> vars,
                                                          java.util.List<ExecutionOutcome> execution)

executeStatement

private static void executeStatement(Sequence s,
                                     java.util.List<ExecutionOutcome> outcome,
                                     int index,
                                     java.lang.Object[] inputVariables)

getResult

public ExecutionOutcome getResult(int index)

This method is typically used by ExecutionVisitors.

The result of executing the index-th element of the sequence.

Parameters:

index - the statement index

Returns:

the outcome of the statement at index

getChecks

public TestChecks<?> getChecks()

Return the set of test checks for the most recent execution.

Returns:

the TestChecks generated from the most recent execution

getValue

private java.lang.Object getValue(int index)

The result of executing the index-th element of the sequence.

Parameters:

index - which element to obtain

Returns:

the result of executing the index-th element of the sequence, if that element's execution completed normally

getLastStatementValues

public java.util.List<ReferenceValue> getLastStatementValues()

Returns the list of (reference type) values created and used by the last statement of this sequence. Null output values are not included.

Returns:

the list of values created and used by the last statement of this sequence

addReferenceValue

private void addReferenceValue(Variable variable,
                               java.lang.Object value,
                               java.util.Set<ReferenceValue> refValues)

If the variable has a non-String reference type, add its value to the set and also add a mapping to variableMap.

Parameters:

variable - the variable to use as a value in variableMap

value - the Java value to use as a key in variableMap

refValues - the set of all reference values; is side-effected by this method

getAllValues

public java.util.List<ReferenceValue> getAllValues()

Returns all values computed in the sequence.

Returns:

the list of values computed in the sequence

getVariables

public @Nullable java.util.List<Variable> getVariables(java.lang.Object value)

Returns the set of variables that have the given value in the outcome of executing this sequence.

Parameters:

value - the value

Returns:

the set of variables that have the given value, or null if none

getVariable

public Variable getVariable(java.lang.Object value)

Returns some variable that has the given value in the outcome of executing this sequence.

Parameters:

value - the value

Returns:

a variable that has the given value

isNormalExecution

private boolean isNormalExecution(int i)

This method is typically used by ExecutionVisitors.

Parameters:

i - the statement index to test for normal execution

Returns:

true if execution of the i-th statement terminated normally

getNonNormalExecutionIndex

public int getNonNormalExecutionIndex()

isNormalExecution

public boolean isNormalExecution()

getExceptionIndex

private int getExceptionIndex(java.lang.Class<?> exceptionClass)

Returns the index in the sequence at which an exception of the given class (or a class compatible with it) was thrown. If no such exception, returns -1.

Parameters:

exceptionClass - the exception thrown

Returns:

the index in the sequence at which an exception of the given class (or a class compatible with it) was thrown. If no such exception, returns -1

throwsException

public boolean throwsException(java.lang.Class<?> exceptionClass)

Return true if an exception of the given class (or a class compatible with it) was thrown during this sequence's execution.

Parameters:

exceptionClass - the exception class

Returns:

true if an exception compatible with the given class was thrown during this sequence's execution

hasNonExecutedStatements

public boolean hasNonExecutedStatements()

Returns whether the sequence contains a non-executed statement. That happens if some statement before the last one throws an exception.

Returns:

true if this sequence has non-executed statements, false otherwise

getNonExecutedIndex

public int getNonExecutedIndex()

Returns the index i for a non-executed statement, or -1 if there is no such index. Note that a statement is considered executed even if it throws an exception.

Returns:

the index of a non-executed statement in this sequence

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(@Nullable java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hasNullInput

public boolean hasNullInput()

Indicates whether the executed sequence has any null input values.

Returns:

true if there is a null input value in this sequence, false otherwise

hasFailure

public boolean hasFailure()

Indicate whether checks are failing or passing.

Returns:

true if checks are all failing, or false if all passing

hasInvalidBehavior

public boolean hasInvalidBehavior()

Indicate whether there are any invalid checks.

Returns:

true if the test checks have been set and are for invalid behavior, false otherwise

addCoveredClass

public void addCoveredClass(java.lang.Class<?> c)

Adds a covered class to the most recent execution results of this sequence.

Parameters:

c - the class covered by the execution of this sequence

coversClass

public boolean coversClass(java.lang.Class<?> c)

Indicates whether the given class is covered by the most recent execution of this sequence.

Parameters:

c - the class to be covered

Returns:

true if the class is covered by the sequence, false otherwise

getOperation

public TypedOperation getOperation()

Return the operation from which this sequence was generated -- the operation of the last statement of this sequence.

Returns:

the operation of the last statement of this sequence

size

public int size()

Return the number of statements in this sequence.

Returns:

the number of statements in this sequence