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

Table of Contents

1. Overview of Java Enterprise Edition
1.1. What is Java EE?
1.2. Open and Standard-based
1.3. Multi-tier
1.4. Web-Enabled
1.5. Server Centric
1.6. Component-Based Distributed Architecture
1.7. Enterprise Applications
1.8. Java EE Contents
1.9. Java EE Services
2. Overview of JBoss Application Server
2.1. JBoss Organization
2.2. JBoss AS Background
2.3. Highlights of JBoss AS
2.4. What is new in JBoss AS 5?
2.5. JBoss AS Architecture
2.6. JBoss Microcontainer Layer
2.7. Services Layer
2.8. Aspect Layer
2.9. Application Layer
2.10. JBoss AS Services
2.11. JBoss AS Requirements
3. Installing JBoss AS
3.1. Getting and Installing Java
3.2. Configuring Java
3.3. Getting JBoss AS
3.4. Installing JBoss AS 5
4. JBoss Directory Structure
4.1. JBoss AS Directory Structure
4.2. The bin Directory
4.3. The client Directory
4.4. The common directory
4.5. The docs Directory
4.6. The lib Directory
4.7. The server Directory
4.8. The server Configuration Sets
4.9. The default/conf Directory
4.10. The default/data Directory
4.11. The default/deploy Directory
4.12. The default/deployers Directory
4.13. The default/lib Directory
4.14. The default/log Directory
4.15. The default/tmp Directory
4.16. The default/work Directory
5. Controlling the Life-Cycle of JBoss AS
5.1. Starting JBoss AS
5.2. Verifying JBoss AS Startup
5.3. Stopping JBoss AS
5.4. Starting From a Remote Server
6. Deployments on JBoss
6.1. Java EE Deployment Lifecycle
6.2. Deployment Descriptors
6.3. Deployment on JBoss AS
6.4. Deployers on JBoss AS
6.5. Deployment Dependencies
6.6. Hot vs. Cold Deployment
6.7. Bootstrapping JBoss
6.8. Lab: Deployment
7. Web Application Administration
7.1. Web Technologies
7.2. CGI vs. Servlets/JSPs
7.3. Tomcat Web Container
7.4. Tomcat’s server.xml
7.5. Tomcat’s web.xml
7.6. Defining and Mapping Servlets
7.7. Defining and Mapping Filters
7.8. Session Configuration
7.9. Welcome File List
7.10. Error Documents
7.11. Serving Static Content
7.12. Virtual Hosting with Tomcat
7.13. Web Access Logging
7.14. Lab: Tomcat
8. JNDI Administration
8.1. Java Naming and Directory Interface
8.2. JNDI in Java EE
8.3. JNDI on JBoss
8.4. Lab: JNDI View
9. Javamail Administration
9.1. What is JavaMail?
9.2. Configuring JavaMail Service
9.3. Lab: Mail
10. JMS Administration
10.1. JMS Overview
10.2. JMS in Java EE
10.3. When is JMS Used
10.4. JMS Architecture
10.5. JMS Messaging Domains
10.6. JMS Message Consumption
10.7. JMS on JBoss Configuration
10.8. Configure JMS connection factories
10.9. Configure JMS destinations
10.10. Advanded JBoss Messaging
10.11. JBoss Messaging bridge
10.12. Persistence service configuration
10.13. Lab: JMS
11. Enterprise Java Beans Administration
11.1. Introduction to EJB 3.0
11.2. EJB 3.0 Components
11.3. EJB Container
11.4. Benefits of EJB Technology
11.5. Drawbacks of EJBs
11.6. Session Beans
11.7. Interceptors
11.8. Entity Beans
11.9. Message-Driven Bean
11.10. Session Beans Client Interfaces
11.11. Stateless Session Beans Life Cycle
11.12. Stateful Session Beans Life Cycle
11.13. Message-Driven Beans Life Cycle
11.14. Configuring the EJB container
11.15. Stateful Session Bean Configuration
11.16. Lab: Stateless Session Bean
12. Web Services and JBoss
12.1. Web Services Overview
12.2. Service Oriented Architecture
12.3. Web Services With JAX-WS
12.4. Web Services on JBoss
12.5. JBoss Web Services Tools
12.6. Lab: Web Services
13. JMX Administration
13.1. What is JMX?
13.2. Why JMX?
13.3. JMX Architecture
13.4. JMX on JBoss AS
13.5. JMX Console
13.6. Web Console
13.7. Twiddle Tool
13.8. JBoss AS Administration Console
13.9. Lab: JMX Print Service
13.10. JBoss Monitoring
13.11. Snapshot and Web Console
13.12. Monitoring with JConsole
13.13. Scheduling on JBoss
13.14. Lab: Monitoring
14. Class Loading on JBoss
14.1. Class Namespace Isolation
14.2. Java Class Runtime Identity
14.3. Class Loading in Java EE
14.4. Class Loading On JBoss
14.5. The Class Loader
14.6. Default Class Search Order
14.7. Scoping Classes
14.8. Scoped Class Search Order
14.9. App-specific Log4J Config
14.10. Problems With Class Loading
14.11. Lab: Class Loading
15. Database Integration on JBoss
15.1. Steps Involved
15.2. Resource Requirement
15.3. Install JDBC Drivers
15.4. Define a RDBMS DBCP Resource
15.5. Map our Resource
15.6. Using our DataSource (RDBMS DBCP)
15.7. Hypersonic Database
15.8. Detecting Connection Leaks
15.9. Lab: Database Connectivity
16. Security on JBoss
16.1. Securing Applications
16.2. Filtering Clients by Source
16.3. Authentication & Authorization
16.4. Requiring A&A
16.5. Plain-Text Login Module
16.6. Database Login Module
16.7. FORM-based Login
16.8. Configuring JBoss AS for SSL
16.9. Creating SSL Certificates
16.10. Configure SSL Connector
16.11. Testing SSL Configuration
16.12. Requiring SSL in Apps
16.13. Lab: Application Security
16.14. Securing JMS destinations
16.15. Securing JBoss AS
16.16. JBoss AS System User
16.17. File System Security
16.18. Securing JMX Invoker
16.19. Securing JBoss Applications
16.20. Securing Hypersonic DB
16.21. Java Security Manager
16.22. Running Behind a Firewall
16.23. Lab: JBoss Security
17. Tuning JBoss
17.1. JVM Tuning
17.2. Tomcat Tuning
17.3. RMI Tuning
17.4. Log4J Tuning
17.5. Tuning Other Services
17.6. JMS Tuning
17.7. Slimming JBoss
18. High Availability and Scalability on JBoss
18.1. Requirements
18.2. Clustering: General understanding
18.3. Clustering and JBoss
18.4. Simple Web Architecture
18.5. External Load Balancer Architecture
18.6. Smart Proxy Architecture
18.7. General configuration for the following examples
18.8. Fronting with a Web Server
18.9. Fronting with Apache HTTPD
18.10. Installing mod_jk
18.11. Configuring mod_jk
18.12. Simple Load Balancing
18.13. Enabling Sticky Sessions
18.14. Clustered Session Replication
18.15. Clustering Single Sign-On
18.16. Clustering with HA-JNDI
18.17. HA-JNDI Client Configuration
18.18. Clustering with HA-JMS
18.19. Clustering with Stateless Session Beans
18.20. Clustering with Stateful Session Beans
18.21. Lab: Clustering