Interface that augment the AdminCommand responsibilities by adding the ability
to undo a previously successful execution of an administrative command.
The ability to rollback is not meant to be used as an exception handling
mechanism while in the
AdminCommand#execute(AdminCommandContext) invocation.
The ability to rollback is meant for undoing a successful command execution that
need to be roll-backed for reasons outside of the knowledge of the command
implementation.
Roll-backing can be very useful in clustering mode where actions can be performed
successfully on some instances but fail on others necessitating to rollback the
entire set of instances to a state previous to the action execution.
The implementations of this interface must retain any pertinent information necessary
to undo the command within its instance context. Therefore all UndoableCommand implementations
must have a
org.glassfish.hk2.api.PerLookup scope otherwise the system will flag it
as an error and will refuse to execute the command.
An undo-able command has a slightly more complicated set of phases execution as compared
to the AdminCommand.
During the first phase, called the prepare phase, the framework will call
this command prepare method as well as all supplemented commands prepare methods (if such
supplemented commands implement the UndoableCommand interface). If the prepare phase is
not successful, the command execution stops here and the command feedback is returned to the
initiator.
Once the prepare phase has succeeded, the normal
AdminCommand#execute(AdminCommandContext)method is invoked (and any supplemented methods).
If the framework is electing that successful commands execution need to be rolled back, it will
call the
#undo(AdminCommandContext, ParameterMap, List) method on the same instance that was used for the
#execute(AdminCommandContext) invocation, as well as any supplemented commands that implement
this interface.