Preface

This document describes the functionality provided by the Generic Model plugin.

See the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

Deployit supports a number of middleware platforms. Sometimes, though, it is necessary to extend Deployit with new middleware support. The Generic Model plugin provides a way to do this, without having to write Java code. Instead, using Deployit's flexible type system and the base CIs from the Generic Model plugin, new CIs can be defined by writing XML and providing scripts for functionality.

Several of Deployit's standard plugins are also built on top of the Generic Model plugin.

Features

• Define custom containers
  • Stop, start, restart capabilities
• Define and copy custom artifacts to a custom container
• Define, copy and execute custom scripts on a custom container
• Define resources to be processed by a template and copied to a custom container
• Flexible templating engine

Requirements

The plugin requires:

• Deployit: version 3.5+

Plugin Concepts

The Generic Model plugin provides several CIs that can be used as base classes for creating Deployit extensions. There are base CIs for each of Deployit's CI types (deployables, deployeds and containers). A typical usage scenario is to create custom, synthetic CIs (based on one of the provided CIs) and using it to invoke the required behavior (scripts) in a deployment plan.

Container

A Container is a topology CI and models middleware in your infrastructure. This would typically be used to model middleware for Deployit does not have out of the box support or that is custom to your environment. The other CIs in the plugin can be deployed to (subclasses of) the container. The behavior of the container in a deployment is configured by specifying scripts to be executed when it is started, stopped or restarted. Deployit will invoke these scripts as needed.

Copied Artifact

A CopiedArtifact is an artifact as copied over to a Container. It manages the copying of any generic artifact (File, Folder, Archive, Resource) in the deployment package to the container. It is possible to indicate that this copied artifact requires a container restart.

Executed Script

An ExecutedScript encapsulates a script that is executed on a generic container. The script is processed by the templating engine (see below) before being copied to the target container. The behavior of the script is configured by specifying scripts to be executed when it is deployed, upgraded or undeployed.

Processed Template

A ProcessedTemplate is a Freemarker template that is processed by the templating engine (see below), then copied to a Container.

Templating

When defining and using CIs with the Generic Model plugin, the need arises to use variables in certain CI properties and scripts. The most obvious use is to include properties from the deployment itself, such as the names or locations of files in the deployment package. Deployit uses the Freemarker templating engine for this.

When performing a deployment using the Generic Model plugin, all CIs and scripts are processed in Freemarker. This means that placeholders can be used in CI properties and scripts to make them more flexible. Freemarker resolves placeholders using a context, a set of objects defining the template's environment. This context depends on the type of CI being deployed.

For deployed CIs, the context deployed refers to the current CI instance. For example:

<type type="tc.DeployedDataSource" extends="generic.ProcessedTemplate" deployable-type="tc.DataSource"
      container-type="tc.Server">
    ...
    <property name="targetFile" default="${deployed.name}-ds.xml" hidden="true"/>
    ...
</type>

For container CIs, the context container refers to the current container instance. For example:

<type type="tc.Server" extends="generic.Container">
    <property name="home" default="/tmp/tomcat"/>
    <property name="targetDirectory" default="${container.home}/webapps" hidden="true"/>
</type>

A special case is when referring to an artifact in the placeholder. For example, when deploying a CI representing a WAR file, the following placeholder can be used to refer to that file (assuming there is a file property on the deployable):

${deployed.deployable.file}

In this case, Deployit will copy the referred artifact to the target container so that the file is available to the executing script. A script containing a command like the following would therefore copy the file represented by the deployable to it's installation path on the remote machine:

cp ${deployed.deployable.file} /install/path

Using the deployables and deployeds

Deployable vs. Container Table

The following table describes which deployable / container combinations are possible. Note that the CIs can only be targeted to containers derived from generic container.

Deployed Actions Table

The following table describes the effect a deployed has on its container.

Sample Usage Scenario - Deploying a new middleware platform

