Jboss Admin Tutorial: Deployments on JBoss

6. Deployments on JBoss

6.1. Java EE Deployment Lifecycle


Development and Deployment Lifecycle:

  1. Design static content (HTML, CSS, GIF, JPG, etc.)
  2. Develop dynamic content (Servlets, JSPs, and other Java components like EJBs)
  3. Write deployment descriptors (e.g. web.xml, application.xml, ejb-jar.xml, etc.) for components
  4. Assemble components into deployable packages (e.g. WAR, JAR, EAR, etc.)
  5. Provide all resources that the components require (e.g DBCP, Mail sessions, message queues, etc.)
  6. Deploy packages (e.g. WAR, JAR, EAR, etc.) on the Java EE application server
  7. Manage Java EE applications on the server

6.2. Deployment Descriptors

  • Give the containers instructions on how to use and manage deployed Java EE components

    • Security
    • Transactions
    • Persistence
  • Declarative customization (XML-based)
  • Enables portability of Java EE components

J2EE 1.3 and JBoss pre 5.x deployment descriptors are defined by XML DTD documents. These can be found in $JBOSS_HOME/docs/dtd/ directory. As of J2EE 1.4 and JBoss 5.x, deployment descriptors are defined by XML Schema (XSD) documents. These can be found in $JBOSS_HOME/docs/schema/ directory.

6.3. Deployment on JBoss AS

  • Deployment is a two-step process

    • First we notify JBoss that of the application we want to deploy by copying it to ${jboss.server.home.url}/deploy/ or any of its subdirectories
    • Then, JBoss performs the necessary steps to make that application ready for our use
  • Undeployment is also a two-step process

    • First we notify JBoss that of the application we want to undeploy by removing it from ${jboss.server.home.url}/deploy/ directory
    • Then, JBoss performs the necessary steps to stop the application and unload its resources
  • Alternatively, applications can be deployed/undeployed/and re-deployed via jboss.system:service=MainDeployer JMX MBean (more on this later).

    • This mechanism also support remote management of JBoss deployments
  • Supports deployment dependencies
  • Hot-deployment vs. cold-deployment
  • Archived components are uncompressed (a.k.a. exploded) under ${jboss.server.temp.dir}/deploy/

    • JBoss deletes (or at least it is supposed to delete) ${jboss.server.temp.dir}/deploy/ deployments upon restart
    • It is recommended to deploy applications already uncompressed (exploded) for to avoid the overhead of uncompression, and provide easy access to deployment descriptors and JSP files
  • The deployed components are automatically redeployed if their deployment descriptors are modified while JBoss AS is running
  • JBoss supports nested deployments (e.g. WAR under EAR) regardless of whether they are compressed into archives or deployed uncompressed
  • With clustering enabled, JBoss AS also supports farmed deployment - that is, pushing applications across the entire cluster when deployed on any single member of that cluster
  • JBoss supports JSR-88 (Java EE application deployment spec) but

    • There are no tools that make this kind of deployment easy - requires writing code
    • The resulting deployments go into the tmp/ directory - making redeployments harder

6.4. Deployers on JBoss AS

  • JBoss has an extensible deployment architecture that allows components to be easily integrated into the core JBoss Microcontainer
  • Deployers for: WARs, EARs, EJBs, JAR libraries, RARs, SARs, XML-based services, HARs, Aspects, Client, BeanShell scripts

    • The deployers are deployed themselves as *.deployer or *-deployer-beans.xml under ${jboss.server.home.url}/deployers/ directory

