Deployment on JBoss

Daniel Schulze

Introduction

The application deployment on JBoss is managed by the J2eeDeployer MBean. The J2eeDeployer is able to deploy ejb.jar packages, webapplication.war packages and j2ee application.ear packages. Furthermore he is able to deploy unpacked ejb.jar files for development purposes.

The deployment is url based, so it is possible to deploy from whatever source as long as there is a url handler for that source available in your environment. (ie. http://somehost/applications/app.ear or file:///home/user/development/myapp.ear)

J2EE Deployer

The J2eeDeployer currently provides 3 methods:

  • void deploy (URL) this method starts the deployment process for the application this URL points to. The URL can be a file: or a http:// or any other type of url your environment is capable to handle. In case of deploying a unpacked ejb.jar package the URL type is currently limited to file. The deployment of an already deployed application (the name of the app is significant) will result in an undeployment of this app followed by a redeployment.

  • void undeploy (URL or Application name) use this to undeploy an application. the parameter can be the URL that was used to deploy this application or just the name (application name = file name of the app package or directory name in case of unpacked) of the application.

  • boolean isDeployed (URL or Application name) use this method to ask for the state of an application. The argument follows the same rules as for the undeploy method.

These 3 methods can be used via the web interface of JBoss at port 8082 at the host JBoss is running on.

The AutoDeployer as helper

The AutoDeployer MBean is a helper for the J2eeDeployer to allow doing administration smoothly via drag and drop or to automate the redeployment in case of development. He observes the given directories for changes and calls the appropriate methods on the J2eeDeployer.

The AutoDeployer observes the timestamps of the application packages or the timestamp of the META-INF/ejb-jar.xml file in case of unpacked ejb.jar files.

The AutoDeployer is configured whether static by the MLET configuration or dynamic by adding urls to watch for in its web interface (port 8082 at the host JBoss is running on).

In its current version the AutoDeployer supports only local directories to observe.

To deploy an ejb, web or ear package simply drop it in one of the observed directories. To autodeploy an unpacked ejb application, add the base directory of that application (base directory = the directory which containes the META-INF directory) to the AutoDeployers observed urls.

Note: There is still a misbehavior when the autodeployer thread wins the race against the copy thread which modifies a package!

Creating J2EE applications

j2ee applications or .ear files are jar archives containing a collection of ejb, web, client, connector and/or other library packages. Currently JBoss only supports ejb, web and other library packages (client and connector packages are ignored if present).

Other Library packages are class packages that are needed by your application and are not provided by the j2ee runtime environment (ie: some xml tools)

This document will only describe the JBoss relevant stuff in creating j2ee packages for a detailed description of how to build such applications see the J2EE specification under chapter 8!

First create all ejb, war and library archives you want to put together to make up your application. Make sure that all dependencies are solved, means: all classes that are needed by your application must be contained in your application (besides the classes that made up the J2EE platform (java core, javax.transaction, javax.sql, javax.servlet ...). Its up to you to create an arbitrary directory structure for your application to make it easier to maintain. Once you ve created your structure and moved all files on their place you have to create a deployment descriptor. This file must reside in the <your_app_dir>/META-INF directory and must be named application.xml.

Figure 11.11. Example of application.xml file

 <application>
     <display-name>My Application</display-name>

      <module>
         <web>
            <web-uri>web-app.war</web-uri>
            <context-root>/myapp</context-root>
         </web>
      </module>

      <module>
         <ejb>ejb-app.jar</ejb>
      </module>
 </application>
		

This descriptor describes an application that contains a web application package (JSPs/Servlets/HTML) and an ejb application (EJBs). The web applications war package is located at the root of the .ear file and is named web-app.war. It will be deployed under the webcontext /myapp. The ejb package also resides in the applications root directory and is called ejb-app.jar.

Understanding the shared classloader architecture in JBoss

When an application in JBoss gets deployed, every module will get deployed by a separate container. Every container will get its own classloader - this means that a call from one module to an other must be an remote call and all parameters must be serialized, because the classes (even if they are loaded from the same physical file) are not compatible across container boundaries. To allow optimized interaction across container boundaries (local calls with parameter ... per reference) the classes that are involved in this communication must be loaded by the same classloader.

In JBoss we achieve this issue with the following classloader architecture:

On deployment one common classloader is created. This classloader will get all archives in its classpath that are referenced in MANIFEST.MF/Class-Path[1] entries of the each individual module contained in enclosing application. Figure 11.12. shows such an entry

When afterwards all modules become deployed in their containers, the classloaders created by these containers are all children of the common classloader.

Now on runtime the communication between modules across container boundaries can be optimized when the classes used for the communication are loaded by the common classloader.

To allow our previous mentioned simple example to make use of the optimization, we must provide the classes the web module needs to communicate with the ejb module in an separate third package, lets call it ejb-client.jar. This ejb-client.jar archive contains the remote interfaces of the ejbs and special method parameter types that are needed for the communication (if any). Now we put this package in the directory /lib of our application.

To make sure that this package is now loaded by the common classloader, we reference it from within the web package by adding a Class-Path entry to the web packages MANIFEST.MF file[2].

Figure 11.12. Example Manifest file of web module

   
   Manifest-Version: 1.0
   Class-Path: ./lib/ejb-client.jar
   
   
  

Now you just jar your applications directory, name it <anyhow>.ear, and drop it in one of JBoss' autodeploy directories.

Figure 11.13. Example application archive contents


   META-INF/
   META-INF/MANIFEST.MF
   META-INF/application.xml
   ejb-app.jar
   web-app.war
   lib/
   lib/ejb-client.jar
 
  

Note:

  1. The MANIFEST.MF as shown in Figure 11.12. is inside of the ejb or the war archive and NOT the one directly in the ear archive.

  2. There should be a carriage return after the Class-Path entry in the manifest file - otherwise it is not found.

Some useful references are Manifest tutorial and Jar specification

Notes

[1] The MANIFEST.MF referred to is the one inside the ejb or war archive and NOT the one directly in the ear archive.

[2] There is a "feature" of the jdk jarfile reader that means that you need to have a carriage return after the Class-Path entry in the manifest file - otherwise it is not found.