XL Deploy Java API Manual

XL Deploy allows customization using the Java programming language. By implementing a server plugpoint, certain XL Deploy server functionality can be changed to adapt the product to your needs. And if you want to use XL Deploy with new middleware, you can implement a custom plugin.

XL Deploy architecture

Before you customize XL Deploy functionality, you should understand the XL Deploy architecture. Refer to the Customization Manual for more information.

Implementing server plugpoints

Functionality in the XL Deploy Server can be customized by using plugpoints. Plugpoints are specified and implemented in Java. On startup, XL Deploy scans its classpath for implementations of its plugpoints in the com.xebialabs or ext.deployit packages and prepares them for use. There is no additional configuration required.

The XL Deploy Server supports the following plugpoints:

protocol: specify a new method for connecting to remote hosts
deployment package importer: allow XL Deploy to import deployment packages in a custom format
orchestrator: control the way XL Deploy combines plans to generate the overall deployment workflow
event listener: specify a listener for XL Deploy notifications and commands

Refer to the Javadoc for detailed information about the Java API.

Defining Protocols

A protocol in XL Deploy is a method for making a connection to a host. Overthere, XL Deploy's remote execution framework, uses protocols to build a connection with a target machine. Protocol implementations are read by Overthere when XL Deploy starts.

Classes implementing a protocol must adhere to two requirements:

the class must implement the OverthereConnectionBuilder interface
the class must have the @Protocol annotation
define a custom host CI type that overrides the default value for property protocol.

Example of a custom host CI type:

<type type="custom.MyHost" extends="overthere.Host">
  <property name="protocol" default="myProtocol" hidden="true"/>
</type>

The OverthereConnectionBuilder interface specifies only one method, connect. This method creates and returns a subclass of OverthereConnection representing a connection to the remote host. The connection must provide access to files (OverthereFile instances) that XL Deploy uses to execute deployments.

For more information, see the Overthere project.

Defining Importers and ImportSources

An importer is a class that turns a source into a collection of XL Deploy entities. Both the import source as well as the importer can be customized. XL Deploy comes with a default importer that understands the DAR package format (see the Packaging Manual for details).

Import sources are classes implementing the ImportSource interface and can be used to obtain a handle to the deployment package file to import. Import sources can also implement the ListableImporter interface, which indicates they can produce a list of possible files that can be imported. The user can make a selection out of these options to start the import process.

When the import source has been selected, all configured importers in XL Deploy are invoked in turn to see if any importer is capable of handling the selected import source (the canHandle method). The first importer that indicates it can handle the package is used to perform the import. XL Deploy's default importer is used as a fallback.

First, the preparePackage method is invoked. This instructs the importer to produce a PackageInfo instance describing the package metadata. This data is used by XL Deploy to determine whether the user requesting the import has sufficient rights to perform it. If so, the importer's importEntities method is invoked, allowing the importer to read the import source, create deployables from the package and return a complete ImportedPackage instance. XL Deploy will handle storing of the package and contents.

Defining Orchestrators

An orchestrator is a class that performs the Orchestration stage described above. The orchestrator is invoked after the delta-analysis phase and before the planning stage and implements the Orchestrator interface containing a single method:

Orchestration orchestrate(DeltaSpecification specification);

For example, this is the (Scala) implementation of the default orchestrator:

@Orchestrator.Metadata (name = "default", description = "The default orchestrator")
class DefaultOrchestrator extends Orchestrator {
  def orchestrate(specification: DeltaSpecification) = interleaved(getDescriptionForSpec(specification), specification.getDeltas)
}

It takes all delta specifications and puts them together in a single, interleaved plan. This results in a deployment plan that is ordered solely on the basis of the step's order property.

In addition to the default orchestrator, XL Deploy also contains the following orchestrators (see also the Reference manual):

sequential-by-container and parallel-by-container orchestrator. These orchestrators groups steps that deal with the same container together, enabling deployments across a farm of middleware.
sequential-by-composite-package and parallel-by-composite-package orchestrators. These orchestrators groups steps per contained package together. The order of the member packages in the composite package is preserved.
sequential-by-deployment-group and parallel-by-deployment-group orchestrators. These orchestrators use the deployment group synthetic property on a container to group steps for all containers with the same deployment group. These orchestrators are provided by a separate plugin that comes bundled with XL Deploy inside the plugins/ directory.

The following orchestrators have been DEPRECATED, please do not use them in new deployments. Their behaviour is the same as the suggested replacements:

container-by-container-serial: use sequential-by-container instead.
composite-package: use sequential-by-composite-package instead.
group-based: use sequential-by-deployment-group instead.

Defining Event Listeners

The XL Deploy Core sends events that listeners can act upon. There are two types of events in XL Deploy system:

Notifications -- Events that indicate that XL Deploy has executed a particular action
Commands -- Events that indicate XL Deploy is about to to execute a particular action

The difference is that commands are fired before an action takes place, while notifications are fired after an action takes place.

Listening for notifications

Notifications indicate a particular action has occurred in XL Deploy. Some examples of notifications in XL Deploy are:

The system is started or stopped
A user logs into or out of the system
A CI is created, updated, moved or deleted
A security role is created, updated or deleted
A task (deployment, undeployment, control task or discovery) is started, cancelled or aborted

Notification event listeners are Java classes that have the @DeployitEventListener annotation and have one or more methods annotated with the T2 event bus @Subscribe annotation.

For example, this is the implementation of a class that logs all notifications it receives:

import nl.javadude.t2bus.Subscribe;

import com.xebialabs.deployit.engine.spi.event.AuditableDeployitEvent;
import com.xebialabs.deployit.engine.spi.event.DeployitEventListener;
import com.xebialabs.deployit.plugin.api.udm.ConfigurationItem;

/**
 * This event listener logs auditable events using our standard logging facilities.
 */
@DeployitEventListener
public class TextLoggingAuditableEventListener {

    @Subscribe
    public void log(AuditableDeployitEvent event) {
        logger.info("[{}] - {} - {}", new Object[] { event.component, event.username, event.message });
    }

    private static Logger logger = LoggerFactory.getLogger("audit");
}

Listening for commands

Commands indicate that XL Deploy has been asked to perform a particular action. Some examples of commands in XL Deploy are:

A request to create a CI or CIs has been received
A request to update a CI has been received
A request to delete a CI or CIs has been received

Command event listeners are Java classes that have the @DeployitEventListener annotation and have one or more methods annotated with the T2 event bus @Subscribe annotation. Command event listeners have the option of vetoing a particular command which causes it to not be executed. Vetoing event listeners indicate that they have the ability to veto the command in the Subscribe annotation and veto the command by throwing a VetoException from the event handler method.

As an example, this listener class listens for update CI commands and optionally vetoes them:

@DeployitEventListener
public class RepositoryCommandListener {

    public static final String ADMIN = "admin";

    @Subscribe(canVeto = true)
    public void checkWhetherUpdateIsAllowed(UpdateCiCommand command) throws VetoException {
        checkUpdate(command.getUpdate(), newHashSet(command.getRoles()), command.getUsername());
    }

    private void checkUpdate(final Update update, final Set<String> roles, final String username) {
        if(...) {
            throw new VetoException("UpdateCiCommand vetoed");
        }
    }
}

Writing a plugin

Writing a custom plugin is the most powerful way to extend XL Deploy. It uses XL Deploy's Java plugin API which is also used by all of the plugins provided by XebiaLabs. The plugin API specifies a contract between XL Deploy core and a plugin that ensures that a plugin can safely contribute to the calculated deployment plan. To understand the plugin API, it is helpful to learn about the XL Deploy system architecture and how the plugins are involved in performing a deployment. The following sections assume the read has this background information.

Refer to the Javadoc for detailed information about the Java API.

UDM and Java

The UDM concepts are represented in Java by interfaces:

Deployable classes represent deployable CIs.
Container classes represent container CIs.
Deployed classes represent deployed CIs.

In addition to these types, plugins also specify the behavior required to perform the deployment. That is, which actions (steps) are needed to ensure that a deployable ends up in the container as a deployed. In good OO-fashion, this behavior is part of the Deployed class.

Let's look at the mechanisms available to plugin writers in each of the two deployment phases, Specification and Planning.

Specifying a Namespace

All of the CIs in XL Deploy are part of a namespace to distinguish them from other, similarly named CIs. For instance, CIs that are part of the UDM plugin all use the udm namespace (such as udm.Deployable).

Plugins implemented in Java must specify their namespace in a source file called package-info.java. This file provides package-level annotations and is required to be in the same package as your CIs.

This is an example package-info file:

@Prefix("yak")
package com.xebialabs.deployit.plugin.test.yak.ci;

import com.xebialabs.deployit.plugin.api.annotation.Prefix;