6.4.1. Type of Deployers

  • Web - handles web application archives as .war files with descriptors WEB-INF/web.xml, WEB-INF/jboss-web.xml (optional), and WEB-INF/context.xml (optional)
  • EAR - handles enterprise application archives as .ear files with descriptors META-INF/application.xml and META-INF/jboss-app.xml (optional)
  • EJB - handles Enterprise Java Bean archives as .jar files with descriptors META-INF/ejb-jar.xml and META-INF/jboss.xml (optional)
  • RAR - handles JCA resource archives as .rar files with a descriptor META-INF/ra.xml
  • SAR - handles JBoss MBean service archives either as .sar files with a META-INF/jboss-service.xml descriptor, or as stand alone *-service.xml files
  • Web Service - handles JBoss Web Services as *.wsr files
  • POJO - handles plain old java objects deployed as *-jboss-beans.xml files that register with JBoss Microcontainer
  • XML - handles arbitrary .xml files that are converted into SARs (e.g. *-ds.xml get deployed as data sources)
  • HAR - handles Hibernate archives as .har files with a META-INF/hibernate-service.xml descriptor
  • Aspect - handles aspect archives either as .aop files with a META-INF/jboss-aop.xml descriptor or as stand-alone *-aop.xml files
  • Client - handles Java EE application client resources as .jar files with META-INF/application-client.xml and META-INF/jboss-client.xml (optional) descriptors
  • BeanShell - handles bean shell scripts as .bsh files that represent MBeans
  • Zip - handles arbitrary .zip archives that are examined for that actual deployment type based on the internal deployment descriptors

6.4.2. Deployment Configuration

  • JBoss deployers (and the file extensions that trigger them) are configured in ${jboss.server.home.url}/conf/bootstrap/deployers.xml file.
  • By default JBoss scans ${jboss.server.home.url}/deploy/ for deployments, but this can be changed/extended in BootstrapProfileFactoryapplicationURIs property in ${jboss.server.home.url}/conf/bootstrap/profile.xml file:

    <deployment ...>
      <bean name="BootstrapProfileFactory" ...>
        <property name="deployersURI">${jboss.server.home.url}deployers</property>
        <property name="applicationURIs">
          <list elementClass="java.net.URI">
  • JBoss rescans the deployment directories for new deployments (or changes to the existing deployments) every 5 seconds as specified by HDScannerscanPeriod in ${jboss.server.home.url}deploy/hdscanner-jboss-beans.xml file:

    <deployment ...>
      <bean name="HDScanner" ...>
        <property name="scanPeriod">5000</property>

    In JBoss 5.0, deployment directories were defined by VFSDeploymentScannerURIList in profile-service.xml file.

6.4.3. Deployment Ordering

  • During the server startup, after initializing all deployers, JBoss will deploy applications/components in the following order: AOPs, SARs, POJOs, RARs, Data Sources, HARs, EJBs, ZIPs, WARs, Web Services, EARs, Bean Shell Scripts
  • To force the deployment of an application/component at the very end of the startup phase, deploy it under ${jboss.server.home.url}/deploy/last or as *.last

