From ControlTier

Jump to: navigation, search

Requires Version: 3.4.4

Manage a JBoss server, with multiple instances and ear deployments. Organize a set of JBoss servers into a Site to manage as a group.

Before delving into ControlTier usage, be sure to read the How to use ControlTier.

Also see the Using Libraries document for some getting-started instructions.



The JBoss Library provides Types for the following purposes:

These Types are designed with the following object composition model:

JBoss Library Composition Model

A single JBossServer object represents an instance of the running JBoss server. A JBossServer object depends on a JBossZip package object to hold the JBoss server software for automatic deployment. JBossServer can also use many ear objects to deploy a enterprise application to the server.

When managing a set of multiple JBossServer objects, you should use a Site object.


Works with JBoss 4.0.3SP1 and 4.0.5.GA. The particular version should be specified in the JBossZip object's "version" property.


Development Process

The following sections will guide you in developing your JBoss management model by use of the Types defined in this library.

Use one or more project.xml files to manage the model definitions, and use a ProjectBuilder object to load and operate on the model.


The JBoss Library provides several Types that can be used for managing a JBoss server and its related enterprise-applications and configurations in various ways. The parts of this section will guide you to the appropriate Types to use for each particular purpose.

These sections are ordered in a way that should let you start simply and move on to more advanced usages. If you have already created some management components you will probably skip to the section you are interested in.

Manage a JBoss server instance

Define a JBossServer object to manage a JBoss server. The JBossServer type manages a single JBoss server instance.

Deploy EAR packages to a JBoss server

After defining and uploading an ear object (see below), add the ear as a child-dependency of the JBossServer object. The JBossServer type allows zero or more ear dependencies so that any amount of ears can be managed by a single jboss server instance.

Upload Packages

Upload the JBossZip

First you should define a JBossZip Object, and upload the package definition. The JBossZip package object holds the JBoss server software in a zip file, and is used by JBossZip.

module JBoss Distribution support. If the version listed is not one of the desired jboss versions, see Package Distribution Integration

Upload an ear

Next you should define an ear for use by JBossServer.

If you want to build a ear package using a Builder, continue to the next section.

Build ear packages to deploy to the server

Any Builder can be used to produce an ear package object. See the Use Builder Document for the generic instructions for doing software Builds using the Builder type.

Specifically if your build process produces an ear file, you should configure your Builder with the following Import Attributes:

More information about Builder Settings are here: Builder Settings and Attributes.

Build software with Ant that depends on JBoss

Use a JBossAntBuilder to use Ant to build an ear. This will allow your Ant-based build script to use the JBoss dependency to produce a ear.

Manage multiple JBoss servers

Define a Site to manage JBoss servers as a group. This Site also dispatches management commands to its children. You will configure the Site to have every JBoss server instance as a child.

Generate Configuration

Integrate Databases

JBoss supports datasource xml configuration within the server instance deploy (${resource.attribute.jboss_basedir}/deploy) directory. This xml configuration can be auto generated as part of the standard Configure command. This configuration is supported by additional database dependencies modeled as child resource(s) of the jboss server instance. The Overview section refers to a diagram describing optional Rdb and RdbSchema database dependencies.

Define JBossServer database dependencies to configure datasources.


Test the deployment: ctl -p MyProject -t JBossServer -r test -c Deploy


The Types below from the JBoss Library (and some from the Core Library) are designed to compose in the fashion described in the #Overview. When using these types, it is useful to reference the Usage section.


A jboss deployment.

Sample Definition

From JBossServer/objects/sample.xml, we have used the first example values for the installRoot and basedir properties, and we have defined some settings to configure the ports that JBoss will run on along with some java related options. Additionally this is deployed to a Node named "centos45.local".

After saving this file, load this model:


ctl -p MyProject -m ProjectBuilder -c load-resources -- -filename JBossServer/objects/sample.xml
Note: To deploy a pre-defined "ear" archive, you should add a <resource> entry to specify it, inside the <resources> section:

<resource type="JBossEar" name="my-app-1.0.ear"/>