Specification

This section describes Java classes used in defining CIs that are used in the Specification stage.

udm.ConfigurationItem and udm.BaseConfigurationItem

The udm.BaseConfigurationItem is the base class for all the standard CIs in XL Deploy. It provides the syntheticProperties map and a default implementation for the name of a CI.

udm.Deployable and udm.BaseDeployable

The udm.BaseDeployable is the default base class for types that are deployable to udm.Container CIs. It does not add any additional behavior

udm.EmbeddedDeployable and udm.BaseEmbeddedDeployable

The udm.BaseEmbeddedDeployable is the default base class for types that can be nested under a udm.Deployable CI, and which participate in the deployment of the udm.Deployable to a udm.Container. It does not add any additional behavior.

udm.Container and udm.BaseContainer

The udm.BaseContainer is the default base class for types that can contain udm.Deployable CIs. It does not add any additional behavior

udm.Deployed and udm.BaseDeployed

The udm.BaseDeployed is the default base class for types that specify which udm.Deployable CI can be deployed onto which udm.Container CI.

udm.EmbeddedDeployed and udm.BaseEmbeddedDeployed

The udm.BaseEmbeddedDeployed is the default base class for types that are nested under a udm.Deployed CI. It specifies which udm.EmbeddedDeployable can be nested under which udm.Deployed or udm.EmbeddedDeployed CI.

Additional UDM concepts

In addition to these base types, the UDM defines a number of implementations with higher level concepts that facilitate deployments.

udm.Environment: The Environment is the target for a deployment in XL Deploy. It has members of type udm.Container
udm.Application: The Application is a grouping of multiple udm.DeploymentPackage CIs that can each be the source of a deployment (for example: application = PetClinic; version = 1.0, 2.0, ...)
udm.DeploymentPackage: A deployment package has a set of udm.Deployable CIs, and it is the source for a deployment in XL Deploy.
udm.DeployedApplication: The DeployedApplication resembles the deployment of a udm.DeploymentPackage to a udm.Environment with a number of specific udm.Deployed CIs
udm.Artifact: An implementation of a udm.Deployable which resembles a 'physical' artifact on disk (or memory)
udm.FileArtifact: A udm.Artifact which points to a single file
udm.FolderArtifact: A udm.Artifact which points to a directory structure

Mapping Deployables to Containers

When creating a deployment, the deployables in the package are targeted to one or more containers. The deployable on the container is represented as a deployed. Deployeds are defined by the deployable CI type and container CI type they support. Registering a deployed CI in XL Deploy informs the system that the combination of the deployable and container is possible and how it is to be configured. Once such a CI exists, XL Deploy users can create them in the GUI by dragging the deployable to the container.

When you drag a deployable that contains embedded-deployables to a container, XL Deploy will create an deployed with embedded-deployeds.

Deployment-level properties

It is also possible to set properties on the deployment (or undeployment) operation itself rather than on the individual deployed. The properties are specified by modifying udm.DeployedApplication in the synthetic.xml.

Here's an example:

<type-modification type="udm.DeployedApplication">
   <property name="username" transient="true"/>
   <property name="password" transient="true" password="true"/>
   <property name="nontransient" required="false" category="SomeThing"/>
</type-modification>

Here, username and password are required properties and need to be set before deployment plan is generated. This can be done in the UI by clicking on the Deployment Properties… button before starting a deployment.

In the CLI, properties are set on the deployment.deployedApplication:

d = deployment.prepareInitial('Applications/AnimalZoo-ear/1.0', 'Environments/myEnv')
d.deployedApplication.username = 'scott'
d.deployedApplication.password = 'tiger'

Deployment-level properties may be defined as transient, in which case the value will not be stored after deployment. This is useful for user names and password for example. On the other hand, non-transient properties will be available afterwards when doing an update or undeployment.

Analogous to the copying of values of properties from the deployable to the deployed, XL Deploy will copy properties from the udm.DeploymentPackage to the deployment level properties of the udm.DeployedApplication.

Planning

During planning a Deployment plugin can contribute steps to the deployment plan. Each of the mechanisms that can be used is described below.

@PrePlanProcessor and @PostPlanProcessor

The @PrePlanProcessor and @PostPlanProcessor annotations can be specified on a method to define a pre- or postprocessor. The pre- or postprocessor takes an optional order attribute which defaults to '100'; lower order means it is earlier, higher order means it is later in the processor chain. The method should take a DeltaSpecification and return either a Step, List of Step or null, the name can be anything, so you can define multiple pre- and postprocessors in one class. See these examples:

@PrePlanProcessor
public Step preProcess(DeltaSpecification specification) { ... }

@PrePlanProcessor
public List<Step> foo(DeltaSpecification specification) { ... }

@PostPlanProcessor
public Step postProcess(DeltaSpecification specification) { ... }

@PostPlanProcessor
public List<Step> bar(DeltaSpecification specification) { ... }

As a pre- or postprocessor is instantiated when it is needed, it should have a default constructor. Any fields on the class are not set, so the annotated method should not rely on them being set.

@Create, @Modify, @Destroy, @Noop

Deployeds can contribute steps to a deployment in which it is present. The methods that are invoked should also be specified in the udm.Deployed CI. It should take a DeploymentPlanningContext (to which one or more Steps can be added with specific ordering) and a Delta (specifying the operation that is being executed on the CI). The return type of the method should be void.

The method is annotated with the operation that is currently being performed on the Deployed CI. The following operations are available:

@Create when deploying a member for the first time
@Modify when upgrading a member
@Destroy when undeploying a member
@Noop when there is no change

In the following example, the method createEar() is called for both a create and modify operation of the DeployedWasEar.

public class DeployedWasEar extends BaseDeployed<Ear, WasServer> {
    ...

    @Create @Modify
    public void createEar(DeploymentPlanningContext context, Delta delta) {
        // do something with my field and add my steps to the result
        // for a particular order
        context.addStep(new CreateEarStep(this));
    }
}

Note: These methods cannot occur on udm.EmbeddedDeployed CIs. The EmbeddedDeployed CIs do not add any additional behavior, but can be checked by the owning udm.Deployed and that can generate steps for the EmbeddedDeployed CIs.

@Contributor

A @Contributor contributes steps for the set of Deltas in the current subplan being evaluated. The methods annotated with @Contributor can be present on any Java class which has a default constructor. The generated steps should be added to the collector argument context.

@Contributor
public void contribute(Deltas deltas, DeploymentPlanningContext context) { ... }

The DeploymentPlanningContext

Both a contributor and specific contribution methods receive a DeploymentPlanningContext object as a parameter. The context is used to add steps to the deployment plan, but it also provides some additional functionality the plugin can use:

getAttribute() / setAttribute(): contributors can add information to the planning context during planning. This information will be available during the entire planning phase and can be used to communicate between contributors or with the core.
getDeployedApplication(): this allows contributors to access the deployed application that the deployeds are a part of.
getRepository(): contributors can access the XL Deploy repository to determine additional information they may need to contribute steps. The repository can be read from and written to during the planning stage.

Checkpoints

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

XL Deploy must be told to add a checkpoint after a step that completes the operation on the CI. Once the step completes successfully, XL Deploy will checkpoint (commit to the repository) the operation on the CI (the destroy operation will remove it, the create operation will create it and the modify operation updates it) and generate rollback steps for it if needed.

Here's an example of adding a checkpoint:

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

This informs XL Deploy to add the specified step and to add a create checkpoint. Here's another example:

@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);
    }
}

XL Deploy will add a destroy checkpoint after the created step.

Checkpoints with the modify action on CIs are a bit more complicated since a modify operation is frequently implemented as a combination of destroy (remove the old version of the CI) and a create (create the new version). In this case, we need to tell XL Deploy to add a checkpoint after the step removing the old version as well as a checkpoint after creating the new one. More specifically, we need to tell XL Deploy that the first checkpoint of the modify operation is really a destroy checkpoint. This is how that looks:

@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 that additional parameter Operation.DESTROY in the addStepWithCheckpoint invocation that lets XL Deploy know the checkpoint is a destroy checkpoint even though the delta passed in represents a modify operation.

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

Implicit checkpoints

If you do not specify any checkpoints for a delta, XL Deploy will add a checkpoint to the last step of the delta. Let's see how it works based on an example.

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

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

Without checkpoints, XL Deploy does not know how to roll back this plan if it fails on a step. XL 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. XL Deploy adds a checkpoint to the last step of each delta. The resulting plan looks like:

Execute the SQL script and checkpoint the SQL script.
Upload the WAR file to the host where the servlet container is present.
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, XL Deploy knows it must roll back the executed SQL script, but not the WAR file.

Define a custom step for rules