6.5. Deployment Dependencies

  • Components can define dependencies on other components through JMX:

    <depends optional-attribute-name="ConnectionManager">
  • For example:

    • Undeploy Hypersonic DB (hsqldb-ds.xml) and JMS MQ automatically shuts down

      12:07:13,767 INFO  [testTopic] Unbinding JNDI name: topic/testTopic
      12:07:13,776 INFO  [securedTopic] Unbinding JNDI name: topic/securedTopic
      12:07:13,779 INFO  [testDurableTopic] Unbinding JNDI name: topic/testDurableTopic
      12:07:13,783 INFO  [testQueue] Unbinding JNDI name: queue/testQueue
      12:07:13,838 INFO  [A] Unbinding JNDI name: queue/A
      12:07:13,850 INFO  [B] Unbinding JNDI name: queue/B
      12:07:13,859 INFO  [C] Unbinding JNDI name: queue/C
      12:07:13,866 INFO  [D] Unbinding JNDI name: queue/D
      12:07:13,869 INFO  [ex] Unbinding JNDI name: queue/ex
      12:07:13,885 INFO  [DLQ] Unbinding JNDI name: queue/DLQ
      12:07:13,895 INFO  [ConnectionFactoryBindingService] Unbound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=DefaultDS' from JNDI name 'java:DefaultDS'
      12:07:16,578 INFO  [HypersonicDatabase] Database standalone closed clean
    • Redeploy Hypersonic DB (hsqldb-ds.xml) and JMS MQ automatically starts up again

      12:18:48,713 INFO  [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=DefaultDS' to JNDI name 'java:DefaultDS'
      12:18:48,847 INFO  [A] Bound to JNDI name: queue/A
      12:18:48,852 INFO  [B] Bound to JNDI name: queue/B
      12:18:48,856 INFO  [C] Bound to JNDI name: queue/C
      12:18:48,861 INFO  [D] Bound to JNDI name: queue/D
      12:18:48,865 INFO  [ex] Bound to JNDI name: queue/ex
      12:18:48,870 INFO  [testTopic] Bound to JNDI name: topic/testTopic
      12:18:48,879 INFO  [securedTopic] Bound to JNDI name: topic/securedTopic
      12:18:48,883 INFO  [testDurableTopic] Bound to JNDI name: topic/testDurableTopic
      12:18:48,887 INFO  [testQueue] Bound to JNDI name: queue/testQueue
      12:18:48,934 INFO  [UILServerILService] JBossMQ UIL service available at : /
      12:18:48,950 INFO  [DLQ] Bound to JNDI name: queue/DLQ
    • Observe the <depends> in the descriptors

6.6. Hot vs. Cold Deployment

  • Hot deployment is cool, but there is a risk of:

    • Class-Loader exceptions (more on this later)
    • Unrecognized configuration settings
    • Lost session/application scoped data
  • Cold deployment is slow but stable

    • Stop JBoss AS
    • Optionally delete data/, log/, tmp/, work/
    • Redeploy your application(s)
    • Start JBoss AS

Hot deployment is generally considered safe for:

  • Java Server Pages (.jsp) files. They get recompiled automatically by the servlet engine following a change.
  • Class files that do not change their public interfaces, especially when there is no RMI involved. This requires full redeployment, so it is still somewhat risky.

Hot and cold [re]deployments can be easily automated with the Ant build tool. See http://ant.apache.org for more info.

6.7. Bootstrapping JBoss

  • When JBoss AS is first started, it is nothing more than a JBoss Microcontainer.

    • It shows its true nature once it loads (bootstraps) the core services from the ${jboss.server.config.url}/jboss-service.xml and ${jboss.server.config.url}/bootstrap.xml files, based on the configuration set (defined on the command line).

6.7.1. File conf/jboss-service.xml

Defines settings and JMX-based services that are fixed for the lifetime of the server:

  • Class-path: ${jboss.server.lib.url}/* and ${jboss.common.lib.url}/*
  • MainDeployer - now just a wrapper for the existing deployment mechanism (as specified above)
  • Attribute Persistence Service

    • Used to persist changes made through JMX to server configuration
    • Disabled by default
  • Thread Pool

    • Used by a number of JBoss services, including EJBs
    • The maximum pool size (MaximumPoolSize=10) and blocking mode (BlockingMode=run) may need to be tuned (more on that later)
  • Logging

    • Based on Log4J
    • Configured via ${jboss.server.home.url}/conf/jboss-log4j.xml

      • Automatically refreshed every 60 seconds if changed
  • Class Loading (including for RMI)
  • JNDI Naming Service

    • Includes JNDIView for JMX-based monitoring of JNDI
  • JaasSecurityManager

6.7.2. File conf/bootstrap.xml

Lists URLs (files) that are to be loaded and processed for Microcontainer-based beans during the bootstrapping process

<bootstrap xmlns="urn:jboss:bootstrap:1.0">

6.7.3. XMBeans in conf/xmdesc/

  • XMBeans annotate MBeans (defined in jboss-service.xml) by adding ability to:

    • Describe attributes and operations
    • Expose notification information
    • Define persistence of attributes
    • Inject custom interceptors for security and remote access
  • Unique to JBoss AS
  • Declarative (XML-based), not hard-coded

XMBeans in conf/xmdesc/:


6.8. Lab: Deployment

  • Deploying fortune.war example application
  • Undeploy it
  • Redeploy it
  • Test access to it
  1. Start JBoss AS
  2. Deploy fortune.war to ${jboss.server.home.url}/deploy/
  3. Observe JBoss AS console output and test http://localhost:8080/fortune/
  4. Undeploy fortune.war (move or delete)
  5. Observe JBoss AS console output and test http://localhost:8080/fortune/
  6. Redeploy - twice
  7. Observe JBoss AS console output
  8. Restart JBoss AS
  9. Is the application still deployed?
  10. Modify deployed fortune.war/WEB-INF/web.xml file (while JBoss AS is running). For example, add:

  11. Observe JBoss AS console output and test http://localhost:8080/fortune/get