Note: This JBoss server instance is targeted to be deployed to a Node called "centos45.local" which will most likely differ and result in an error indicating a non existent object. Change the reference to this Node resource name to one that equates with your project:
        <resource type="Node" name="centos45.local"/>

Continue to the next step:


You need also to decide on the "Install Root" of the JBoss Server install and the "Base Directory" of the server instance. These are the paths where the JBoss zip will be installed and server instance will reside respectively. Examples:


To define the JBossServer object, we must first make note of some configuration that we may want to apply to the server definition.

This is the list of Setting types associated with the JBossServer type. We can create an object for each type, and the value of that setting object will be used as described below. The Default column shows the value that is used when no explicit Setting is configured.



Zip archive of the JBoss distribution

Since the JBossServer implementation supports multiple releases, it is important to be precise about which JBoss version is in use. The JBossZip package type represents the zip package containing the JBoss software, and we must define a package for the appropriate JBoss version that we want to use.

Here is a list of a few supported sourceForge versions (for comprehensive ControlTier version 3.4 list, see: module JBoss Distribution support ):

When creating your definition below, make note of the specific version (e.g. "4.0.5.GA").

Define the project.xml for the jboss package. It is the convention to name the project file exactly as the package file, with an added ".xml" extension. For the "jboss-4.0.5.GA.zip" file, this project file would be named "jboss-4.0.5.GA.zip.xml".

A sample is provided in the JBossZip module: JBossZip/objects/sample.xml'

After downloading, upload your jboss-4.0.5.GA.zip file using this command:


ctl -p MyProject -m JBossZip -c upload -- -filename jboss-4.0.5.GA.zip -xml JBossZip/objects/sample.xml

This uploads the jboss-4.0.5.GA.zip file to the package repository (WebDAV), and defines the package object in the server.


An ear package targeted for a JBoss Server

If your ear deployment is not produced by the Builder, you should define it via another project.xml file such as this example


ctl -p MyProject -m JBossEar -c upload -- -filename HelloWorld- -xml JBossEar/objects/sample.xml


Centralized management for a set of JBoss server instances.

Define the Site object that ties the JBossServer objects into a single manageable component, ensuring all objects are deployed to the same node (or set of nodes).


ctl -p MyProject -m ProjectBuilder -c load-resources -- -filename JBossServer/objects/sample-site.xml
[anthony@centos52 ~]$ ctl-project -p MyProject -a install
ctl -p MyProject -t Site -r test -c Deploy


Both Rdb and RdbSchema configuration are needed in order to support automated datasource configuration. Rdb object(s) represent the dependent database server itself, while RdbSchema object(s) represent a schema associated with a specific database server. Together, this hierarchical set of objects is sufficient for the JBoss server instance to generate datasource configuration within its deploy directory.


Description: abstract respresentation of a database server


Description: abstract respresentation of a database schema

Sample Definition

To define the JBossServer database dependencies, rdb and rdbschema objects are configured.

This sample shows a simple Rdb (which the JBossServer object depends on) and RdbSchema object. In this case the JBossServer depends on the Rdb object and the Rdb object depends on the RdbSchema object. Therefore the JBossServer directly depends on Rdb object(s) and indirectly depends on RdbSchema object(s).

Add Rdb Dependency to JBossServer

The intent is to modify your previous JBossServer object recently uploaded into the model so that it can refer to these new rdb based dependencies. The following is a partial diff highlighting a small change of your original JBossServer/objects/sample.xml previously loaded showing the newly introduced Rdb object referenced by the JBossServer object:

charles-scotts-macbook-pro-15:objects demo$ diff -u sample.xml sample-withRdb.xml 
--- sample.xml	2009-05-26 13:10:33.000000000 -0700
+++ sample-withRdb.xml	2009-05-26 13:12:17.000000000 -0700
@@ -38,6 +38,9 @@
          <!-- override the default behavior of selecting the "ports-default" svc binding configuration -->
          <resource type="JBossPortConfig" name="test"/>
