JBoss Application Server 7+ Plugin Manual

Preface

This document describes the functionality provided by the JBoss Domain (JBoss AS 7.1+, JBoss EAP 6) plugin.

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

Overview

The JBoss Domain plugin is an XL Deploy plugin that adds the capability to manage deployments and resources on JBoss application server 7.1+ or JBoss EAP 6. The plugin has the capability of managing application artifacts, datasource and other JMS resources via the JBoss Cli, and can easily be extended to support more deployment options or management of new artifacts/resources on JBoss AS.

Features

• Domain and Standalone mode support
• Deployment of application artifacts
  • Enterprise application (EAR)
  • Web application (WAR)
• Deployment of resources
  • Datasource including XA Datasource
  • JMS Queue
  • JMS Topic
• Discovery of Profiles and ServerGroups in Domain

Requirements

• XL Deploy requirements

  • XL Deploy: version 4.5.0+

• Infrastructural requirements

  • JBoss AS versions: 7.1+
  • JBoss EAP versions: 6.2.0, 6.3.0
  • WildFly: 8.0.x, 8.1.x
  • User credentials for accessing the Host and JBoss CLI.

Usage in Deployment Packages

The plugin works with XL Deploy's standard deployment package DAR format. Please see the Packaging Manual for more details about the DAR format and the ways to compose one.

The following is a sample deployit-manifest.xml file that can be used to create a JBoss AS specific deployment package. It contains declarations for an Ear, a datasource and a couple of JMS resources.

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="1.0" application="SampleApp">
  <deployables>
    <jbossdm.QueueSpec name="testQueue">
      <jndiName>java:jboss/jms/testQueue</jndiName>
    </jbossdm.QueueSpec>
    <jbossdm.TopicSpec name="testTopic">
      <jndiName>jms/testTopic</jndiName>
    </jbossdm.TopicSpec>
    <jbossdm.DataSourceSpec name="testDatasource">
      <jndiName>java:jboss/jdbc/sampleDatasource</jndiName>
      <driverName>mysql</driverName>
      <username>{{DATABASE_USERNAME}}</username>
      <password>{{DATABASE_PASSWORD}}</password>
      <connectionUrl>jdbc:mysql://localhost/test</connectionUrl>
      <connectionProperties />
    </jbossdm.DataSourceSpec>
    <jee.Ear name="PetClinic" file="PetClinic/PetClinic.ear">
      <scanPlaceholders>false</scanPlaceholders>
    </jee.Ear>
  </deployables>
</udm.DeploymentPackage>

Using the deployables and deployeds

The following table describes which deployable/container combinations are possible.

Deployable vs. Container table

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

Deployed Actions Table

Deploying applications

Note that the plugin uses the JBoss CLI to (un)install artifacts and resources. As such, the plugin assumes that the JBoss Domain or Standalone server has already been started. The plugin does not support the starting of the domain or standalone server prior to a deployment.

Standalone Mode

Artifacts (war, ear) and resources (datasources, queues, topics, etc) can be targeted to a StandaloneServer.

Domain Mode

Artifacts (war, ear) can be targeted to either a Domain or ServerGroup. When targeted to a domain, the artifacts are (un)installed on all server groups defined for the domain. For specific targeting of artifacts to certain server groups, you can define the server groups in your environment.

Resources (datasources, queues, topics, etc) can be targeted to either a Domain or Profile. When targeted to a domain, the resources are (un)installed in the "default" profile. For specific targeting of resources to certain profiles, you can define the profiles in your environment.

Discovery

The plugin supports the discovery of Profiles and Server Groups in a Domain.

Here is an example CLI script which discovers a sample Domain:

host = repository.create(factory.configurationItem('Infrastructure/jboss-host', 'overthere.SshHost',
    {'connectionType':'SFTP','address': 'jboss-7','username': 'root','password':'centos','os':'UNIX'}))
jboss = factory.configurationItem('Infrastructure/jboss-host/jboss-domain', 'jbossdm.Domain',
    {'home':'/opt/jboss/7', 'host':'Infrastructure/jboss-host', 'username':"jbossAdmin", "password":"jboss"})

taskId = deployit.createDiscoveryTask(jboss)
deployit.startTaskAndWait(taskId)
cis = deployit.retrieveDiscoveryResults(taskId)
deployit.print(cis)

