Package org.lsst.ccs

Class CommandHelper

java.lang.Object

org.lsst.ccs.CommandHelper

public class CommandHelper
extends Object

A class to make it easier to execute commands while correctly handling ACKS, NACKS, and exceptions. Usage example:

 @Command(type = Command.CommandType.ACTION, description = "Perform a clear operation", level=Command.NORMAL, autoAck=false)
 public void clear(int nClears) {
     helper()
       .precondition(nClears > 0 && nClears <= 15, "Invalid nClears: %d", nClears)
       .precondition(FocalPlaneState.QUIESCENT , FocalPlaneState.NEEDS_CLEAR)
       .enterFaultOnException(true)
       .action(()-> { subsys.getSequencers().clear(nClears); });
      }
 

Author:

tonyj

See Also:

• Agent.helper()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	CommandHelper.CommandFailedException	Exception thrown if the target of the action method throws an exception.
static interface	CommandHelper.RunnableWithException	An interface similar to Runnable but which allows exceptions to be generated and handled.

Constructor Summary

Constructors

Constructor	Description
CommandHelper(Agent agent)	Create a new CommandHelper.

Method Summary

Modifier and Type	Method	Description
<T> T	action(Callable<T> callable)	Executes the specified callable if all preconditions were me.
void	action(CommandHelper.RunnableWithException runnable)	Execure the specified runnable if all preconditions were met.Designed to be the last method on the method chain.
CommandHelper	duration(Duration duration)	Set the duration for the command
CommandHelper	duration(Supplier<Duration> durationSupplier)	Set the duration for the command
CommandHelper	enterFaultOnException(boolean enterFault)	Controls whether exceptions should be thrown back to caller, or whether the should cause the subsystem to entry fault state
CommandHelper	precondition(boolean ok)	A simple precondition.
CommandHelper	precondition(boolean ok, String reason, Object... args)	A precondition with a reason.
CommandHelper	precondition(boolean ok, String reason, Supplier<Object>... args)	A precondition with a reason and delayed evaluation of provided arguments.
CommandHelper	precondition(Enum... states)	A precondition with one of more states.

Methods inherited from class java.lang.Object

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

Constructor Details

CommandHelper

public CommandHelper(Agent agent)

Create a new CommandHelper. This method is normally not called directly, use instead Agent.helper().

Parameters:

agent - The agent associated with this command helper.

Method Details

precondition

public CommandHelper precondition(boolean ok)

A simple precondition.

Parameters:

ok - If false command will not proceed

Returns:

The CommandHelper, to allow method chaining

precondition

public CommandHelper precondition(boolean ok,
 String reason,
 Object... args)

A precondition with a reason.

Parameters:

ok - If false command will not proceed

reason - The reason to use if precondition is not met

args - If present then reason is interpreted as a format string, and args are substituted into the format

Returns:

The CommandHelper, to allow method chaining

precondition

public CommandHelper precondition(boolean ok,
 String reason,
 Supplier<Object>... args)

A precondition with a reason and delayed evaluation of provided arguments.

Parameters:

ok - If false command will not proceed

reason - The reason to use if precondition is not met

args - If present then reason is interpreted as a format string, and the Suppliers are evaluated at the time the failure reason is processed.

Returns:

The CommandHelper, to allow method chaining

precondition

public CommandHelper precondition(Enum... states)

A precondition with one of more states. Precondition fails if the subsystems is not in one of the listed states.

Parameters:

states - The states to test

Returns:

The CommandHelper, to allow method chaining

duration

public CommandHelper duration(Duration duration)

Set the duration for the command

Parameters:

duration - The duration for the command, overrides the default duration provided by any annotation.

Returns:

The CommandHelper, to allow method chaining

duration

public CommandHelper duration(Supplier<Duration> durationSupplier)

Set the duration for the command

Parameters:

durationSupplier - The Supplier of a duration for the command, overrides the default duration provided by any annotation.

Returns:

The CommandHelper, to allow method chaining

enterFaultOnException

public CommandHelper enterFaultOnException(boolean enterFault)

Controls whether exceptions should be thrown back to caller, or whether the should cause the subsystem to entry fault state

Parameters:

enterFault - If true then any exceptions during command execution will be caught, and the subsystem will be put into fault state.

Returns:

The CommandHelper, to allow method chaining

action

public <T> T action(Callable<T> callable)

Executes the specified callable if all preconditions were me. Designed to be the last method on the method chain.

Type Parameters:

T - The return type of the callable

Parameters:

callable - The callable to call

Returns:

The result of the callable

action

public void action(CommandHelper.RunnableWithException runnable)

Execure the specified runnable if all preconditions were met.Designed to be the last method on the method chain.

Parameters:

runnable - The runnable to run