This section describes how to create a custom step that can be used in rules. For more information on rules, please refer to the Rules Manual.

Custom steps are defined in Java. To create a custom step that is available for rules, you must declare its name and parameters by providing annotations.

Step metadata annotation

The @StepMetadata annotation that is targeted to the Java type (that is, the Java class) specifies the name of the step.

Step parameter annotation

The @StepParameter annotation that is targeted to fields specifies the parameters. The name of the parameter is the Java field name of the parameter. The annotation allows you to specify metadata such as a label and description.

Supported parameter types

XL Deploy supports all Java primitives and string classes, including int, String, and so on.

Post Construct method

You can add additional logic to your step that will be executed when step is created within a rule. This can include defining default parameters of your step, applying complex validations and etc.

You have to annotate your method with @RulePostConstruct and make sure that this method accepts StepPostConstructContext as its argument.

Custom step example

This is an example of the implementation of a new type of step:

import com.xebialabs.deployit.plugin.api.flow.Step;
import com.xebialabs.deployit.plugin.api.rules.StepMetadata;
import com.xebialabs.deployit.plugin.api.rules.StepParameter;

@StepMetadata(name = "my-step")
public class MyStep implements Step {

    @StepParameter(label = "My parameter", description = "The foo's bar to baz the quuxes", required=false)
    private FooBarImpl myParam;
    @StepParameter(label = "Order", description = "The execution order of this step")
    private int order;

    public int getOrder() { return order; }
    public String getDescription() { return "Performing MyStep..."; }
    public StepExitCode execute(ExecutionContext ctx) throws Exception {
        /* ...perform deployment operations, using e.g. myParam...*/
    }
}

In xl-rules.xml, you refer to this rule as follows:

<rule ...>
    ...
    <steps>
        <my-step>
            <order>42</order>
            <my-param expression="true">deployed.foo.bar</myParam>
        </my-step>
    </steps>
</rule>

The script variant is as follows (note the underscores):

<rule ...>
    <steps>
        <script><![CDATA[
            context.addStep(steps.my_step(order=42, my_param=deployed.foo.bar))
        ]]></script>
    </steps>
</rule>

A step type is represented by a Java class with a default constructor implementing the Step interface. The resulting class file must be placed in the standard XL Deploy classpath.

The order represents the execution order of the step and the description is the description of this step, which will appear in the Plan Analyzer and the deployment execution plan. The execute method is executed when the step runs. The ExecutionContext interface that is passed to the execute method allows you to access the Repository and the step logs and allows you to set and get attributes, so steps can communicate data.

The step class must be annotated with the StepMetadata annotation, which has only a name String member. This name translates directly to a tag inside the steps section of xl-rules.xml, so the name must be XML-compliant. In this example, @StepMetadata(name="my-step") corresponds to the my-step tag.

Passing data to the step class is done using dependency injection. You annotate the private fields that you want to receive data with the StepParameter annotation.

In xl-rules.xml, you fill these fields by adding tags based on the field name. Camel-case names (such as myParam) are represented with dashes in XML (my-param) or underscores in Jython (my_param=...). The content of the resulting XML tags are interpreted as Jython expressions and must result in a value of the type of the private field.

Control Tasks

CIs can also define control tasks. Control tasks allow actions to be executed on CIs and can be invoked from the GUI or the CLI. Control tasks specify a list of steps to be executed in order. Control tasks can be parameterized in two ways:

by specifying arguments to the control task in the control task configuration
by allowing the user to specify parameters to the control task during control task execution

Arguments are configured in the control task definition in the synthetic.xml file. Arguments are specified as attributes on the synthetic method definition XML and are passed as-is to the control task. Parameters are specified by defining a parameters CI type. See the next section for more information about defining and using control task parameters.

Control tasks can be implemented in different ways:

In Java as methods annotated with the @ControlTask annotation. The method returns a List<Step> that the server will execute when it is invoked:

@ControlTask(description = "Start the Apache webserver")
public List<Step> start() {
    // Should return actual steps here
    return newArrayList();
}

In Java as a delegate which is bound via synthetic XML. Delegate is an object with a default constructor which contains one or more methods annotated with @Delegate. Those can be used to generate steps for control tasks.

class MyControlTasks {

    public MyControlTasks() {}

    @Delegate(name="startApache")
    public List<Step> start(ConfigurationItem ci, String method, Map<String, String> arguments) {
        // Should return actual steps here
        return newArrayList();
    }
}

