org.requirementsascode

Class ModelRunner

java.lang.Object

org.requirementsascode.ModelRunner

public class ModelRunner
extends java.lang.Object

A model runner is a highly configurable controller that receives messages and conditionally calls methods that handle them (the "system reactions").

The runner is configured by the model it owns. Each real user needs an instance of a runner, as the runner determines the user journey.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	ModelRunner.As

Constructor Summary

Constructors

Constructor and Description
ModelRunner() Constructor for creating a model runner.

Method Summary

Modifier and Type	Method and Description
ModelRunner.As	as(AbstractActor runActor) After you called this method, the runner will only react in steps that have explicitly set the specified actor as one of its actors, or that are declared as "autonomous system reactions".
boolean	canReactTo(java.lang.Class<? extends java.lang.Object> messageClass) Returns whether at least one step can react to a message of the specified class.
java.util.Optional<Flow>	getLatestFlow() Returns the flow the latest step that has been run is contained in.
java.util.Optional<Step>	getLatestStep() Returns the latest step that has been run by this runner.
java.util.Set<java.lang.Class<?>>	getReactToTypes() Returns the classes of messages the runner can react to.
java.lang.Object[]	getRecordedMessages() Returns the recorded messages that the runner reacted to so far.
java.lang.String[]	getRecordedStepNames() Returns the recorded names of the steps that have been run so far.
java.util.Set<Step>	getStepsThatCanReactTo(java.lang.Class<? extends java.lang.Object> messageClass) Returns the steps in the model that can react to the specified message class.
protected void	handleException(java.lang.Exception e) Overwrite this method to control what happens exactly when an exception is thrown by a system reaction.
ModelRunner	handleUnhandledWith(java.util.function.Consumer<java.lang.Object> unhandledMessageHandler) Define handler for messages that the runner doesn't react to.
ModelRunner	handleWith(java.util.function.Consumer<StepToBeRun> messageHandler) Define a custom message handler.
boolean	isRunning() Returns whether the runner is currently running.
ModelRunner	publishWith(java.util.function.Consumer<java.lang.Object> eventPublisher) Define a custom publisher for events.
<U> java.util.Optional<U>	reactTo(java.lang.Object... messages) Call this method to provide several messages to the runner.
<T,U> java.util.Optional<U>	reactTo(T message) Call this method to provide a message (i.e. command or event object) to the runner.
void	restart() Restarts the runner, resetting it to its original defaults ("no flow has been run, no step has been run").
ModelRunner	run(Model model) Configures the runner to use the specified model.
void	setLatestStep(Step latestStep) Sets the latest step run by the runner.
ModelRunner	startRecording() After calling this method, until recording is stopped, messages and step names are recorded.
void	stop() Stops the runner.
ModelRunner	stopRecording() When calling this method, recording is stopped.

Methods inherited from class java.lang.Object

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

Constructor Detail

ModelRunner

public ModelRunner()

Constructor for creating a model runner.

Method Detail

handleWith

public ModelRunner handleWith(java.util.function.Consumer<StepToBeRun> messageHandler)

Define a custom message handler. It can perform tasks before/after running the step (which will trigger the system reaction method defined in the model). A custom message handler is useful for cross-cutting concerns, e.g. measuring performance.

Parameters:

messageHandler - the custom message handler

Returns:

this model runner, for chaining

handleUnhandledWith

public ModelRunner handleUnhandledWith(java.util.function.Consumer<java.lang.Object> unhandledMessageHandler)

Define handler for messages that the runner doesn't react to.

Parameters:

unhandledMessageHandler - the handler for messages not handled by the runner

Returns:

this model runner, for chaining

publishWith

public ModelRunner publishWith(java.util.function.Consumer<java.lang.Object> eventPublisher)

Define a custom publisher for events. It will be called after a system reaction has been run, for the returned event objects of the system reaction.

Parameters:

eventPublisher - the custom event eventPublisher

Returns:

this model runner, for chaining

restart

public void restart()

Restarts the runner, resetting it to its original defaults ("no flow has been run, no step has been run").

run

public ModelRunner run(Model model)

Configures the runner to use the specified model. After you called this method, the runner will accept messages via reactTo(Object).

As a side effect, this method immediately triggers "autonomous system reactions".

Parameters:

model - the model that defines the runner's behavior

Returns:

this model runner, for chaining

as

public ModelRunner.As as(AbstractActor runActor)

After you called this method, the runner will only react in steps that have explicitly set the specified actor as one of its actors, or that are declared as "autonomous system reactions".

Parameters:

runActor - the actor to run as