This section describes an example of using the Generic Model plugin to implement support for a simple middleware platform. Deployment to this platform is done by simply copying a WAR archive to the right directory on the container. Resources are created by copying configuration files into the container's configuration directory. The Tomcat application server works in a very similar manner.

By defining a container and several other CIs based on CIs from the Generic Model plugin, it is possible to add support for deploying to this platform to Deployit.

Defining the Container

To use any of the CIs in the Generic Model plugin, they need to be targeted to a Container. This snippet shows how to define a generic container as a synthetic type:

<type type="tc.Server" extends="generic.Container">
    <property name="home" default="/tmp/tomcat"/>
</type>

<type type="tc.UnmanagedServer" extends="tc.Server">
    <property name="startScript" default="tc/start.sh" hidden="true"/>
    <property name="stopScript" default="tc/stop.sh" hidden="true"/>
    <property name="restartScript" default="tc/restart.sh" hidden="true"/>
</type>

Note that the tc.UnmanagedServer CI defines a start, stop and restart script. Deployit Server reads these scripts from the classpath. When targetting a deployment to the tc.UnmanagedServer, Deployit will include steps executing the start, stop and restart scripts in appropriate places in the deployment plan.

Defining a Configuration File

The following snippet defines a CI based on the CopiedArtifact. The tc.DeployedFile CI can be targeted to the tc.Server. The target directory is specified as a hidden property. Note the placeholder syntax used here.

<type type="tc.DeployedFile" extends="generic.CopiedArtifact" deployable-type="tc.File"
      container-type="tc.Server">
    <generate-deployable type="tc.File" extends="generic.File"/>
    <property name="targetDirectory" default="${deployed.container.home}/conf" hidden="true"/>
</type>

Using the above snippet, it is possible to create a package with a tc.File deployable and deploy it to an environment containing a tc.UnmanagedServer. This will result in a tc.DeployedFile deployed.

Defining a WAR

To deploy a WAR file to the tc.Server, one possibility is to define a tc.DeployedWar CI that extends the ExecutedScript. The tc.DeployedWar CI is generated when deploying a jee.War to the tc.Server CI. This is what the XML looks like:

<type type="tc.DeployedWar" extends="generic.ExecutedScript" deployable-type="jee.War"
      container-type="tc.Server">
    <generate-deployable type="tc.War" extends="jee.War"/>
    <property name="createScript" default="tc/install-war" hidden="true"/>
    <property name="modifyScript" default="tc/reinstall-war" hidden="true" required="false"/>
    <property name="destroyScript" default="tc/uninstall-war" hidden="true"/>
</type>

When performing an initial deployment, the create script, tc/install-war is executed on the target container. Inside the script, a reference to the file property is replaced by the actual archive. Note that the script files do not have an extension. Depending on the target platform, the extension sh (Unix) or cmd (Windows) is used.

Defining a Datasource

Configuration files can be deployed by creating a CI based on the ProcessedTemplate. By including a Resource in the package that is a Freemarker template, a configuration file can be generated during the deployment and copied to the container. This snippet defines such a CI, tc.DeployedDataSource:

<type type="tc.DeployedDataSource" extends="generic.ProcessedTemplate" deployable-type="tc.DataSource"
      container-type="tc.Server">
    <generate-deployable type="tc.DataSource" extends="generic.Resource"/>

    <property name="jdbcUrl"/>
    <property name="port" kind="integer"/>
    <property name="targetDirectory" default="${deployed.container.home}/webapps" hidden="true"/>
    <property name="targetFile" default="${deployed.name}-ds.xml" hidden="true"/>
    <property name="template" default="tc/datasource.ftl" hidden="true"/>
</type>

The template property specifies the Freemarker template file that Deployit Server reads from the classpath. The targetDirectory controls where the template is copied to. Inside the template, properties like jdbcUrl on the datasource can be used to produce a proper configuration file.