...

<type-modification type="www.ApacheHttpdServer">
    <method name="startApache" label="Start the Apache webserver" delegate="startApache" argument1="value1" argument2="value2"/>
</type-modification>

When the start method above is invoked, the arguments argument1 and argument2 will be provided in the arguments parameter map.

Control Tasks with Parameters

Control tasks can have parameters. Parameters can be passed to the task that is started. In this way the control task can use these values during execution. Parameters are normal CIs, but need to extend the udm.Parameters CI. This is an example CI that can be used as control task parameter:

<type type="www.ApacheParameters" extends="udm.Parameters">
    <property name="force" kind="boolean" />
</type>

This example Parameters CI contains only one property named force of kind boolean. To define a control task with parameters on a CI, use the parameters-type attribute to specify the CI type:

<type-modification type="www.ApacheHttpdServer">
    <method name="start" />
    <method name="stop" parameters-type="www.ApacheParameters" />
    <method name="restart">
        <parameters>
            <parameter name="force" kind="boolean" />
        </parameters>
    </method>
</type-modification>

The stop method uses the www.ApacheParameters Parameters CI we just defined. The restart method has an inline definition for its parameters. This is a short notation for creating a Parameters definition. The inline parameters definition is equal to using www.ApacheParameters.

Parameters can also be defined in Java classes. To do this you need to specify the parameterType element of the ControlTask annotation. The ApacheParameters class is a CI and remember that it needs to extend the udm Parameters class.

@ControlTask(parameterType = "www.ApacheParameters")
public List<Step> startApache(final ApacheParameters params) {
    // Should return actual steps here
    return newArrayList();
}

If you want to use the Parameters in a delegate, your delegate method specify an additional 4th parameter of type Parameters:

@SuppressWarnings("unchecked")
@Delegate(name = "methodInvoker")
public static List<Step> invokeMethod(ConfigurationItem ci, final String methodName, Map<String, String> arguments, Parameters parameters) {
    // Should return actual steps here
    return newArrayList();
}

Discovery

XL Deploy's discovery mechanism is used to discover existing middleware and create them as CIs in the repository.

Do the following to enable discovery in your plugin:

Indicate that the CI type is discoverable (can be used as the starting point of the discovery process) by giving it the annotation Metadata(inspectable = true).
Indicate where in the repository tree the discoverable CI should be placed by adding an as-containment reference to the parent CI type. This also means that the context menu for the parent CI type will show the Discover menu item for your CI type.

For example, to indicate that a CI is stored under a overthere.Host CI in the repository, define the following field in your CI:

@Property(asContainment=true)
private Host host;

Implement an inspection method that inspects the environment for an instance of your CI. This method needs to add an inspection step to the given context.

For example:

@Inspect
public void inspect(InspectionContext ctx) {
    CliInspectionStep step = new SomeInspectionStep(...);
    ctx.addStep(step);
}

SomeInspectionStep should do two things: inspect properties of the current CIs and discover new ones. Those should be registered in InspectionContext with inspected(ConfigurationItem item) and discovered(ConfigurationItem item) methods respectively.

Validation rules

Next to defining CIs, new validation rules can also be defined in Java. These can then be used to annotate CIs or their properties so that XL Deploy can perform validations.

This is an example of a property validation rule called static-content that validates that a string kind field has a specific fixed value:

import com.xebialabs.deployit.plugin.api.validation.Rule;
import com.xebialabs.deployit.plugin.api.validation.ValidationContext;
import com.xebialabs.deployit.plugin.api.validation.ApplicableTo;
import com.xebialabs.deployit.plugin.api.reflect.PropertyKind;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@ApplicableTo(PropertyKind.STRING)
@Retention(RetentionPolicy.RUNTIME)
@Rule(clazz = StaticContent.Validator.class, type = "static-content")
@Target(ElementType.FIELD)
public @interface StaticContent {
    String content();

    public static class Validator
           implements com.xebialabs.deployit.plugin.api.validation.Validator<String> {
        private String content;

        @Override
        public void validate(String value, ValidationContext context) {
            if (value != null && !value.equals(content)) {
                context.error("Value should be %s but was %s", content, value);
            }
        }
    }
}