Returns:

object for method chaining

isRunning

public boolean isRunning()

Returns whether the runner is currently running.

Returns:

true if the runner is running, false otherwise.

See Also:

run(Model)

stop

public void stop()

Stops the runner. It will not be reacting to messages, until run(Model) is called again.

reactTo

public <U> java.util.Optional<U> reactTo(java.lang.Object... messages)

Call this method to provide several messages to the runner. For each message, reactTo(Object) is called.

Type Parameters:

U - the return type that you as the user expects.

Parameters:

messages - the message objects

Returns:

the event that was published (latest) if the system reacted, or an empty Optional.

reactTo

public <T,U> java.util.Optional<U> reactTo(T message)

Call this method to provide a message (i.e. command or event object) to the runner.

If it is running, the runner will then check which steps can react. If a single step can react, the runner will call the message handler with it. If no step can react, the runner will either call the handler defined with handleUnhandledWith(Consumer), or if no such handler exists, consume the message silently. If more than one step can react, the runner will throw an exception.

After that, the runner will trigger "autonomous system reactions". Note that if you provide a collection as the first and only argument, this will be flattened to the objects in the collection, and for each object reactTo(Object) is called.

See canReactTo(Class) for a description of what "can react" means.

Type Parameters:

T - the type of message

U - the return type that you as the user expects.

Parameters:

message - the message object

Returns:

the event that was published (latest) if the system reacted, or an empty Optional.

Throws:

MoreThanOneStepCanReact - when more than one step can react

InfiniteRepetition - when a step has an always true condition, or there is an infinite loop.

java.lang.ClassCastException - when type of the returned instance isn't U

canReactTo

public boolean canReactTo(java.lang.Class<? extends java.lang.Object> messageClass)

Returns whether at least one step can react to a message of the specified class.

A step "can react" if all of the following conditions are met: a) the runner is running b) one of the step's actors matches the actor the runner is run as c) the step's message class is the same or a superclass of the specified message class d) the step has a condition that is true

Parameters:

messageClass - the type of message to check steps for

Returns:

true if the runner is running and at least one step can react, false otherwise

getReactToTypes

public java.util.Set<java.lang.Class<?>> getReactToTypes()

Returns the classes of messages the runner can react to.

See canReactTo(Class) for a description of what "can react" means.

Returns:

the collection of message types

getStepsThatCanReactTo

public java.util.Set<Step> getStepsThatCanReactTo(java.lang.Class<? extends java.lang.Object> messageClass)

Returns the steps in the model that can react to the specified message class.

Parameters:

messageClass - the class of messages

Returns:

the steps that can react to the class of messages

handleException

protected void handleException(java.lang.Exception e)

Overwrite this method to control what happens exactly when an exception is thrown by a system reaction. The behavior implemented in runner: the model runner reacts to the exception. You may replace this with a more sophisticated behavior, that for example involves some kind of logging.

Parameters:

e - the exception that has been thrown by the system reaction

getLatestStep

public java.util.Optional<Step> getLatestStep()

Returns the latest step that has been run by this runner.

Returns:

the latest step run

setLatestStep

public void setLatestStep(Step latestStep)

Sets the latest step run by the runner.

Use this method if you want to restore some previous state, normally you should influence the behavior of the runner by calling reactTo(Object).

Parameters:

latestStep - the latest step run

getLatestFlow

public java.util.Optional<Flow> getLatestFlow()

Returns the flow the latest step that has been run is contained in.

Returns:

the latest flow run

startRecording

public ModelRunner startRecording()

After calling this method, until recording is stopped, messages and step names are recorded. If messages/step names have been recorded before calling this method, they are discarded.

Returns:

this model runner for method chaining

stopRecording

public ModelRunner stopRecording()

When calling this method, recording is stopped. No messages and step names are recorded until startRecording() is called again.

Returns:

this model runner for method chaining

getRecordedStepNames

public java.lang.String[] getRecordedStepNames()

Returns the recorded names of the steps that have been run so far.

If no step has been run, an empty array is returned. For example, this method can used with the assertArrayEquals method of JUnit to compare the actual names of steps that have been run (returned by this method) to the expected step names.

Returns:

the ordered names of steps run by this runner

getRecordedMessages

public java.lang.Object[] getRecordedMessages()

Returns the recorded messages that the runner reacted to so far.

If no messages have caused a system reaction, an empty array is returned. For example, this method can used with the assertArrayEquals method of JUnit to compare the actual messages that caused a reaction (returned by this method) to the expected messages.

Returns:

the messages that caused a system reaction, in order of occurrence