org.glassfish.internal.api

Interface UndoableCommand

All Superinterfaces:

org.glassfish.api.admin.AdminCommand

public interface UndoableCommand
extends org.glassfish.api.admin.AdminCommand

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 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 AdminCommand.execute(AdminCommandContext) invocation, as well as any supplemented commands that implement this interface.

Author:

Jerome Dochez

Method Summary

Methods

Modifier and Type	Method and Description
org.glassfish.api.ActionReport.ExitCode	prepare(org.glassfish.api.admin.AdminCommandContext context, org.glassfish.api.admin.ParameterMap parameters) Checks whether the command execution has a chance of success before the execution is attempted.
void	undo(org.glassfish.api.admin.AdminCommandContext context, org.glassfish.api.admin.ParameterMap parameters, List<com.sun.enterprise.config.serverbeans.Server> instances) Undo a previously successful execution of the command implementation.

Methods inherited from interface org.glassfish.api.admin.AdminCommand

execute

Method Detail

prepare

@IfFailure(value=Error)
org.glassfish.api.ActionReport.ExitCode prepare(org.glassfish.api.admin.AdminCommandContext context,
                                                        org.glassfish.api.admin.ParameterMap parameters)

Checks whether the command execution has a chance of success before the execution is attempted. This could be useful in clustering environment where you must check certain pre-conditions before attempting to run an administrative change.

For instance, the change-admin-password should probably not be attempted if all the servers instances are on-line and can be notified of the change.

No changes to the configuration should be made within the implementation of the prepare method since #undo(AdminCommandContext, ParameterMap, List) will not be called if the command execution stops at the prepare phase.

Note that if, as part of prepare, remote instances have to be contacted, then it is the responsibility of the command implementation to invoke remote instaces for such verification. The framework will call prepare() method in DAS before execution of the main command and the execution of the main command will happen only if the prepare() call returns ActionReport.ExitCode.SUCCESS on DAS.

Parameters:

context - the command's context

parameters - parameters to the commands.

undo

void undo(org.glassfish.api.admin.AdminCommandContext context,
        org.glassfish.api.admin.ParameterMap parameters,
        List<com.sun.enterprise.config.serverbeans.Server> instances)

Undo a previously successful execution of the command implementation. The context for undoing the administrative operation should be obtained from either the parameters passed to the command execution or the command instance context. The list of servers indicates to the command implementation on which servers the command succeeded The command implementation is guaranteed that the #undo(AdminCommandContext, ParameterMap, List) is called on DAS if the main command execution failed on one instance but it is the responsiblity of the command implementation to invoke remote instances to do the actual undo if required

Parameters:

context - the command's context

parameters - parameters passed to the command.

instances - instances on which the command succeeded