A validation rule consists of an annotation, in this case @StaticContent, which is associated with an implementation of com.xebialabs.deployit.plugin.api.validation.Validator<T>. They are associated using the @com.xebialabs.deployit.plugin.api.validation.Rule annotation. Each method of the annotation needs to be present in the validator as a property with the same name, see the content field and property above. It is possible to limit the kinds of properties that a validation rule can be applied to by annotating it with the @ApplicableTo annotation and providing that with the allowed property kinds.

When you've defined this validation rule, you can use it to annotate a CI like such:

public class MyLinuxHost extends BaseContainer {
    @Property
    @StaticContent(content = "/tmp")
    private String temporaryDirectory;
}

Or you can use it in synthetic XML in the following way:

<type name="ext.MyLinuxHost" extends="udm.BaseContainer">
    <property name="temporaryDirectory">
        <rule type="static-content" content="/tmp"/>
    </property>
</type>

Plugin versioning

Plugins, like all software, change. To support plugin changes, it is important to keep track of each plugin version as it is installed in XL Deploy. This makes it possible to detect when a plugin version changes and allows XL Deploy to take specific action, if required. XL Deploy keeps track of plugin versions by scanning each plugin jar for a file called plugin-version.properties. This file contains the plugin name and its current version.

For example:

plugin=sample-plugin
version=3.7.0

This declares the plugin to be the sample-plugin, version 3.7.0..

Repository upgrades

Sometimes, when changes occur in a plugin's structure (properties added, removed or renamed, the structure of CI trees updated), the XL Deploy repository must be migrated from the old to the new structure. Plugins contain upgrade classes for this.

Upgrade classes are Java classes that upgrade data in the repository that was produced by a previous version of the plugin to the current version of the plugin. XL Deploy scans the plugin JAR file for upgrade classes when it loads the plugin. When found, the current plugin version is compared with the plugin version registered in the XL Deploy repository. If the current version is higher than the previous version, the upgrade is executed. If the plugin was never installed before, the upgrade is not run.

An upgrade class extends the following base class:

public abstract class Upgrade implements Comparable<Upgrade> {

    public abstract boolean doUpgrade(RawRepository repository) throws UpgradeException;
    public abstract Version upgradeVersion();

    ...
}

The two methods each upgrade must implement are:

public abstract Version upgradeVersion();

This method returns the version of the upgrade. This is the version the upgrade migrates to. That is, after it has run, XL Deploy registers that this is the new current version.

Method

public abstract boolean doUpgrade(RawRepository repository) throws UpgradeException;

is the workhorse of the upgrade. Here, the class has access to the repository to perform any rewrites necessary.

When XL Deploy boots, it scans for upgrades to run. If it detects any, the boot process is stopped to report this fact to the user and to prompt them to make a backup of the repository first in case of problems. The user has the option to stop XL Deploy at this time if he does not want to perform the upgrade now. Otherwise, XL Deploy continues to boot and executes all upgrades sequentially.

Packaging your plugin

Plugins are distributed as standard Java archives (JAR files). Plugin JARs are put in the XL Deploy server plugins directory, which is added to the XL Deploy server classpath when it boots. XL Deploy will scan its classpath for plugin CIs and plugpoint classes and load these into its registry. These classes must be in the com.xebialabs or ext.deployit packages. The CIs are used and invoked during a deployment when appropriate.

Synthetic extension files packaged in the JAR file will be found and read. If there are multiple extension files present, they will be combined and the changes from all files will be combined.

Sample Java Plugin

This example describes some classes from a test plugin we use at XebiaLabs, the Yak plugin.

We'll use the following sample deployment in this example

The YakApp 1.1 deployment package.
The application contains two deployables: "yakfile1" and "yakfile2". Both are of type YakFile.
An environment that contains one container: "yakserver", of type YakServer.
An older version of the application, YakApp/1.0, is already deployed on the container.
YakApp/1.0 contains an older version of yakfile1, but yakfile2 is new in this deployment.

Deployable: YakFile

The YakFile is a deployable CI representing a file. It extends the built-in BaseDeployableFileArtifact class.

package com.xebialabs.deployit.plugin.test.yak.ci;

import com.xebialabs.deployit.plugin.api.udm.BaseDeployableFileArtifact;

public class YakFile extends BaseDeployableFileArtifact {
}

In our sample deployment, both yakfile1 and yakfile2 are instances of this Java class.

Container: YakServer

The YakServer is the container that will be the target of our deployment.

package com.xebialabs.deployit.plugin.test.yak.ci;

// imports omitted...

@Metadata(root = Metadata.ConfigurationItemRoot.INFRASTRUCTURE)
public class YakServer extends BaseContainer {