#discovery just discovers the topology and keeps the configuration items in memory. Save them in the XL Deploy repository
repository.create(cis)

Few things to note about the above discovery example:

• JBoss Domain has a containment relation with a Host (created under a Host), so the server id has been kept as 'Infrastructure/jboss-host/jboss-domain'

Extension points

The plugin is designed to be extended through XL Deploy's Plugin API type system and jython. The plugin wraps the JBoss CLI with a jython runtime environment, thus allowing extenders to interact with JBoss and XL Deploy from the script. Note that the jython script is executed on the XL Deploy Server itself and has full access to the following XL Deploy objects :

• deployed: The current deployed object on which the operation has been triggered.
• step: The step object that the script is being executed from. Exposes an overthere remote connection for file manipulation and a method to execute JBoss CLI commands.
• container: The container object to which the deployed is targeted to.
• delta: The delta specification that lead to the script being executed.
• deployedApplication: The entire deployed application.

The plugin associates Create, Modify, Destroy, Noop and Inspect operations received from XL Deploy with jython scripts that need to be executed for the specific operation to be performed.

There also exists an advanced method to extend the plugin, but the implementation of this form of extension needs to be written in the Java programming language and consists of writing so-called Deployed contributors, PlanPreProcessors and Contributors.

Please refer to the Customization Manual for a detailed explanation of the type system and advanced methods of customization of plugins. Also refer to the Overthere documentation for working with remote files.

Extending the plugin to support JDBC Driver deployment

In this example we will deploy a JDBC driver jar to a Domain or StandaloneServer as a module and register the driver with JBoss datasources subsystem.

Define the deployed and deployable to represent a JDBC Driver

The following synthetic.xml snippet shows the definition of the JDBC Driver deployed. The deployed will be targeted to a Domain or a StandaloneServer. Please refer to the CI reference section of this document to understand the interfaces and class hierarchy of these types.

<type type="jbossdm.JdbcDriverModule" extends="jbossdm.CliManagedDeployedArtifact"
      deployable-type="jbossdm.JdbcDriver" container-type="jbossdm.CliManagingContainer">
  <generate-deployable type="jbossdm.JdbcDriver" extends="udm.BaseDeployableArchiveArtifact">

  <property name="driverName"/>
  <property name="driverModuleName"/>
  <property name="driverXaDatasourceClassName/>

  <!-- hidden properties to specify the jython scripts to execute for an operation -->
  <property name="createScript" default="jboss/dm/ds/create-jdbc-driver.py" hidden="true"/>
</type>

Defined the create-jdbc-driver.py

from com.xebialabs.overthere.util import OverthereUtils

#create module directory to copy jar and module.xml to
driverModuleName = deployed.getProperty("driverModuleName")
moduleRelPath = driverModuleName.replaceAll("\\.","/")
moduleAbsolutePath = "%s/modules/%s" % (container.getProperty("home"), moduleRelPath)
moduleDir = step.getRemoteConnection().getFile(moduleAbsolutePath);
moduleDir.mkdirs();
#upload jar
moduleJar = moduleDir.getFile(deployed.file.getName())
deployed.file.copyTo(moduleJar)

moduleXmlContent = """
 <?xml version="1.0" encoding="UTF-8"?>
 <module xmlns="urn:jboss:module:1.0" name="%s">
    <resources>
        <resource-root path="%s"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
      </dependencies>
 </module>
 """ % (deployed.getProperty("driverModuleName"), deployed.file.getName())

#create module.xml
moduleXml = moduleDir.getFile("module.xml")
OverthereUtils.write(moduleXlContent.getBytes(),moduleXml)

#register driver with the datasource subsystem
driverName = deployed.getProperty("driveName")
xaClassName = deployed.getProperty("driverXaDatasourceClassName")
cmd = '/subsystem=datasources/jdbc-driver=%s:add(driver-name="%s",driver-module-name="%s",driver-xa-datasource-class-name="%s")'      % (driverName, driverName, driverModuleName, xaClasName)
cmd = prependProfilePath(cmd) #prefix with profile if deploying to domain
executeCmd(cmd)  #used to execute a JBoss Cli command.

Extending the plugin with custom control task