+         <!-- generic database dependency for automated datasource configuration -->
+         <resource type="Rdb" name="test"/>
       <referrers replace="false">
          <resource type="Node" name="centos45.local"/>

Reload with Datasource Configuration

Load the database dependencies into the model:


ctl -p MyProject -m ProjectBuilder -c load-resources -- -filename Rdb/objects/sample.xml

Re-load JBoss sample.xml with rdb change

ctl -p MyProject -m ProjectBuilder -c load-resources -- -filename JBossServer/objects/sample.xml


JBoss application Ant builder

Sample Definition

Configure a JBossAntBuilder using this command:


ctl -p MyProject -m ProjectBuilder -c load-resources -- -filename JBossAntBuilder/objects/sample.xml

Package Distribution Integration


The JBoss Library supports various versions of the JBoss server. The requirement for a new JBoss distribution is to integrate templates to support the following:

  * run.conf
  * jboss_service.xml
  * bindings.xml (service bindings for port management)
  * datasource configuration (optional)

These templates are tied to the JBoss Server distribution available from SourceForge

The procedure for adding JBoss distribution support to the JBossServer module will involve:


In order to demonstrate the process of integrating support for a new jboss distribution, the following assumptions are made (adjust accordingly where indicated):

-bash-3.00$ which svn
$HOME/test/jdk.1.5.0_15/bin/java -version
java version "1.5.0_12"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_15-b04)
Java HotSpot(TM) Client VM (build 1.5.0_15-b04, mixed mode, sharing)

Create the ProjectBuilder elements instance

Checkout the elements source from moduleforge's 3.4 support branch

mkdir -p $CTIER_ROOT/src
cd $CTIER_ROOT/src
svn checkout https://moduleforge.svn.sourceforge.net/svnroot/moduleforge/controltier/branches/controltier-3-4-support/elements

Register the elements ProjectBuilder instance

ctl -p demo -t ProjectBuilder -r elements -c Register -- -installroot '${env.CTIER_ROOT}/target/elements' -basedir '${env.CTIER_ROOT}/src/elements' -install

Import the JBoss zip distribution package

Download the distribution from sourceforge into the elements objects directory

cd $CTIER_ROOT/src/elements/objects
wget http://superb-west.dl.sourceforge.net/sourceforge/jboss/jboss-4.2.2.GA.zip

Copy the JBossZip sample.xml

cp  $CTIER_ROOT/src/elements/modules/JBossZip/objects/sample.xml jboss-4.2.2.GA.zip.xml

Adjust this xml file for the new version by changing references to 4.0.5.GA to the new one (e.g. 4.2.2.GA). The following diff describes the necessary changes:

[centos-52.local:objects chuck$] diff -u  $CTIER_ROOT/src/elements/modules/JBossZip/objects/sample.xml jboss-4.2.2.GA.zip.xml
--- $CTIER_ROOT/src/elements/modules/JBossZip/objects/sample.xml	2009-06-09 07:32:46.000000000 -0700
+++ jboss-4.2.2.GA.zip.xml	2009-06-22 11:33:44.000000000 -0700
@@ -6,16 +6,16 @@
    <!-- JBoss platform distribution package -->
    <package type="JBossZip"
-         name="jboss-4.0.5.GA.zip"
-         version="4.0.5.GA"
-         release="4.0.5.GA"
+         name="jboss-4.2.2.GA.zip"
+         version="4.2.2.GA"
+         release="4.2.2.GA"
-         filename="jboss-4.0.5.GA.zip"
+         filename="jboss-4.2.2.GA.zip"
-         base="jboss-4.0.5.GA"
+         base="jboss-4.2.2.GA"
-         repoUrl="/JBossZip/zips/jboss-4.0.5.GA.zip"
+         repoUrl="/JBossZip/zips/jboss-4.2.2.GA.zip"

Upload the jboss zip into the project

ctl -p demo -m zip -c upload -- -xml jboss-4.2.2.GA.zip.xml -filename jboss-4.2.2.GA.zip