    @Contributor
    public void restartYakServers(Deltas deltas, DeploymentPlanningContext result) {
        for (YakServer yakServer : serversRequiringRestart(deltas.getDeltas())) {
            result.addStep(new StopYakServerStep(yakServer));
            result.addStep(new StartYakServerStep(yakServer));
        }
    }

    private static Set<YakServer> serversRequiringRestart(List<Delta> operations) {
        Set<YakServer> servers = new TreeSet<YakServer>();
        for (Delta operation : operations) {
            if (operation.getDeployed() instanceof RestartRequiringDeployedYakFile && operation.getDeployed().getContainer() instanceof YakServer) {
                servers.add((YakServer) operation.getDeployed().getContainer());
            }
        }
        return servers;
    }
}

This class shows several interesting features:

The YakServer extends the built-in BaseContainer class.
The @Metadata annotation specifies where in the XL Deploy repository the CI will be stored. In this case, the CI will be stored under the Infrastructure node. (see the XL Deploy Reference Manual for more information on the repository).
The restartYakServers() method annotated with @Contributor is invoked when any deployment takes place (also deployments that may not necessarily contain an instance of the YakServer class). The method serversRequiringRestart() searches for any YakServer instances that are present in the deployment and that requires a restart. For each of these YakServer instances, a StartYakServerStep and StopYakServerStep is added to the plan.

When the restartYakServers method is invoked, the deltas parameter contains operations for both yakfile CIs. If either of the yakfile CIs was an instance of RestartRequiringDeployedYakFile, a start step would be added to the deployment plan.

Deployed: DeployedYakFile

The DeployedYakFile represents a YakFile deployed to a YakServer, as reflected in the class definition. The class extends the built-in BaseDeployed class.

package com.xebialabs.deployit.plugin.test.yak.ci;

// imports omitted...

public class DeployedYakFile extends BaseDeployedArtifact<YakFile, YakServer> {

   @Modify
   @Destroy
   public void stop(DeploymentPlanningContext result) {
     logger.info("Adding stop artifact");
     result.addStep(new StopDeployedYakFileStep(this));
   }

   @Create
   @Modify
   public void start(DeploymentPlanningContext result) {
     logger.info("Adding start artifact");
     result.addStep(new StartDeployedYakFileStep(this));
   }

   @Create
   public void deploy(DeploymentPlanningContext result) {
     logger.info("Adding deploy step");
     result.addStep(new DeployYakFileToServerStep(this));
   }

   @Modify
   public void upgrade(DeploymentPlanningContext result) {
     logger.info("Adding upgrade step");
     result.addStep(new UpgradeYakFileOnServerStep(this));
   }

   @Destroy
   public void destroy(DeploymentPlanningContext result) {
     logger.info("Adding undeploy step");
     result.addStep(new DeleteYakFileFromServerStep(this));
   }

   private static final Logger logger = LoggerFactory.getLogger(DeployedYakFile.class);

}

This class shows how to use the @Contributor to contribute steps to a deployment that includes a configured instance of the DeployedYakFile. Each annotated method annotated is invoked when the specified operation is present in the deployment for the YakFile.

In our sample deployment, yakfile1 already exists on the target container CI so a MODIFY delta will be present in the delta specification for this CI, causing the stop, start and upgrade methods to be invoked on the CI instance. Because yakfile2 is new, a CREATE delta will be present, causing the start, and deploy method to be invoked on the CI instance.

Step: StartYakServerStep

Steps are the actions that will be executed when the deployment plan is started.

package com.xebialabs.deployit.plugin.test.yak.step;

import com.xebialabs.deployit.plugin.api.flow.ExecutionContext;
import com.xebialabs.deployit.plugin.api.flow.Step;
import com.xebialabs.deployit.plugin.api.flow.StepExitCode;
import com.xebialabs.deployit.plugin.test.yak.ci.YakServer;

@SuppressWarnings("serial")
public class StartYakServerStep implements Step {

   private YakServer server;

   public StartYakServerStep(YakServer server) {
     this.server = server;
   }

   @Override
   public String getDescription() {
     return "Starting " + server;
   }

   @Override
   public StepExitCode execute(ExecutionContext ctx) throws Exception {
     return StepExitCode.SUCCESS;
   }


   public YakServer getServer() {
     return server;
   }

   @Override
   public int getOrder() {
     return 90;
   }
}