Preface

This document describes the functionality provided by the JBoss application server (AS) plugin.

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

Overview

The JBoss plugin is a Deployit plugin that adds the capability to manage deployments and resources on JBoss application server. It works out of the box for deploying/ undeploying application artifacts, datasource and other JMS resources (see the Features section below) , and can easily be extended to support more deployment options or management of new artifacts/resources on JBoss AS.

Features

• Application artifacts
  • Enterprise application (EAR)
  • Web application (WAR)
• JBoss-specific artifacts:
  • Service Archive (SAR)
  • Resource Archive (RAR)
  • Hibernate Archive (HAR)
  • Aspect archive (AOP)
• Resources
  • Datasource
  • JMS Queue**
  • JMS Topic**
• Discovery

_{** While creating JMS resources like Queues and Topics for JBoss AS 6, only the jndi name is used for the creation purpose. Other properties like RedeliveryDelay, MaxDeliveryAttempts and so on are not used even when they have been defined on the CI (in synthetic.xml) and set. These properties are defined by editing the global server configuration, which can be found at "%JBOSS_HOME%/server/<configuration/deploy/hornetq/hornetq-jms.xml.}

Requirements

• Deployit requirements

  • Deployit: version 3.7+
  • JBoss AS versions: 4.x, 5.x and 6.x
  • Other Deployit Plugins: None

• Infrastructural requirements

  • User credentials for accessing the Host running the JBoss application Server.
  • JBoss installed as a service when running on Windows. See the JBoss Native guide for one possible method of installing JBoss as a service.

Usage in Deployment Packages

The plugin works with the standard deployment package of 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 MANIFEST.MF file that can be used to create a JBoss AS specific deployment package. It contain declarations for an Ear, a datasource and a couple of JMS resources.

Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: SampleApp
CI-Version: 1.0

Name: PetClinic-1.0.ear
CI-Name: PetClinic
CI-Type: jee.Ear

Name: testDatasource
CI-Type: jbossas.TransactionalDatasourceSpec
CI-jndiName: jdbc/sampleDatasource
CI-connectionUrl: jdbc:mysql://localhost/test
CI-driverClass: com.mysql.jdbc.Driver
CI-username: {{DATABASE_USERNAME}}
CI-password: {{DATABASE_PASSWORD}}

Name: testQueue
CI-Type: jbossas.QueueSpec
CI-jndiName: jms/testQueue

Name: testTopic
CI-Type: jbossas.TopicSpec
CI-jndiName: jms/testTopic

Name: testConfigFile.txt
CI-Name: testConfigFiles
CI-Type: jbossas.ConfigurationFile

Name: testConfigFolder
CI-Name: testConfigFolder
CI-Type: jbossas.ConfigurationFolder

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 it's container

Deployed Actions Table

Deploying applications

By default, Deployit deploys the application artifacts and resource specifications (datasource, queues, topics etc) to the 'deploy' directory in the server's configuration. So if the server configuration is set to 'default' (which is the default value of server name), the artifact is copied to ${JBOSS_HOME}/server/default/deploy. Also, the server is stopped before copying the artifact and then started again. But all these configurations can be customized to suit more specific scenarios.

Extension points

The JBoss plugin is designed to be extended through Deployit's Plugin API type system. Also, since the JBoss plugin is built on top of generic-plugin, support for new types can be added using the generic plugin patterns. Refer to Generic Plugin Manual for more details. Also, refer to Customization Manual for an explanation of the type system.

The next section describes extensibility by examples:

Extending the JBoss Plugin

Making existing propery hidden/visible or changing the default value

The following synthetic.xml snippet shows how the restartRequired property can be made visible and the targetDirectory property can be given a default value of '/home/deployer/install-files' for jbossas.EarModule.

<type-modification type="jbossas.EarModule">
  <!-- make it visible so that I can control whether to restart a Server or not from UI-->
  <property name="restartRequired" kind="boolean" default="true" hidden="false"/>

  <!-- custom deploy directory for my jboss applications -->
  <property name="targetDirectory" default="/home/deployer/install-files" hidden="true"/>
</type-modification>

Adding a new property to a deployed/deployable

The following synthetic.xml snippet shows how a new property 'blocking-timeout-millis' can be added to jbossas.TransactionalDatasource

<type-modification type="jbossas.TransactionalDatasource">
    <!-- adding new property -->
    <property name="blockingTimeoutMillis" kind="integer" default="3000" description="maximum time in milliseconds to block 
    while waiting for a connection before throwing an exception"/>
</type-modification>    

Note that while adding a new property in JBoss plugin, the configuration property must be specified in lower camel-case with the hyphens removed from it. Thus the property
'blocking-timeout-millis' has to be specified as blockingTimeoutMillis. Similary 'idle-timeout-minutes' becomes idleTimeoutMinutes in synthetic.xml.

Adding a new type

New types can be added in JBoss plugin using the Generic Plugin patterns. For example, the following synthetic.xml snippet defines a new type jbossas.EjbJarModule

<type type="jbossas.EjbJarModule" extends="generic.CopiedArtifact" deployable-type="jee.EjbJar" 
                                     container-type="jbossas.BaseServer">
    <generate-deployable type="jbossas.EjbJar" extends="jee.EjbJar"/>
    <property name="targetDirectory" default="${deployed.container.home}/server/${deployed.container.serverName}/deploy"
                        hidden="true"/>
    <property name="targetFile" default="${deployed.deployable.name}.jar" hidden="true"/>
    <property name="createOrder" kind="integer" default="50" hidden="true"/>
    <property name="destroyOrder" kind="integer" default="40" hidden="true"/>
    <property name="restartRequired" kind="boolean" default="true" hidden="true"/>
</type>

Discovery

Once the JBoss server's home location and the host on which JBoss server is running are specified, the following properties can be discovered on a running JBoss server.

• JBoss version
• Control port
• Http port
• Ajp port

Here is an example CLI script which discovers a sample JBoss server:

host = repository.create(factory.configurationItem('Infrastructure/jboss-51-host', 'overthere.SshHost',
    {'connectionType':'SFTP','address': 'jboss-51','username': 'root','password':'centos','os':'UNIX'}))
jboss = factory.configurationItem('Infrastructure/jboss-51-host/jboss-51', 'jbossas.ServerV5',
    {'home':'/opt/jboss/5.1.0.GA', 'host':'Infrastructure/jboss-51-host'})

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 Deployit repository
repository.create(cis)

Few things to note about the above discovery example:

• Hosts are created under the Infrastructure tree, so the host id has been kepts as 'Infrastructure/jboss-51-host'
• Host address can be the host IP address or the dns name defined for the host
• JBoss server has a containment relation with a Host (created under a Host), so the server id has been kept as 'Infrastructure/jboss-51-host/jboss-51'