Add a checkpoint to a custom plugin

This topic guides you through the process of adding a checkpoint to a custom plugin in Deploy.

Important: Although the content in this topics is relevant for this version of Deploy, we recommend that you use the rules system for customizing deployment plans. For more information, see Getting started with Deploy rules.

As a plugin author, you typically execute multiple steps when your CI is created, destroyed or modified. You can let Deploy know when the action performed on your CI is complete, so that Deploy can store the results of the action in its repository. If the deployment plan fails halfway through, Deploy can generate a customized rollback plan that contains steps to rollback only those changes that are already committed.

Deploy must be instructed to add a checkpoint after a step that completes the operation on the CI. Once the step completes successfully, Deploy will checkpoint, by committing to the repository, the operation on the CI and generate rollback steps if required.

Here is an example of adding a checkpoint:

@Create
public void executeCreateCommand(DeploymentPlanningContext ctx, Delta delta) {
    ctx.addStepWithCheckpoint(new ExecuteCommandStep(order, this), delta);
}

The following example instructs Deploy to add the specified step and to add a create checkpoint.

@Destroy
public void destroyCommand(DeploymentPlanningContext ctx, Delta delta) {
    if (undoCommand != null) {
        DeployedCommand deployedUndoCommand = createDeployedUndoCommand();
        ctx.addStepWithCheckpoint(new ExecuteCommandStep(undoCommand.getOrder(), deployedUndoCommand), delta);
    } else {
        ctx.addStepWithCheckpoint(new NoCommandStep(order, this), delta);
    }
}

Deploy will add a destroy checkpoint after the created step.

Checkpoints with the modify action on CIs are more complicated because a modify operation is frequently implemented as a combination of destroy and a create. In this case, we need to instruct Deploy to add a checkpoint after the step, removing the old version and the checkpoint after creating the new step. We also need to instruct Deploy that the first checkpoint of the modify operation is now a destroy checkpoint. For example:

@Modify
public void executeModifyCommand(DeploymentPlanningContext ctx, Delta delta) {
    if (undoCommand != null && runUndoCommandOnUpgrade) {
        DeployedCommand deployedUndoCommand = createDeployedUndoCommand();
        ctx.addStepWithCheckpoint(new ExecuteCommandStep(undoCommand.getOrder(), deployedUndoCommand), delta, Operation.DESTROY);
    }

    ctx.addStepWithCheckpoint(new ExecuteCommandStep(order, this), delta);
}

Note: The additional parameter Operation.DESTROY in the addStepWithCheckpoint invocation informs Deploy that the checkpoint is a destroy checkpoint even though the delta that was passed in represents a modify operation.

The final step uses the modify operation from the delta to indicate the CI is now present.

Implicit checkpoints

If you do not specify any checkpoints for a delta, Deploy will add a checkpoint to the last step of the delta.

Example

We perform the initial deployment of a package that contains an SQL script and a WAR file. The deployment plan looks like:

1. Execute the SQL script.
2. Upload the WAR file to the host where the servlet container is present.
3. Register the WAR file with the servlet container.

Without checkpoints, Deploy does not know how to roll back this plan if it fails on a step. Deploy adds implicit checkpoints based on the two delta in the plan: a new SQL script and a new WAR file. Step 1 is related to the SQL script, while steps 2 and 3 are related to the WAR file. Deploy adds a checkpoint to the last step of each delta. The resulting plan looks like:

1. Execute the SQL script and checkpoint the SQL script.
2. Upload the WAR file to the host where the servlet container is present.
3. Register the WAR file with the servlet container and checkpoint the WAR file.

If step 1 was executed successfully but step 2 or 3 failed, Deploy knows it must roll back the executed SQL script, but not the WAR file.