JBoss Enterprise Application Platform 6

Development Guide

For Use with JBoss Enterprise Application Platform 6

Edition 2

Sande Gilda

Eamon Logue

Darrin Mison

David Ryan

Misty Stanley-Jones

Keerat Verma

Tom Wells

Legal Notice

Copyright © 2012 Red Hat, Inc..
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.


This book provides references and examples for Java EE 6 developers using JBoss Enterprise Application Platform 6 and its patch releases.
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
1. Get Started Developing Applications
1.1. Introduction
1.1.1. Introducing JBoss Enterprise Application Platform 6
1.2. Prerequisites
1.2.1. Become Familiar with Java Enterprise Edition 6
1.2.2. About Modules and the New Modular Class Loading System used in JBoss Enterprise Application Platform 6
1.3. Install JBoss Enterprise Application Platform 6
1.3.1. Download and Install JBoss Enterprise Application Platform 6
1.3.2. Take a Quick Tour of JBoss Enterprise Application Platform 6
1.4. Set Up the Development Environment
1.4.1. Download and Install JBoss Developer Studio
1.5. Run Your First Application
1.5.1. Replace the Default Welcome Web Application
1.5.2. Download the Quickstart Code Examples
1.5.3. Run the Quickstarts
1.5.4. Review the Quickstart Tutorials
2. Maven Guide
2.1. Learn about Maven
2.1.1. About the Maven Repository
2.1.2. About the Maven POM File
2.1.3. Minimum Requirements of a Maven POM File
2.1.4. About the Maven Settings File
2.2. Install Maven and the JBoss Maven Repository
2.2.1. Download and Install Maven
2.2.2. Install the JBoss Enterprise Application Platform 6 Maven Repository
2.2.3. Install the JBoss Enterprise Application Platform 6 Maven Repository Locally
2.2.4. Install the JBoss Enterprise Application Platform 6 Maven Repository for Use with Apache httpd
2.2.5. Install the JBoss Enterprise Application Platform 6 Maven Repository Using Nexus Maven Repository Manager
2.2.6. About Maven Repository Managers
2.3. Configure the Maven Repository
2.3.1. Configure the JBoss Enterprise Application Platform Maven Repository
2.3.2. Configure the JBoss Enterprise Application Platform Maven Repository Using the Maven Settings
2.3.3. Configure the JBoss Enterprise Application Platform Maven Repository Using the Project POM
3. Class Loading and Modules
3.1. Introduction
3.1.1. Overview of Class Loading and Modules
3.1.2. Class Loading
3.1.3. Modules
3.1.4. Module Dependencies
3.1.5. Class Loading in Deployments
3.1.6. Class Loading Precedence
3.1.7. Dynamic Module Naming
3.1.8. jboss-deployment-structure.xml
3.2. Add an Explicit Module Dependency to a Deployment
3.3. Generate MANIFEST.MF entries using Maven
3.4. Prevent a Module Being Implicitly Loaded
3.5. Exclude a Subsystem from a Deployment
3.6. Class Loading and Subdeployments
3.6.1. Modules and Class Loading in Enterprise Archives
3.6.2. Subdeployment Class Loader Isolation
3.6.3. Disable Subdeployment Class Loader Isolation Within a EAR
3.7. Reference
3.7.1. Implicit Module Dependencies
3.7.2. Included Modules
3.7.3. JBoss Deployment Structure Deployment Descriptor Reference
4. Logging for Developers
4.1. Introduction
4.1.1. About Logging
4.1.2. Application Logging Frameworks Supported By JBoss LogManager
4.1.3. About Log Levels
4.1.4. Supported Log Levels
4.1.5. Default Log File Locations
4.2. Logging with the JBoss Logging Framework
4.2.1. About JBoss Logging
4.2.2. Features of JBoss Logging
4.2.3. Add Logging to an Application with JBoss Logging
5. Internationalization and Localization
5.1. Introduction
5.1.1. About Internationalization
5.1.2. About Localization
5.2. JBoss Logging Tools
5.2.1. Overview
5.2.2. Creating Internationalized Loggers, Messages and Exceptions
5.2.3. Localizing Internationalized Loggers, Messages and Exceptions
5.2.4. Customizing Internationalized Log Messages
5.2.5. Customizing Internationalized Exceptions
5.2.6. Reference
6. Enterprise JavaBeans
6.1. Introduction
6.1.1. Overview of Enterprise JavaBeans
6.1.2. EJB 3.1 Feature Set
6.1.3. EJB 3.1 Lite
6.1.4. EJB 3.1 Lite Features
6.1.5. Enterprise Beans
6.1.6. Overview of Writing Enterprise Beans
6.1.7. Session Bean Business Interfaces
6.2. Creating Enterprise Bean Projects
6.2.1. Create an EJB Archive Project Using JBoss Developer Studio
6.2.2. Create an EJB Archive Project in Maven
6.2.3. Create an EAR Project containing an EJB Project
6.2.4. Add a Deployment Descriptor to an EJB Project
6.3. Session Beans
6.3.1. Session Beans
6.3.2. Stateless Session Beans
6.3.3. Stateful Session Beans
6.3.4. Singleton Session Beans
6.3.5. Add Session Beans to a Project in JBoss Developer Studio
6.4. Message-Driven Beans
6.4.1. Message-Driven Beans
6.4.2. Resource Adapters
6.4.3. Create a JMS-based Message-Driven Bean in JBoss Developer Studio
6.5. Invoking Session Beans
6.5.1. Invoke a Session Bean Remotely using JNDI
6.6. Clustered Enterprise JavaBeans
6.6.1. About Clustered Enterprise JavaBeans (EJBs)
6.7. Reference
6.7.1. EJB JNDI Naming Reference
6.7.2. EJB Reference Resolution
6.7.3. Project dependencies for Remote EJB Clients
6.7.4. jboss-ejb3.xml Deployment Descriptor Reference
7. Clustering in Web Applications
7.1. Session Replication
7.1.1. About HTTP Session Replication
7.1.2. About the Web Session Cache
7.1.3. Configure the Web Session Cache
7.1.4. Enable Session Replication in Your Application
7.2. HttpSession Passivation and Activation
7.2.1. About HTTP Session Passivation and Activation
7.2.2. Configure HttpSession Passivation in Your Application
7.3. Cookie Domain
7.3.1. About the Cookie Domain
7.3.2. Configure the Cookie Domain
7.4. Implement an HA Singleton
8. CDI
8.1. Overview of CDI
8.1.1. Overview of CDI
8.1.2. About Contexts and Dependency Injection (CDI)
8.1.3. Benefits of CDI
8.1.4. About Type-safe Dependency Injection
8.1.5. Relationship Between Weld, Seam 2, and JavaServer Faces
8.2. Use CDI
8.2.1. First Steps
8.2.2. Use CDI to Develop an Application
8.2.3. Ambiguous or Unsatisfied Dependencies
8.2.4. Managed Beans
8.2.5. Contexts, Scopes, and Dependencies
8.2.6. Bean Lifecycle
8.2.7. Named Beans and Alternative Beans
8.2.8. Stereotypes
8.2.9. Observer Methods
8.2.10. Interceptors
8.2.11. About Decorators
8.2.12. About Portable Extensions
8.2.13. Bean Proxies
9. Java Transaction API (JTA)
9.1. Overview
9.1.1. Overview of Java Transactions API (JTA)
9.2. Transaction Concepts
9.2.1. About Transactions
9.2.2. About ACID Properties for Transactions
9.2.3. About the Transaction Coordinator or Transaction Manager
9.2.4. About Transaction Participants
9.2.5. About Java Transactions API (JTA)
9.2.6. About Java Transaction Service (JTS)
9.2.7. About XA Datasources and XA Transactions
9.2.8. About XA Recovery
9.2.9. About the 2-Phase Commit Protocol
9.2.10. About Transaction Timeouts
9.2.11. About Distributed Transactions
9.2.12. About the ORB Portability API
9.2.13. About Nested Transactions
9.2.14. About Garbage Collection
9.3. Transaction Optimizations
9.3.1. Overview of Transaction Optimizations
9.3.2. About the LRCO Optimization for Single-phase Commit (1PC)
9.3.3. About the Presumed-Abort Optimization
9.3.4. About the Read-Only Optimization
9.4. Transaction Outcomes
9.4.1. About Transaction Outcomes
9.4.2. About Transaction Commit
9.4.3. About Transaction Roll-Back
9.4.4. About Heuristic Outcomes
9.4.5. JBoss Transactions Errors and Exceptions
9.5. Overview of JTA Transactions
9.5.1. About Java Transactions API (JTA)
9.5.2. Lifecycle of a JTA Transaction
9.6. Transaction Subsystem Configuration
9.6.1. Transactions Configuration Overview
9.6.2. Transactional Datasource Configuration
9.6.3. Transaction Logging
9.7. Use JTA Transactions
9.7.1. Transactions JTA Task Overview
9.7.2. Control Transactions
9.7.3. Begin a Transaction
9.7.4. Nest Transactions
9.7.5. Commit a Transaction
9.7.6. Roll Back a Transaction
9.7.7. Handle a Heuristic Outcome in a Transaction
9.7.8. Transaction Timeouts
9.7.9. JTA Transaction Error Handling
9.8. ORB Configuration
9.8.1. About Common Object Request Broker Architecture (CORBA)
9.8.2. Configure the ORB for JTS Transactions
9.9. Transaction References
9.9.1. JBoss Transactions Errors and Exceptions
9.9.2. JTA Clustering Limitations
9.9.3. JTA Transaction Example
9.9.4. API Documentation for JBoss Transactions JTA
10. Hibernate
10.1. About Hibernate Core
10.2. Java Persistence API (JPA)
10.2.1. About JPA
10.2.2. Hibernate EntityManager
10.2.3. Getting Started
10.2.4. Configuration
10.2.5. Second-Level Caches
10.3. Hibernate Annotations
10.3.1. Hibernate Annotations
10.4. Hibernate Query Language
10.4.1. About Hibernate Query Language
10.4.2. HQL Statements
10.4.3. About the INSERT Statement
10.4.4. About the FROM Clause
10.4.5. About the WITH Clause
10.4.6. About Collection Member References
10.4.7. About Qualified Path Expressions
10.4.8. About Scalar Functions
10.4.9. HQL Standardized Functions
10.4.10. About the Concatenation Operation
10.4.11. About Dynamic Instantiation
10.4.12. About HQL Predicates
10.4.13. About Relational Comparisons
10.4.14. About the IN Predicate
10.4.15. About HQL Ordering
10.5. Hibernate Services
10.5.1. About Hibernate Services
10.5.2. About Service Contracts
10.5.3. Types of Service Dependencies
10.5.4. The ServiceRegistry
10.5.5. Custom Services
10.5.6. The Bootstrap Registry
10.5.7. The SessionFactory Registry
10.5.8. Integrators
10.6. Bean Validation
10.6.1. About Bean Validation
10.6.2. Hibernate Validator
10.6.3. Validation Constraints
10.6.4. Configuration
10.7. Envers
10.7.1. About Hibernate Envers
10.7.2. About Auditing Persistent Classes
10.7.3. Auditing Strategies
10.7.4. Getting Started with Entity Auditing
10.7.5. Configuration
10.7.6. Queries
11. JAX-RS Web Services
11.1. About JAX-RS
11.2. About RESTEasy
11.3. About RESTful Web Services
11.4. RESTEasy Defined Annotations
11.5. RESTEasy Configuration
11.5.1. RESTEasy Configuration Parameters
11.6. JAX-RS Web Service Security
11.6.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service
11.6.2. Secure a JAX-RS Web Service using Annotations
11.7. RESTEasy Logging
11.7.1. About JAX-RS Web Service Logging
11.7.2. Configure a Log Category in the Management Console
11.7.3. Logging Categories Defined in RESTEasy
11.8. Exception Handling
11.8.1. Create an Exception Mapper
11.8.2. RESTEasy Internally Thrown Exceptions
11.9. RESTEasy Interceptors
11.9.1. Intercept JAX-RS Invocations
11.9.2. Bind an Interceptor to a JAX-RS Method
11.9.3. Register an Interceptor
11.9.4. Interceptor Precedence Families
11.10. String Based Annotations
11.10.1. Convert String Based @*Param Annotations to Objects
11.11. Configure File Extensions
11.11.1. Map File Extensions to Media Types in the web.xml File
11.11.2. Map File Extensions to Languages in the web.xml File
11.11.3. RESTEasy Supported Media Types
11.12. RESTEasy JavaScript API
11.12.1. About the RESTEasy JavaScript API
11.12.2. Enable the RESTEasy JavaScript API Servlet
11.12.3. RESTEasy Javascript API Parameters
11.12.4. Build AJAX Queries with the JavaScript API
11.12.5. REST.Request Class Members
11.13. RESTEasy Asynchronous Job Service
11.13.1. About the RESTEasy Asynchronous Job Service
11.13.2. Enable the Asynchronous Job Service
11.13.3. Configure Asynchronous Jobs for RESTEasy
11.13.4. Asynchronous Job Service Configuration Parameters
11.14. RESTEasy JAXB
11.14.1. Create a JAXB Decorator
11.15. RESTEasy Atom Support
11.15.1. About the Atom API and Provider
12. JAX-WS Web Services
12.1. About JAX-WS Web Services
12.2. Configure the webservices Subsystem
12.3. JAX-WS Web Service Endpoints
12.3.1. About JAX-WS Web Service Endpoints
12.3.2. Write and Deploy a JAX-WS Web Service Endpoint
12.4. JAX-WS Web service Clients
12.4.1. Consume and Access a JAX-WS Web Service
12.4.2. Develop a JAX-WS Client Application
12.5. JAX-WS Development Reference
12.5.1. Enable Web Services Addressing (WS-Addressing)
12.5.2. JAX-WS Common API Reference
13. Identity Within Applications
13.1. Foundational Concepts
13.1.1. About Encryption
13.1.2. About Security Domains
13.1.3. About SSL Encryption
13.1.4. About Declarative Security
13.2. Role-Based Security in Applications
13.2.1. About Application Security
13.2.2. About Authentication
13.2.3. About Authorization
13.2.4. About Security Auditing
13.2.5. About Security Mapping
13.2.6. About the Security Extension Architecture
13.2.7. Java Authentication and Authorization Service (JAAS)
13.2.8. About Java Authentication and Authorization Service (JAAS)
13.2.9. Use a Security Domain in Your Application
13.2.10. Use Role-Based Security In Servlets
13.2.11. Use A Third-Party Authentication System In Your Application
13.3. Security Realms
13.3.1. About Security Realms
13.3.2. Add a New Security Realm
13.3.3. Add a User to a Security Realm
13.4. EJB Application Security
13.4.1. Security Identity
13.4.2. EJB Method Permissions
13.4.3. EJB Security Annotations
13.4.4. Remote Access to EJBs
13.5. JAX-RS Application Security
13.5.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service
13.5.2. Secure a JAX-RS Web Service using Annotations
13.6. Secure Remote Password Protocol
13.6.1. About Secure Remote Password Protocol (SRP)
13.6.2. Configure Secure Remote Password ISRP) Protocol
13.7. Password Vaults for Sensitive Strings
13.7.1. About Securing Sensitive Strings in Clear-Text Files
13.7.2. Create a Java Keystore to Store Sensitive Strings
13.7.3. Mask the Keystore Password and Initialize the Password Vault
13.7.4. Configure the JBoss Enterprise Application Platform to Use the Password Vault
13.7.5. Store and Retrieve Encrypted Sensitive Strings in the Java Keystore
13.7.6. Store and Resolve Sensitive Strings In Your Applications
13.8. Java Authorization Contract for Containers (JACC)
13.8.1. About Java Authorization Contract for Containers (JACC)
13.8.2. Configure Java Authorization Contract for Containers (JACC) Security
13.9. Java Authentication SPI for Containers (JASPI)
13.9.1. About Java Authentication SPI for Containers (JASPI) Security
13.9.2. Configure Java Authentication SPI for Containers (JASPI) Security
14. Single Sign On (SSO)
14.1. About Single Sign On (SSO) for Web Applications
14.2. About Clustered Single Sign On (SSO) for Web Applications
14.3. Choose the Right SSO Implementation
14.4. Use Single Sign On (SSO) In A Web Application
14.5. About Kerberos
14.6. About SPNEGO
14.7. About Microsoft Active Directory
14.8. Configure Kerberos or Microsoft Active Directory Desktop SSO for Web Applications
15. Development Security References
15.1. jboss-web.xml Configuration Reference
15.2. EJB Security Parameter Reference
16. Supplemental References
16.1. Types of Java Archives
A. Revision History