Add support to the JBossServer module

Within the JBossServer module, create the versioned template directories

cd $CTIER_ROOT/src/elements/modules/JBossServer/templates
mkdir -p jboss-4.2.2.GA/ds
mkdir -p jboss-4.2.2.GA/server/default/conf

Configure the jboss-service and bindings templates

Extract the sample-bindings and jboss-service xml files from the distribution

unzip $CTIER_ROOT/src/elements/objects/jboss-4.2.2.GA.zip  jboss-4.2.2.GA/docs/examples/binding-manager/sample-bindings.xml
unzip  $CTIER_ROOT/src/elements/objects/jboss-4.2.2.GA.zip  jboss-4.2.2.GA/server/default/conf/jboss-service.xml

Rename these files as templates

mv jboss-4.2.2.GA/docs/examples/binding-manager/sample-bindings.xml jboss-4.2.2.GA/server/default/conf/bindings.xml.template
mv jboss-4.2.2.GA/server/default/conf/jboss-service.xml jboss-4.2.2.GA/server/default/conf/jboss-service.xml.template
rm -rf jboss-4.2.2.GA/docs

Enable service binding configuration in the jboss-service.xml template by uncommenting the ServiceBindingManager mbean block

   <mbean code="org.jboss.services.binding.ServiceBindingManager"
     <attribute name="ServerName">ports-01</attribute>
     <attribute name="StoreURL">${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml</attribute>
     <attribute name="StoreFactoryClassName">

templatatize the ServerName and StoreURL parameters

     <attribute name="ServerName">@PortConfig@</attribute>
     <attribute name="StoreURL">${jboss.home.url}/server/@BaseDirName@/conf/bindings.xml</attribute>

The following is a diff of the original jboss-service.xml and the new jboss-service.xml.template summarizing these changes:

[centos-52.local:objects chuck$] diff -u jboss-4.2.2.GA/server/default/conf/jboss-service.xml jboss-4.2.2.GA/server/default/conf/jboss-service.xml.template 
--- jboss-4.2.2.GA/server/default/conf/jboss-service.xml        2007-10-22 11:43:32.000000000 -0700
+++ jboss-4.2.2.GA/server/default/conf/jboss-service.xml.template       2009-06-18 16:08:50.000000000 -0700
@@ -187,16 +187,16 @@
       | during initialization that specifies how to connect to the bindings store.
       | StoreFactory: The org.jboss.services.binding.ServicesStoreFactory interface
       | implementation to create to obtain the ServicesStore instance.
+   -->
    <mbean code="org.jboss.services.binding.ServiceBindingManager"
-     <attribute name="ServerName">ports-01</attribute>
-     <attribute name="StoreURL">${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml</attribute>
+     <attribute name="ServerName">@PortConfig@</attribute>
+     <attribute name="StoreURL">${jboss.home.url}/server/@BaseDirName@/conf/bindings.xml</attribute>
      <attribute name="StoreFactoryClassName">
-   -->

Configure the run.conf template

cat > jboss-4.2.2.GA/server/default/conf/run.conf.template <<!
if [ "x$JAVA_OPTS" = "x" ]; then

Configure datasource templates

Datasource templates are based on the JBoss Solid DB datasource reference

Hypersonic datasource template

cat > jboss-4.2.2.GA/ds/hsqldb-ds.xml.template <<!
<?xml version="1.0" encoding="UTF-8"?>


      <!-- The jndi name of the DataSource, it is prefixed with java:/ -->
      <!-- Datasources are not available outside the virtual machine -->


      <!-- The driver class -->

      <!-- The login and password -->

      <!-- The minimum connections in a pool/sub-pool. Pools are lazily constructed on first use -->

      <!-- The maximum connections in a pool/sub-pool -->

      <!-- The time before an unused connection is destroyed -->

     <!-- HSQL DB benefits from prepared statement caching -->

      <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
         <type-mapping>Hypersonic SQL</type-mapping>


   <!-- This mbean can be used when using in process persistent db -->
   <mbean code="org.jboss.jdbc.HypersonicDatabase" 
     <attribute name="Database">localDB</attribute>
     <attribute name="InProcessMode">true</attribute>

Solid datasource template

cat > jboss-4.2.2.GA/ds/soliddb-ds.xml.template <<!
<?xml version="1.0" encoding="UTF-8"?>


      <!-- The jndi name of the DataSource, it is prefixed with java:/ -->
      <!-- Datasources are not available outside the virtual machine -->


      <!-- The driver class -->

      <!-- The login and password -->

      <!-- The minimum connections in a pool/sub-pool. Pools are lazily constructed on first use -->

      <!-- The maximum connections in a pool/sub-pool -->

      <!-- The time before an unused connection is destroyed -->

      <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->



Update the project with type and object changes

Build, Upload, and Install the new JBossServer module

Use ProjectBuilder to rebuild the JBossServer module

ctl -p demo -t ProjectBuilder -r elements -c build-type -- -type JBossServer -upload

Create and Load the JBossServer ProjectXML file

Copy the JBossServer sample.xml

cp  $CTIER_ROOT/src/elements/modules/JBossServer/objects/sample.xml $CTIER_ROOT/src/elements/objects/jbossServer.xml

Adjust this xml file for version 4.2.2.GA by changing package references from 4.0.5.GA to 4.2.2.GA and the local Node name that this service will be deployed to, the following diff highlights necessary changes

[centos52.local objects chuck]$ diff -u  $CTIER_ROOT/src/elements/modules/JBossServer/objects/sample.xml $CTIER_ROOT/src/elements/objects/jbossServer.xml
charles-scotts-power-mac-g5:objects chuck$ diff -u /Users/chuck/ctier/src/elements/modules/JBossServer/objects/sample.xml jbossServer.xml 
--- /Users/chuck/ctier/src/elements/modules/JBossServer/objects/sample.xml	2009-06-09 07:32:43.000000000 -0700
+++ /Users/chuck/ctier/src/elements/objects/jbossServer.xml	2009-06-22 17:44:25.000000000 -0700
@@ -18,13 +18,13 @@
    <!-- configure the jboss test instance to be installed relative to the effective user's home directory
    <deployment type="JBossServer" name="test" 
-               basedir="${user.home}/jboss-4.0.5.GA/server/test" 
-               installRoot="${user.home}/jboss-4.0.5.GA" 
+               basedir="${user.home}/jboss-4.2.2.GA/server/test" 
+               installRoot="${user.home}/jboss-4.2.2.GA" 
                description="test jboss service instance" startuprank="1">
       <resources replace="true">
          <!-- ensure the JBoss platform distribution has been installed -->
-         <resource type="JBossZip" name="jboss-4.0.5.GA.zip"/>
+         <resource type="JBossZip" name="jboss-4.2.2.GA.zip"/>
          <!-- path to JAVA_HOME -->
          <resource type="JBossJavaHome" name="test"/>
@@ -40,7 +40,7 @@
       <referrers replace="false">
-         <resource type="Node" name="centos45.local"/>
+         <resource type="Node" name="centos52.local"/>

Load the jbossServer ProjectXML file and sync back to the local system

ctl -p demo -t ProjectBuilder -r elements -c load-resources -- -filename $CTIER_ROOT/src/elements/objects/jbossServer.xml  
ctl-project -p demo -a install

Deploy and Verify the test jboss service

Deploy the JBoss test service instance

ctl -p demo -t JBossServer -r test -c Deploy

Verify test service is listening to port 8180

[centos-52.local:objects chuck$]netstat -an |grep 8180
tcp        0      0    *                   LISTEN      

Submit the JBoss Library changes

Generate the compressed unified diff file using svn diff

cd $CTIER_ROOT/src/elements/modules/JBossServer/templates
svn diff -x -u  > jboss-4.2.2.GA.diff
gzip jboss-4.2.2.GA.diff

Upload the compressed diff

Setting up an JBoss Cluster

Steps to configure a JBoss cluster

Personal tools