The plugin has the capability to add control tasks to CliManagedDeployed or CliManagedContainer. The control task can be specified as a jython script that will be executed on the XL Deploy Server or as an OS shell script that will be run on the target host. The OS shell script is first processed with FreeMarker before being executed.

Creating a jython based control task to list JDBC drivers in a StandaloneServer

Synthetic.xml snippet

<type-modification type="jbossdm.StandaloneServer">
  <property name="listJdbcDriversPythonTaskScript" hidden="true" default="jboss/dm/container/list-jdbc-drivers.py"/>
  <!-- Note "PythonTaskScript" is appended to the method name to determine the script to run. -->
  <method name="listJdbcDrivers"/>
</type-modification>

list-jdbc-drivers.py snippet

drivers = executeCmd("/subsystem=datasources:installed-drivers-list")
logOutput(drivers)  #outputs to the step log

Start the StandaloneServer

Synthetic.xml snippet

<type-modification type="jbossdm.StandaloneServer">
  <property name="startShellTaskScript" hidden="true" default="jboss/dm/container/start-standalone"/>
  <!-- Note "ShellTaskScript" is appended to the method name to determine the script to run. -->
  <method name="start"/>
</type-modification>

start-standalone.sh snippet

nohup ${container.home}/bin/standalone.sh >>nohup.out 2>&1 &
sleep 2
echo background process to start standalone server executed.

Release notes

Version 4.5.2

Features

• [DEPL-8431] Fixed issue where special characters were not escaped when deploying without a daemon (introduced commandExecutionMode property on CLIBasedContainer)
  • Implemented command execution in non-daemon mode via jboss-cli file paramater

Bug fixes

• [DEPL-7782] Fixed issue where the jboss-cli step failed if the connection type was SFTP
• [DEPL-8347] Fixed issue where a deployed datasource with default pool data fails the connection test
• [DEPL-7750] Fixed issue where recovery file couldn't be written throwing a 'SshElevatedUserFile is not serializable' exception
• [DEPL-7937] Fixed error handling problem if Daemon is enabled

Version 4.5.1

Features

• [DEPL-6847] Add jboss-cli step primitive

Bug fixes

• [DEPL-7703] Cancelling or rolling back a deployment can give the wrong results in jbossdm plugin

Improvements

• [DEPL-5851] CliProcessOutputHandler should handle error lines
• [DEPL-6782] Datasources, jms resources and application names should not contain whitespace characters.

Version 4.5.0

Feature

• [DEPL-4895] - Support JBoss EAP 6.2.0, EAP 6.3.0
• [DEPL-5566] - Support Wildfly 8.0.0.Final, 8.1.0.Final

Version 4.0.1

Feature

• [DEPL-5524] - Support staging of artifacts

Bug fixes

• [DEPL-5665] - Deployit hangs when JBoss CLI terminates unexpectedly
• [DEPL-5666] - JBossDM Datasource attributes are truncated when value has spaces.

Improvements

• [DEPL-5664] - Show preview of JBoss DM steps in analyser
• [DEPL-5667] - Better propagation JBoss CLI errors and jython scripting errors to the user.

Version 4.0.0

Bug fixes

• [DEPL-5234] - jbossdm-plugin JAR is packaged twice in the distribution zip file
• [DEPL-5304] - A context root is required when deploying to JBoss DM

Improvements

• [DEPL-5225] - Update JBoss DM plugin documentation with manifest.xml example

Version 3.9.1

Bug fixes

• DEPLOYITPB-4950 contextRoot is a required parameter on jbossdm.WarModule
• DEPLOYITPB-4896 jbossdm-plugin distribution does not contain jython-standalone-2.5.1.jar
• DEPLOYITPB-4340 Exceptions that occur during execution of JBoss CLI command are masked

Version 3.9.0

Improvements

• [DEPLOYITPB-4430] - Added jbossdm.EjbJar type for EJB deployments.

Version 3.8.1

Bug fixes

• [DEPLOYITPB-3948] - Orders have not been configured correctly
• [DEPLOYITPB-4140] - Jboss DM plugin uses List as an asContainment property

Version 3.8.0

Improvements

• [DEPLOYITPB-2906] - Support JBoss 7+ and JBoss EAP 6+