JBoss Enterprise Application Platform 6.1

Development Guide

For Use with Red Hat JBoss Enterprise Application Platform 6

Edition 1

Nidhi Chaudhary

Lucas Costi

Russell Dickenson

Sande Gilda

Vikram Goyal

Eamon Logue

Darrin Mison

Scott Mumford

David Ryan

Misty Stanley-Jones

Keerat Verma

Tom Wells

Legal Notice

Copyright © 2014 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.

Abstract

This book provides references and examples for Java EE 6 developers using Red Hat JBoss Enterprise Application Platform 6 and its patch releases.
Preface
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. About Red Hat JBoss Enterprise Application Platform 6 (JBoss EAP 6)
1.1.2. About the Use of EAP_HOME in this Document
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 EAP 6
1.3. Set Up the Development Environment
1.3.1. Download and Install JBoss Developer Studio
1.4. Run Your First Application
1.4.1. Replace the Default Welcome Web Application
1.4.2. Download the Quickstart Code Examples
1.4.3. Run the Quickstarts
1.4.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 EAP 6 Maven Repository
2.2.3. Install the JBoss EAP 6 Maven Repository Locally
2.2.4. Install the JBoss EAP 6 Maven Repository for Use with Apache httpd
2.2.5. Install the JBoss EAP 6 Maven Repository Using Nexus Maven Repository Manager
2.2.6. About Maven Repository Managers
2.3. Use the Maven Repository
2.3.1. Configure the JBoss EAP Maven Repository
2.3.2. Configure the JBoss EAP 6 Maven Repository Using the Maven Settings
2.3.3. Configure the JBoss EAP 6 Maven Repository Using the Project POM
2.3.4. Manage Project Dependencies
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. Global Valves
4.1. About Valves
4.2. About Global Valves
4.3. About Authenticator Valves
4.4. Configure a Web Application to use a Valve
4.5. Configure a Web Application to use an Authenticator Valve
4.6. Create a Custom Valve
5. Logging for Developers
5.1. Introduction
5.1.1. About Logging
5.1.2. Application Logging Frameworks Supported By JBoss LogManager
5.1.3. About Log Levels
5.1.4. Supported Log Levels
5.1.5. Default Log File Locations
5.2. Logging with the JBoss Logging Framework
5.2.1. About JBoss Logging
5.2.2. Features of JBoss Logging
5.2.3. Add Logging to an Application with JBoss Logging
5.3. Logging Profiles
5.3.1. About Logging Profiles
5.3.2. Specify a Logging Profile in an Application
6. Internationalization and Localization
6.1. Introduction
6.1.1. About Internationalization
6.1.2. About Localization
6.2. JBoss Logging Tools
6.2.1. Overview
6.2.2. Creating Internationalized Loggers, Messages and Exceptions
6.2.3. Localizing Internationalized Loggers, Messages and Exceptions
6.2.4. Customizing Internationalized Log Messages
6.2.5. Customizing Internationalized Exceptions
6.2.6. Reference
7. Enterprise JavaBeans
7.1. Introduction
7.1.1. Overview of Enterprise JavaBeans
7.1.2. EJB 3.1 Feature Set
7.1.3. EJB 3.1 Lite
7.1.4. EJB 3.1 Lite Features
7.1.5. Enterprise Beans
7.1.6. Overview of Writing Enterprise Beans
7.1.7. Session Bean Business Interfaces
7.2. Creating Enterprise Bean Projects
7.2.1. Create an EJB Archive Project Using JBoss Developer Studio
7.2.2. Create an EJB Archive Project in Maven
7.2.3. Create an EAR Project containing an EJB Project
7.2.4. Add a Deployment Descriptor to an EJB Project
7.3. Session Beans
7.3.1. Session Beans
7.3.2. Stateless Session Beans
7.3.3. Stateful Session Beans
7.3.4. Singleton Session Beans
7.3.5. Add Session Beans to a Project in JBoss Developer Studio
7.4. Message-Driven Beans
7.4.1. Message-Driven Beans
7.4.2. Resource Adapters
7.4.3. Create a JMS-based Message-Driven Bean in JBoss Developer Studio
7.5. Invoking Session Beans
7.5.1. Invoke a Session Bean Remotely using JNDI
7.5.2. About EJB Client Contexts
7.5.3. Considerations When Using a Single EJB Context
7.5.4. Using Scoped EJB Client Contexts
7.5.5. Configure EJBs Using a Scoped EJB Client Context
7.5.6. EJB Client Properties
7.6. Container Interceptors
7.6.1. About Container Interceptors
7.6.2. Create a Container Interceptor Class
7.6.3. Configure a Container Interceptor
7.6.4. Change the Security Context Identity
7.6.5. Pass Additional Security For EJB Authentication
7.6.6. Use a Client Side Interceptor in an Application
7.7. Clustered Enterprise JavaBeans
7.7.1. About Clustered Enterprise JavaBeans (EJBs)
7.8. Reference
7.8.1. EJB JNDI Naming Reference
7.8.2. EJB Reference Resolution
7.8.3. Project dependencies for Remote EJB Clients
7.8.4. jboss-ejb3.xml Deployment Descriptor Reference
8. Clustering in Web Applications
8.1. Session Replication
8.1.1. About HTTP Session Replication
8.1.2. About the Web Session Cache
8.1.3. Configure the Web Session Cache
8.1.4. Enable Session Replication in Your Application
8.2. HttpSession Passivation and Activation
8.2.1. About HTTP Session Passivation and Activation
8.2.2. Configure HttpSession Passivation in Your Application
8.3. Cookie Domain
8.3.1. About the Cookie Domain
8.3.2. Configure the Cookie Domain
8.4. Implement an HA Singleton
9. CDI
9.1. Overview of CDI
9.1.1. Overview of CDI
9.1.2. About Contexts and Dependency Injection (CDI)
9.1.3. Benefits of CDI
9.1.4. About Type-safe Dependency Injection
9.1.5. Relationship Between Weld, Seam 2, and JavaServer Faces
9.2. Use CDI
9.2.1. First Steps
9.2.2. Use CDI to Develop an Application
9.2.3. Ambiguous or Unsatisfied Dependencies
9.2.4. Managed Beans
9.2.5. Contexts, Scopes, and Dependencies
9.2.6. Bean Lifecycle
9.2.7. Named Beans and Alternative Beans
9.2.8. Stereotypes
9.2.9. Observer Methods
9.2.10. Interceptors
9.2.11. About Decorators
9.2.12. About Portable Extensions
9.2.13. Bean Proxies
10. Java Transaction API (JTA)
10.1. Overview
10.1.1. Overview of Java Transactions API (JTA)
10.2. Transaction Concepts
10.2.1. About Transactions
10.2.2. About ACID Properties for Transactions
10.2.3. About the Transaction Coordinator or Transaction Manager
10.2.4. About Transaction Participants
10.2.5. About Java Transactions API (JTA)
10.2.6. About Java Transaction Service (JTS)
10.2.7. About XA Datasources and XA Transactions
10.2.8. About XA Recovery
10.2.9. About the 2-Phase Commit Protocol
10.2.10. About Transaction Timeouts
10.2.11. About Distributed Transactions
10.2.12. About the ORB Portability API
10.2.13. About Nested Transactions
10.3. Transaction Optimizations
10.3.1. Overview of Transaction Optimizations
10.3.2. About the LRCO Optimization for Single-phase Commit (1PC)
10.3.3. About the Presumed-Abort Optimization
10.3.4. About the Read-Only Optimization
10.4. Transaction Outcomes
10.4.1. About Transaction Outcomes
10.4.2. About Transaction Commit
10.4.3. About Transaction Roll-Back
10.4.4. About Heuristic Outcomes
10.4.5. JBoss Transactions Errors and Exceptions
10.5. Overview of JTA Transactions
10.5.1. About Java Transactions API (JTA)
10.5.2. Lifecycle of a JTA Transaction
10.6. Transaction Subsystem Configuration
10.6.1. Transactions Configuration Overview
10.6.2. Transactional Datasource Configuration
10.6.3. Transaction Logging
10.7. Use JTA Transactions
10.7.1. Transactions JTA Task Overview
10.7.2. Control Transactions
10.7.3. Begin a Transaction
10.7.4. Nest Transactions
10.7.5. Commit a Transaction
10.7.6. Roll Back a Transaction
10.7.7. Handle a Heuristic Outcome in a Transaction
10.7.8. Transaction Timeouts
10.7.9. JTA Transaction Error Handling
10.8. ORB Configuration
10.8.1. About Common Object Request Broker Architecture (CORBA)
10.8.2. Configure the ORB for JTS Transactions
10.9. Transaction References
10.9.1. JBoss Transactions Errors and Exceptions
10.9.2. JTA Clustering Limitations
10.9.3. JTA Transaction Example
10.9.4. API Documentation for JBoss Transactions JTA
11. Hibernate
11.1. About Hibernate Core
11.2. Java Persistence API (JPA)
11.2.1. About JPA
11.2.2. Hibernate EntityManager
11.2.3. Getting Started
11.2.4. Configuration
11.2.5. Second-Level Caches
11.3. Hibernate Annotations
11.3.1. Hibernate Annotations
11.4. Hibernate Query Language
11.4.1. About Hibernate Query Language
11.4.2. HQL Statements
11.4.3. About the INSERT Statement
11.4.4. About the FROM Clause
11.4.5. About the WITH Clause
11.4.6. About Bulk Update, Insert and Delete
11.4.7. About Collection Member References
11.4.8. About Qualified Path Expressions
11.4.9. About Scalar Functions
11.4.10. HQL Standardized Functions
11.4.11. About the Concatenation Operation
11.4.12. About Dynamic Instantiation
11.4.13. About HQL Predicates
11.4.14. About Relational Comparisons
11.4.15. About the IN Predicate
11.4.16. About HQL Ordering
11.5. Hibernate Services
11.5.1. About Hibernate Services
11.5.2. About Service Contracts
11.5.3. Types of Service Dependencies
11.5.4. The ServiceRegistry
11.5.5. Custom Services
11.5.6. The Bootstrap Registry
11.5.7. The SessionFactory Registry
11.5.8. Integrators
11.6. Bean Validation
11.6.1. About Bean Validation
11.6.2. Hibernate Validator
11.6.3. Validation Constraints
11.6.4. Configuration
11.7. Envers
11.7.1. About Hibernate Envers
11.7.2. About Auditing Persistent Classes
11.7.3. Auditing Strategies
11.7.4. Getting Started with Entity Auditing
11.7.5. Configuration
11.7.6. Queries
12. JAX-RS Web Services
12.1. About JAX-RS
12.2. About RESTEasy
12.3. About RESTful Web Services
12.4. RESTEasy Defined Annotations
12.5. RESTEasy Configuration
12.5.1. RESTEasy Configuration Parameters
12.6. JAX-RS Web Service Security
12.6.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service
12.6.2. Secure a JAX-RS Web Service using Annotations
12.7. RESTEasy Logging
12.7.1. About JAX-RS Web Service Logging
12.7.2. Configure a Log Category in the Management Console
12.7.3. Logging Categories Defined in RESTEasy
12.8. Exception Handling
12.8.1. Create an Exception Mapper
12.8.2. RESTEasy Internally Thrown Exceptions
12.9. RESTEasy Interceptors
12.9.1. Intercept JAX-RS Invocations
12.9.2. Bind an Interceptor to a JAX-RS Method
12.9.3. Register an Interceptor
12.9.4. Interceptor Precedence Families
12.10. String Based Annotations
12.10.1. Convert String Based @*Param Annotations to Objects
12.11. Configure File Extensions
12.11.1. Map File Extensions to Media Types in the web.xml File
12.11.2. Map File Extensions to Languages in the web.xml File
12.11.3. RESTEasy Supported Media Types
12.12. RESTEasy JavaScript API
12.12.1. About the RESTEasy JavaScript API
12.12.2. Enable the RESTEasy JavaScript API Servlet
12.12.3. RESTEasy Javascript API Parameters
12.12.4. Build AJAX Queries with the JavaScript API
12.12.5. REST.Request Class Members
12.13. RESTEasy Asynchronous Job Service
12.13.1. About the RESTEasy Asynchronous Job Service
12.13.2. Enable the Asynchronous Job Service
12.13.3. Configure Asynchronous Jobs for RESTEasy
12.13.4. Asynchronous Job Service Configuration Parameters
12.14. RESTEasy JAXB
12.14.1. Create a JAXB Decorator
12.15. RESTEasy Atom Support
12.15.1. About the Atom API and Provider
13. JAX-WS Web Services
13.1. About JAX-WS Web Services
13.2. Configure the webservices Subsystem
13.3. JAX-WS Web Service Endpoints
13.3.1. About JAX-WS Web Service Endpoints
13.3.2. Write and Deploy a JAX-WS Web Service Endpoint
13.4. JAX-WS Web service Clients
13.4.1. Consume and Access a JAX-WS Web Service
13.4.2. Develop a JAX-WS Client Application
13.5. JAX-WS Development Reference
13.5.1. Enable Web Services Addressing (WS-Addressing)
13.5.2. JAX-WS Common API Reference
14. Identity Within Applications
14.1. Foundational Concepts
14.1.1. About Encryption
14.1.2. About Security Domains
14.1.3. About SSL Encryption
14.1.4. About Declarative Security
14.2. Role-Based Security in Applications
14.2.1. About Application Security
14.2.2. About Authentication
14.2.3. About Authorization
14.2.4. About Security Auditing
14.2.5. About Security Mapping
14.2.6. About the Security Extension Architecture
14.2.7. Java Authentication and Authorization Service (JAAS)
14.2.8. About Java Authentication and Authorization Service (JAAS)
14.2.9. Use a Security Domain in Your Application
14.2.10. Use Role-Based Security In Servlets
14.2.11. Use A Third-Party Authentication System In Your Application
14.3. Security Realms
14.3.1. About Security Realms
14.3.2. Add a New Security Realm
14.3.3. Add a User to a Security Realm
14.4. EJB Application Security
14.4.1. Security Identity
14.4.2. EJB Method Permissions
14.4.3. EJB Security Annotations
14.4.4. Remote Access to EJBs
14.5. JAX-RS Application Security
14.5.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service
14.5.2. Secure a JAX-RS Web Service using Annotations
14.6. Secure Remote Password Protocol
14.6.1. About Secure Remote Password Protocol (SRP)
14.6.2. Configure Secure Remote Password (SRP) Protocol
14.7. Password Vaults for Sensitive Strings
14.7.1. About Securing Sensitive Strings in Clear-Text Files
14.7.2. Create a Java Keystore to Store Sensitive Strings
14.7.3. Mask the Keystore Password and Initialize the Password Vault
14.7.4. Configure JBoss EAP 6 to Use the Password Vault
14.7.5. Store and Retrieve Encrypted Sensitive Strings in the Java Keystore
14.7.6. Store and Resolve Sensitive Strings In Your Applications
14.8. Java Authorization Contract for Containers (JACC)
14.8.1. About Java Authorization Contract for Containers (JACC)
14.8.2. Configure Java Authorization Contract for Containers (JACC) Security
14.9. Java Authentication SPI for Containers (JASPI)
14.9.1. About Java Authentication SPI for Containers (JASPI) Security
14.9.2. Configure Java Authentication SPI for Containers (JASPI) Security
15. Single Sign On (SSO)
15.1. About Single Sign On (SSO) for Web Applications
15.2. About Clustered Single Sign On (SSO) for Web Applications
15.3. Choose the Right SSO Implementation
15.4. Use Single Sign On (SSO) In A Web Application
15.5. About Kerberos
15.6. About SPNEGO
15.7. About Microsoft Active Directory
15.8. Configure Kerberos or Microsoft Active Directory Desktop SSO for Web Applications
16. Development Security References
16.1. jboss-web.xml Configuration Reference
16.2. EJB Security Parameter Reference
17. Supplemental References
17.1. Types of Java Archives
A. Revision History

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog-box text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For example:
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above: username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled “Important” will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. Getting Help and Giving Feedback

2.1. Do You Need Help?

If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can:
  • search or browse through a knowledgebase of technical support articles about Red Hat products.
  • submit a support case to Red Hat Global Support Services (GSS).
  • access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.

2.2. Give us Feedback

If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product JBoss Enterprise Application Platform 6 and the component doc-Development_Guide. The following link will take you to a pre-filled bug report for this product: https://bugzilla.redhat.com/.
Fill out the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly.
Document URL:


Section Number and Name:


Describe the issue:


Suggestions for improvement:


Additional information:


Be sure to give us your name so that you can receive full credit for reporting the issue.

Chapter 1. Get Started Developing Applications

1.1. Introduction

1.1.1. About Red Hat JBoss Enterprise Application Platform 6 (JBoss EAP 6)

Red Hat JBoss Enterprise Application Platform 6 (JBoss EAP 6) is a fast, secure, powerful middleware platform built upon open standards, and compliant with the Java Enterprise Edition 6 specification. It integrates JBoss Application Server 7 with high-availability clustering, powerful messaging, distributed caching, and other technologies to create a stable and scalable platform.
The new modular structure allows for services to be enabled only when required, significantly increasing start up speed. The Management Console and Management Command Line Interface remove the need to edit XML configuration files by hand, adding the ability to script and automate tasks. In addition, it includes APIs and development frameworks that can be used to develop secure, powerful, and scalable Java EE applications quickly.

1.1.2. About the Use of EAP_HOME in this Document

In this document, the variable EAP_HOME is used to denote the path to the JBoss EAP 6 installation. Replace this variable with the actual path to your JBoss EAP 6 installation.

1.2. Prerequisites

1.2.1. Become Familiar with Java Enterprise Edition 6

1.2.1.1. Overview of EE 6 Profiles

Java Enterprise Edition 6 (EE 6) includes support for multiple profiles, or subsets of APIs. The only two profiles that the EE 6 specification defines are the Full Profile and the Web Profile.
EE 6 Full Profile includes all APIs and specifications included in the EE 6 specification. EE 6 Web Profile includes a subset of APIs which are useful to web developers.
JBoss EAP 6 is a certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications.

1.2.1.2. Java Enterprise Edition 6 Web Profile

The Web Profile is one of two profiles defined by the Java Enterprise Edition 6 specification. It is designed for web application development. The other profile defined by the Java Enterprise Edition 6 specification is the Full Profile. See Section 1.2.1.3, “Java Enterprise Edition 6 Full Profile” for more details.

Java EE 6 Web Profile Requirements

  • Java Platform, Enterprise Edition 6
  • Java Web Technologies

    • Servlet 3.0 (JSR 315)
    • JSP 2.2 and Expression Language (EL) 1.2
    • JavaServer Faces (JSF) 2.0 (JSR 314)
    • Java Standard Tag Library (JSTL) for JSP 1.2
    • Debugging Support for Other Languages 1.0 (JSR 45)
  • Enterprise Application Technologies

    • Contexts and Dependency Injection (CDI) (JSR 299)
    • Dependency Injection for Java (JSR 330)
    • Enterprise JavaBeans 3.1 Lite (JSR 318)
    • Java Persistence API 2.0 (JSR 317)
    • Common Annotations for the Java Platform 1.1 (JSR 250)
    • Java Transaction API (JTA) 1.1 (JSR 907)
    • Bean Validation (JSR 303)

1.2.1.3. Java Enterprise Edition 6 Full Profile

The Java Enterprise Edition 6 (EE 6) specification defines a concept of profiles, and defines two of them as part of the specification. Besides the items supported in the Java Enterprise Edition 6 Web Profile ( Section 1.2.1.2, “Java Enterprise Edition 6 Web Profile”), the Full Profile supports the following APIs. JBoss Enterprise Edition 6 supports the Full Profile.

Items Included in the EE 6 Full Profile

  • EJB 3.1 (not Lite) (JSR 318)
  • Java EE Connector Architecture 1.6 (JSR 322)
  • Java Message Service (JMS) API 1.1 (JSR 914)
  • JavaMail 1.4 (JSR 919)
  • Web Service Technologies

    • Jax-RS RESTful Web Services 1.1 (JSR 311)
    • Implementing Enterprise Web Services 1.3 (JSR 109)
    • JAX-WS Java API for XML-Based Web Services 2.2 (JSR 224)
    • Java Architecture for XML Binding (JAXB) 2.2 (JSR 222)
    • Web Services Metadata for the Java Platform (JSR 181)
    • Java APIs for XML-based RPC 1.1 (JSR 101)
    • Java APIs for XML Messaging 1.3 (JSR 67)
    • Java API for XML Registries (JAXR) 1.0 (JSR 93)
  • Management and Security Technologies

    • Java Authentication Service Provider Interface for Containers 1.0 (JSR 196)
    • Java Authentication Contract for Containers 1.3 (JSR 115)
    • Java EE Application Deployment 1.2 (JSR 88)
    • J2EE Management 1.1 (JSR 77)

1.2.2. About Modules and the New Modular Class Loading System used in JBoss EAP 6

1.2.2.1. Modules

A Module is a logical grouping of classes used for class loading and dependency management. JBoss EAP 6 identifies two different types of modules, sometimes called static and dynamic modules. However the only difference between the two is how they are packaged. All modules provide the same features.
Static Modules
Static Modules are predefined in the EAP_HOME/modules/ directory of the application server. Each sub-directory represents one module and contains one or more JAR files and a configuration file (module.xml). The name of the module is defined in the module.xml file. All the application server provided APIs are provided as static modules, including the Java EE APIs as well as other APIs such as JBoss Logging.

Example 1.1. Example module.xml file

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.1.15.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>


The module name, com.mysql, should match the directory structure for the module.

Creating custom static modules can be useful if many applications are deployed on the same server that use the same third party libraries. Instead of bundling those libraries with each application, a module containing these libraries can be created and installed by the JBoss administrator. The applications can then declare an explicit dependency on the custom static modules.
Dynamic Modules
Dynamic Modules are created and loaded by the application server for each JAR or WAR deployment (or subdeployment in an EAR). The name of a dynamic module is derived from the name of the deployed archive. Because deployments are loaded as modules, they can configure dependencies and be used as dependencies by other deployments.
Modules are only loaded when required. This usually only occurs when an application is deployed that has explicit or implicit dependencies.

1.2.2.2. Overview of Class Loading and Modules

JBoss EAP 6 uses a new modular class loading system for controlling the class paths of deployed applications. This system provides more flexibility and control than the traditional system of hierarchical class loaders. Developers have fine-grained control of the classes available to their applications, and can configure a deployment to ignore classes provided by the application server in favour of their own.
The modular class loader separates all Java classes into logical groups called modules. Each module can define dependencies on other modules in order to have the classes from that module added to its own class path. Because each deployed JAR and WAR file is treated as a module, developers can control the contents of their application's class path by adding module configuration to their application.
The following material covers what developers need to know to successfully build and deploy applications on JBoss EAP 6.

1.3. Set Up the Development Environment

1.3.1. Download and Install JBoss Developer Studio

1.3.1.2. Download JBoss Developer Studio 5

  1. Select DownloadsRed Hat JBoss MiddlewareDownloads.
  2. Select JBoss Developer Studio from the dropbox.
  3. Select the appropriate version and click Download.

1.3.1.3. Install JBoss Developer Studio 5

Procedure 1.1. Install JBoss Developer Studio 5

  1. Open a terminal.
  2. Move into the directory containing the downloaded .jar file.
  3. Run the following command to launch the GUI installer:
    java -jar jbdevstudio-build_version.jar
  4. Click Next to start the installation process.
  5. Select I accept the terms of this license agreement and click Next.
  6. Adjust the installation path and click Next.

    Note

    If the installation path folder does not exist, a prompt will appear. Click Ok to create the folder.
  7. Choose a JVM, or leave the default JVM selected, and click Next.
  8. Add any application platforms available, and click Next.
  9. Review the installation details, and click Next.
  10. Click Next when the installation process is complete.
  11. Configure the desktop shortcuts for JBoss Developer Studio, and click Next.
  12. Click Done.

1.3.1.4. Start JBoss Developer Studio

Procedure 1.2. Command to start JBoss Developer Studio

  1. Open a terminal.
  2. Change into the installation directory.
  3. Run the following command to start the JBoss Developer Studio:
    [localhost]$ ./jbdevstudio

1.3.1.5. Add the JBoss EAP 6 Server to JBoss Developer Studio

These instructions assume this is your first introduction to JBoss Developer Studio and you have not yet added any JBoss EAP 6 servers.

Procedure 1.3. Add the server

  1. Open the Servers tab. If there is no Servers tab, add it to the panel as follows:
    1. Click WindowShow ViewOther....
    2. Select Servers from the Server folder and click OK.
  2. Click on the new server wizard link or right click within the blank Server panel and select NewServer.
    Add a new server - No servers available

    Figure 1.1. Add a new server - No servers available


  3. Expand JBoss Enterprise Middleware and choose JBoss Enterprise Application Platform 6.x.Then click Next.
    Choose server type

    Figure 1.2. Choose server type


  4. Click Browse and navigate to your JBoss EAP 6 install location. Then click Next.
    Browse to server install

    Figure 1.3. Browse to server install


  5. On this screen you define the server behavior. You can start the server manually or let JBoss Developer Studio manage it for you. You can also define a remote server for deployment and determine if you want to expose the management port for that server, for example, if you need connect to it using JMX. In this example, we assume the server is local and you want JBoss Developer Studio to manage your server so you do not need to check anything. Click Next.
    Define the new JBoss server behavior

    Figure 1.4. Define the new JBoss server behavior


  6. This screen allows you to configure existing projects for the new server. Because you do not have any projects at this point, click Finish.
    Modify resources for the new JBoss server

    Figure 1.5. Modify resources for the new JBoss server


Result
The JBoss Enterprise Application Server 6.0 Runtime Server is listed in the Servers tab.
Server appears in the server list

Figure 1.6. Server appears in the server list


1.4. Run Your First Application

1.4.1. Replace the Default Welcome Web Application

JBoss EAP 6 includes a Welcome application, which displays when you open the URL of the server at port 8080. You can replace this application with your own web application by following this procedure.

Procedure 1.4. Replace the Default Welcome Web Application With Your Own Web Application

  1. Disable the Welcome application.

    Use the Management CLI script EAP_HOME/bin/jboss-cli.sh to run the following command. You may need to change the profile to modify a different managed domain profile, or remove the /profile=default portion of the command for a standalone server.
    /profile=default/subsystem=web/virtual-server=default-host:write-attribute(name=enable-welcome-root,value=false)
  2. Configure your Web application to use the root context.

    To configure your web application to use the root context (/) as its URL address, modify its jboss-web.xml, which is located in the META-INF/ or WEB-INF/ directory. Replace its <context-root> directive with one that looks like the following.
    <jboss-web>
        <context-root>/</context-root>
    </jboss-web>		
    		
    
    
    
  3. Deploy your application.

    Deploy your application to the server group or server you modified in the first step. The application is now available on http://SERVER_URL:PORT/.

1.4.2. Download the Quickstart Code Examples

1.4.2.1. Access the Quickstarts

Summary
JBoss EAP 6 comes with a series of quickstart examples designed to help users begin writing applications using the Java EE 6 technologies.

Procedure 1.5. Download the Quickstarts

  1. Find "Quickstarts" in the list.
  2. Click the Download button to download a Zip archive containing the examples.
  3. Unzip the archive in a directory of your choosing.
Result
The JBoss EAP Quickstarts have been downloaded and unzipped. Refer to the README.md file in the top-level directory of the Quickstart archive for instructions about deploying each quickstart.

1.4.3. Run the Quickstarts

1.4.3.1. Run the Quickstarts in JBoss Developer Studio

Procedure 1.6. Import the quickstarts into JBoss Developer Studio

Each quickstart ships with a POM (Project Object Model) file that contains project and configuration information for the quickstart. Using this POM file, you can easily import the quickstart into JBoss Developer Studio.
  1. Start JBoss Developer Studio.
  2. From the menu, select FileImport.
  3. In the selection list, choose MavenExisting Maven Projects, then click Next.
    Import Existing Maven Projects

    Figure 1.7. Import Existing Maven Projects


  4. Browse to the directory of the quickstart you want to import and click OK. The Projects list box will be populated with the pom.xml file of the selected quickstart project.
    Select Maven Projects

    Figure 1.8. Select Maven Projects


  5. Click Next, then click Finish.

Procedure 1.7. Build and Deploy the helloworld quickstart

The helloworld quickstart is one of the simplest quickstarts and is a good way to verify that the JBoss server is configured and running correctly.
  1. Open the Servers tab. To add it to the panel:
    1. Click WindowShow ViewOther....
    2. Select Servers from the Server folder and click Ok.
  2. Right click on helloworld in the Project Explorer tab, and select Run AsRun on Server.
  3. Select the JBoss EAP 6.0 Runtime Server server and click Next. This should deploy the helloworld quickstart to the JBoss server.
  4. To verify that the helloworld quickstart was deployed successfully to the JBoss server, open a web browser and access the application at this URL: http://localhost:8080/jboss-as-helloworld

1.4.3.2. Run the Quickstarts Using a Command Line

Procedure 1.8. Build and Deploy the Quickstarts Using a Command Line

You can easily build and deploy the quickstarts using a command line. Be aware that, when using a command line, you are responsible for starting the JBoss server if it is required.
  1. Review the README file in the root directory of the quickstarts.

    This file contains general information about system requirements, how to configure Maven, how to add users, and how to run the Quickstarts. Be sure to read through it before you get started.
    It also contains a table listing the available quickstarts. The table lists each quickstart name and the technologies it demonstrates. It gives a brief description of each quickstart and the level of experience required to set it up. For more detailed information about a quickstart, click on the quickstart name.
    Some quickstarts are designed to enhance or extend other quickstarts. These are noted in the Prerequisites column. If a quickstart lists prerequisites, you must install them first before working with the quickstart.
    Some quickstarts require the installation and configuration of optional components. Do not install these components unless the quickstart requires them.
  2. Run the helloworld quickstart.

    The helloworld quickstart is one of the simplest quickstarts and is a good way to verify that the JBoss server is configured and running correctly. Open the README file in the root of the helloworld quickstart. It contains detailed instructions on how to build and deploy the quickstart and access the running application
  3. Run the other quickstarts.

    Follow the instructions in the README file located in the root folder of each quickstart to run the example.

1.4.4. Review the Quickstart Tutorials

1.4.4.1. Explore the helloworld Quickstart

Summary
The helloworld quickstart shows you how to deploy a simple Servlet to JBoss EAP 6. The business logic is encapsulated in a service which is provided as a CDI (Contexts and Dependency Injection) bean and injected into the Servlet. This quickstart is very simple. All it does is print "Hello World" onto a web page. It is a good starting point to make sure you have configured and started your server properly.
Detailed instructions to build and deploy this quickstart using a command line can be found in the README file at the root of the helloworld quickstart directory. Here we show you how to use JBoss Developer Studio to run the quickstart.

Procedure 1.9. Import the helloworld quickstart into JBoss Developer Studio

If you previously imported all of the quickstarts into JBoss Developer Studio following the steps here Section 1.4.3.1, “Run the Quickstarts in JBoss Developer Studio”, you can skip to the next section.
  1. From the menu, select FileImport.
  2. In the selection list, choose MavenExisting Maven Projects, then click Next.
    Import Existing Maven Projects

    Figure 1.9. Import Existing Maven Projects


  3. Browse to the QUICKSTART_HOME/quickstart/helloworld/ directory and click OK. The Projects list box is populated with the pom.xml file from the helloworld quickstart project.
    Select Maven Projects

    Figure 1.10. Select Maven Projects


  4. Click Finish.

Procedure 1.10. Build and Deploy the helloworld quickstart

  1. If you have not yet configured JBoss Developer Studio for JBoss EAP 6, you must Section 1.3.1.5, “Add the JBoss EAP 6 Server to JBoss Developer Studio”.
  2. Right click on jboss-as-helloworld in the Project Explorer tab, and select Run AsRun on Server.
    Run on Server

    Figure 1.11. Run on Server


  3. Select the JBoss EAP 6.0 Runtime Server server and click Next. This deploys the helloworld quickstart to the JBoss server.
  4. To verify that the helloworld quickstart was deployed successfully to the JBoss server, open a web browser and access the application at this URL: http://localhost:8080/jboss-as-helloworld

Procedure 1.11. Examine the Directory Structure

The code for the helloworld quickstart can be found in the QUICKSTART_HOME/helloworld directory. The helloworld quickstart is comprised a Servlet and a CDI bean. It also includes an empty beans.xml file which tells JBoss EAP 6 to look for beans in this application and to activate the CDI.
  1. The beans.xml file is located in the WEB-INF/ folder in the src/main/webapp/ directory of the quickstart.
  2. The src/main/webapp/ directory also includes an index.html file which uses a simple meta refresh to redirect the user's browser to the Servlet, which is located at http://localhost:8080/jboss-as-helloworld/HelloWorld.
  3. All the configuration files for this example are located in WEB-INF/, which can be found in the src/main/webapp/ directory of the example.
  4. Notice that the quickstart doesn't even need a web.xml file!

Procedure 1.12. Examine the Code

The package declaration and imports have been excluded from these listings. The complete listing is available in the quickstart source code.
  1. Review the HelloWorldServlet code

    The HelloWorldServlet.java file is located in the src/main/java/org/jboss/as/quickstarts/helloworld/ directory. This Servlet sends the information to the browser.
    27. @WebServlet("/HelloWorld")
    28. public class HelloWorldServlet extends HttpServlet {
    29. 
    30.    static String PAGE_HEADER = "<html><head /><body>";
    31.
    32.    static String PAGE_FOOTER = "</body></html>";
    33.
    34.    @Inject
    35.    HelloService helloService;
    36.
    37.    @Override
    38.    protected void doGet(HttpServletRequest req, HttpServletResponse resp) 
                                 throws ServletException, IOException {
    39.       PrintWriter writer = resp.getWriter();
    40.       writer.println(PAGE_HEADER);
    41.       writer.println("<h1>" + helloService.createHelloMessage("World") + "</h1>");
    42.       writer.println(PAGE_FOOTER);
    43.       writer.close();
    44.     }
    45. 
    46. }
    
    
    

    Table 1.1. HelloWorldServlet Details

    Line Note
    27 Before Java EE 6, an XML file was used to register Servlets. It is now much cleaner. All you need to do is add the @WebServlet annotation and provide a mapping to a URL used to access the servlet.
    30-32 Every web page needs correctly formed HTML. This quickstart uses static Strings to write the minimum header and footer output.
    34-35 These lines inject the HelloService CDI bean which generates the actual message. As long as we don't alter the API of HelloService, this approach allows us to alter the implementation of HelloService at a later date without changing the view layer.
    41 This line calls into the service to generate the message "Hello World", and write it out to the HTTP request.

  2. Review the HelloService code

    The HelloService.java file is located in the src/main/java/org/jboss/as/quickstarts/helloworld/ directory. This service is very simple. It returns a message. No XML or annotation registration is required.
     9. public class HelloService {
    10. 
    11.    String createHelloMessage(String name) {
    12.       return "Hello " + name + "!"; 
    32.    }
    33. }
    34.  
    
    
    

1.4.4.2. Explore the numberguess Quickstart

Summary
This quickstart shows you how to create and deploy a simple application to JBoss EAP 6. This application does not persist any information. Information is displayed using a JSF view, and business logic is encapsulated in two CDI (Contexts and Dependency Injection) beans. In the numberguess quickstart, you get 10 attempts to guess a number between 1 and 100. After each attempt, you're told whether your guess was too high or too low.
The code for the numberguess quickstart can be found in the QUICKSTART_HOME/numberguess directory. The numberguess quickstart is comprised of a number of beans, configuration files and Facelets (JSF) views, packaged as a WAR module.
Detailed instructions to build and deploy this quickstart using a command line can be found in the README file at the root of the numberguess quickstart directory. Here we show you how to use JBoss Developer Studio to run the quickstart.

Procedure 1.13. Import the numberguess quickstart into JBoss Developer Studio

If you previously imported all of the quickstarts into JBoss Developer Studio following the steps in the following procedure, Section 1.4.3.1, “Run the Quickstarts in JBoss Developer Studio”, you can skip to the next section.
  1. If you have not done so, perform the following procedures: Section 1.3.1.3, “Install JBoss Developer Studio 5”
  2. From the menu, select FileImport.
  3. In the selection list, choose MavenExisting Maven Projects, then click Next.
    Import Existing Maven Projects

    Figure 1.12. Import Existing Maven Projects


  4. Browse to the QUICKSTART_HOME/quickstart/numberguess/ directory and click OK. The Projects list box is populated with the pom.xml file from the numberguess quickstart project.
  5. Click Finish.

Procedure 1.14. Build and Deploy the numberguess quickstart

  1. If you have not yet configured JBoss Developer Studio for JBoss EAP 6, you must do the following: Section 1.3.1.5, “Add the JBoss EAP 6 Server to JBoss Developer Studio”.
  2. Right click on jboss-as-numberguess in the Project Explorer tab, and select Run AsRun on Server.
  3. Select the JBoss EAP 6.0 Runtime Server server and click Next. This deploys the numberguess quickstart to the JBoss server.
  4. To verify that the numberguess quickstart was deployed successfully to the JBoss server, open a web browser and access the application at this URL: http://localhost:8080/jboss-as-numberguess

Procedure 1.15. Examine the Configuration Files

All the configuration files for this example are located in WEB-INF/ directory which can be found in the src/main/webapp/ directory of the quickstart.
  1. Examine the faces-config file

    This quickstart uses the JSF 2.0 version of faces-config.xml filename. A standardized version of Facelets is the default view handler in JSF 2.0, so there's really nothing that you have to configure. JBoss EAP 6 goes above and beyond Java EE here. It will automatically configure the JSF for you if you include this configuration file. As a result, the configuration consists of only the root element:
    03. <faces-config version="2.0"
    04.    xmlns="http://java.sun.com/xml/ns/javaee"
    05.    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    06.    xsi:schemaLocation="
    07.       http://java.sun.com/xml/ns/javaee>
    08.       http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd">
    09.      
    10. </faces-config>
    
    
    
  2. Examine the beans.xml file

    There's also an empty beans.xml file, which tells JBoss EAP 6 to look for beans in this application and to activate the CDI.
  3. There is no web.xml file

    Notice that the quickstart doesn't even need a web.xml file!

Procedure 1.16. Examine the JSF Code

JSF uses the .xhtml file extension for source files, but serves up the rendered views with the .jsf extension.
  • Examine the home.xhtml code

    The home.xhtml file is located in the src/main/webapp/ directory.
    03. <html xmlns="http://www.w3.org/1999/xhtml"
    04.    xmlns:ui="http://java.sun.com/jsf/facelets"
    05.    xmlns:h="http://java.sun.com/jsf/html"
    06.    xmlns:f="http://java.sun.com/jsf/core">
    07.
    08. <head>
    09. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
    10. <title>Numberguess</title>
    11. </head>
    12.
    13. <body>
    14.    <div id="content">
    15.       <h1>Guess a number...</h1>
    16.       <h:form id="numberGuess">
    17.
    18.          <!-- Feedback for the user on their guess -->
    19.          <div style="color: red">
    20.             <h:messages id="messages" globalOnly="false" />
    21.             <h:outputText id="Higher" value="Higher!"
    22.                rendered="#{game.number gt game.guess and game.guess ne 0}" />
    23.             <h:outputText id="Lower" value="Lower!"
    24.                rendered="#{game.number lt game.guess and game.guess ne 0}" />
    25.          </div>
    26.
    27.          <!-- Instructions for the user -->
    28.          <div>
    29.             I'm thinking of a number between <span
    30.                id="numberGuess:smallest">#{game.smallest}</span> and <span
    31.                id="numberGuess:biggest">#{game.biggest}</span>. You have
    32.             #{game.remainingGuesses} guesses remaining.
    33.          </div>
    34.
    35.          <!-- Input box for the users guess, plus a button to submit, and reset -->
    36.          <!-- These are bound using EL to our CDI beans -->
    37.          <div>
    38.             Your guess:
    39.             <h:inputText id="inputGuess" value="#{game.guess}"
    40.                required="true" size="3"
    41.                disabled="#{game.number eq game.guess}"
    42.                validator="#{game.validateNumberRange}" />
    43.             <h:commandButton id="guessButton" value="Guess"
    44.                action="#{game.check}"
    45.                disabled="#{game.number eq game.guess}" />
    46.          </div>
    47.          <div>
    48.             <h:commandButton id="restartButton" value="Reset"
    49.                action="#{game.reset}" immediate="true" />
    50.          </div>
    51.       </h:form>
    52.
    53.    </div>
    54.
    55.    <br style="clear: both" />
    56.
    57. </body>
    58. </html>
    
    
    

    Table 1.2. JSF Details

    Line Note
    20-24 These are the messages which can be sent to the user: "Higher!" and "Lower!"
    29-32 As the user guesses, the range of numbers they can guess gets smaller. This sentence changes to make sure they know the number range of a valid guess.
    38-42 This input field is bound to a bean property using a value expression.
    42 A validator binding is used to make sure the user does not accidentally input a number outside of the range in which they can guess. If the validator was not here, the user might use up a guess on an out of bounds number.
    43-45 There must be a way for the user to send their guess to the server. Here we bind to an action method on the bean.

Procedure 1.17. Examine the Class Files

All of the numberguess quickstart source files can be found in the src/main/java/org/jboss/as/quickstarts/numberguess/ directory. The package declaration and imports have been excluded from these listings. The complete listing is available in the quickstart source code.
  1. Review the Random.java qualifier code

    A qualifier is used to remove ambiguity between two beans, both of which are eligible for injection based on their type. For more information on qualifiers, refer to Section 9.2.3.3, “Use a Qualifier to Resolve an Ambiguous Injection”
    The @Random qualifier is used for injecting a random number.
    21. @Target({ TYPE, METHOD, PARAMETER, FIELD })
    22. @Retention(RUNTIME)
    23. @Documented
    24. @Qualifier
    25. public @interface Random {
    26.
    27. }
    
    
    
  2. Review the MaxNumber.java qualifier code

    The @MaxNumberqualifier is used for injecting the maximum number allowed.
    21. @Target({ TYPE, METHOD, PARAMETER, FIELD })
    22. @Retention(RUNTIME)
    23. @Documented
    24. @Qualifier
    25. public @interface MaxNumber {
    26.
    27. }
    
    
    
  3. Review the Generator code

    The Generator class is responsible for creating the random number via a producer method. It also exposes the maximum possible number via a producer method. This class is application scoped so you don't get a different random each time.
    28. @ApplicationScoped
    29. public class Generator implements Serializable {
    30.    private static final long serialVersionUID = -7213673465118041882L;
    31.
    32.    private java.util.Random random = new java.util.Random(System.currentTimeMillis());
    33.
    34.    private int maxNumber = 100;
    35.
    36.    java.util.Random getRandom() {
    37.       return random;
    38.    }
    39.
    40.    @Produces
    41.    @Random
    42.    int next() {
    43.       // a number between 1 and 100
    44.       return getRandom().nextInt(maxNumber - 1) + 1;
    45.    }
    46.
    47.    @Produces
    48.    @MaxNumber
    49.    int getMaxNumber() {
    50.       return maxNumber;
    51.    }
    52. }
    
    
    
  4. Review the Game code

    The session scoped class Game is the primary entry point of the application. It is responsible for setting up or resetting the game, capturing and validating the user's guess, and providing feedback to the user with a FacesMessage. It uses the post-construct lifecycle method to initialize the game by retrieving a random number from the @Random Instance<Integer> bean.
    Notice the @Named annotation in the class. This annotation is only required when you want to make the bean accessible to a JSF view via Expression Language (EL), in this case #{game}.
    035. @Named
    036. @SessionScoped
    037. public class Game implements Serializable {
    038.
    039.    private static final long serialVersionUID = 991300443278089016L;
    040.
    041.    /**
    042.     * The number that the user needs to guess
    043.     */
    044.    private int number;
    045.
    046.    /**
    047.     * The users latest guess
    048.     */
    049.    private int guess;
    050.
    051.    /**
    052.     * The smallest number guessed so far (so we can track the valid guess range).
    053.     */
    054.    private int smallest;
    055.
    056.    /**
    057.     * The largest number guessed so far
    058.     */
    059.    private int biggest;
    060.
    061.    /**
    062.     * The number of guesses remaining
    063.     */
    064.    private int remainingGuesses;
    065.
    066.    /**
    067.     * The maximum number we should ask them to guess
    068.     */
    069.    @Inject
    070.    @MaxNumber
    071.    private int maxNumber;
    072.
    073.    /**
    074.     * The random number to guess
    075.     */
    076.    @Inject
    077.    @Random
    078.    Instance<Integer> randomNumber;
    079.
    080.    public Game() {
    081.    }
    082.
    083.    public int getNumber() {
    084.       return number;
    085.    }
    086.
    087.    public int getGuess() {
    088.       return guess;
    089.    }
    090.
    091.    public void setGuess(int guess) {
    092.       this.guess = guess;
    093.    }
    094.
    095.    public int getSmallest() {
    096.       return smallest;
    097.    }
    098.
    099.    public int getBiggest() {
    100.       return biggest;
    101.    }
    102.
    103.    public int getRemainingGuesses() {
    104.       return remainingGuesses;
    105.    }
    106.
    107.    /**
    108.     * Check whether the current guess is correct, and update the biggest/smallest guesses as needed.
    109.     * Give feedback to the user if they are correct.
    110.     */
    111.    public void check() {
    112.       if (guess > number) {
    113.          biggest = guess - 1;
    114.       } else if (guess < number) {
    115.          smallest = guess + 1;
    116.       } else if (guess == number) {
    117.          FacesContext.getCurrentInstance().addMessage(null, new FacesMessage("Correct!"));
    118.       }
    119.       remainingGuesses--;
    120.    }
    121.
    122.    /**
    123.     * Reset the game, by putting all values back to their defaults, and getting a new random number.
    124.     * We also call this method when the user starts playing for the first time using
    125.     * {@linkplain PostConstruct @PostConstruct} to set the initial values.
    126.     */
    127.    @PostConstruct
    128.    public void reset() {
    129.       this.smallest = 0;
    130.       this.guess = 0;
    131.       this.remainingGuesses = 10;
    132.       this.biggest = maxNumber;
    133.       this.number = randomNumber.get();
    134.    }
    135.
    136.    /**
    137.     * A JSF validation method which checks whether the guess is valid. It might not be valid because
    138.     * there are no guesses left, or because the guess is not in range.
    139.     *
    140.     */
    141.    public void validateNumberRange(FacesContext context, UIComponent toValidate, Object value) {
    142.       if (remainingGuesses <= 0) {
    143.          FacesMessage message = new FacesMessage("No guesses left!");
    144.          context.addMessage(toValidate.getClientId(context), message);
    145.          ((UIInput) toValidate).setValid(false);
    146.          return;
    147.       }
    148.       int input = (Integer) value;
    149.
    150.       if (input < smallest || input > biggest) {
    151.          ((UIInput) toValidate).setValid(false);
    152.
    153.          FacesMessage message = new FacesMessage("Invalid guess");
    154.          context.addMessage(toValidate.getClientId(context), message);
    155.       }
    156.    }
    157. }
    
    
    

Chapter 2. Maven Guide

2.1. Learn about Maven

2.1.1. About the Maven Repository

Apache Maven is a distributed build automation tool used in Java application development to create, manage, and build software projects. Maven uses standard configuration files called Project Object Model, or POM, files to define projects and manage the build process. POMs describe the module and component dependencies, build order, and targets for the resulting project packaging and output using an XML file. This ensures that the project is built in a correct and uniform manner.
Maven achieves this by using a repository. A Maven repository stores Java libraries, plug-ins, and other build artifacts. The default public repository is the Maven 2 Central Repository, but repositories can be private and internal within a company with a goal to share common artifacts among development teams. Repositories are also available from third-parties. JBoss EAP 6 includes a Maven repository that contains many of the requirements that Java EE developers typically use to build applications on JBoss EAP 6. To configure your project to use this repository, see Section 2.3.1, “Configure the JBoss EAP Maven Repository”.
A repository can be local or remote. Remote repositories are accessed using common protocols such as http:// for a repository on an HTTP server or file:// for a repository a file server. A local repository is a cached download of the artifacts from a remote repository.
For more information about Maven, see Welcome to Apache Maven.
For more information about Maven repositories, see Apache Maven Project - Introduction to Repositories.
For more information about Maven POM files, see the Apache Maven Project POM Reference and Section 2.1.2, “About the Maven POM File”.

2.1.2. About the Maven POM File

The Project Object Model, or POM, file is a configuration file used by Maven to build projects. It is an XML file that contains information about the project and how to build it, including the location of the source, test, and target directories, the project dependencies, plug-in repositories, and goals it can execute. It can also include additional details about the project including the version, description, developers, mailing list, license, and more. A pom.xml file requires some configuration options and will default all others. See Section 2.1.3, “Minimum Requirements of a Maven POM File” for details.
The schema for the pom.xml file can be found at http://maven.apache.org/maven-v4_0_0.xsd.
For more information about POM files, see the Apache Maven Project POM Reference.

2.1.3. Minimum Requirements of a Maven POM File

Minimum requirements
The minimum requirements of a pom.xml file are as follows:
  • project root
  • modelVersion
  • groupId - the id of the project's group
  • artifactId - the id of the artifact (project)
  • version - the version of the artifact under the specified group
Sample pom.xml file
A basic pom.xml file might look like this:
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.jboss.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1</version>
</project> 


2.1.4. About the Maven Settings File

The Maven settings.xml file contains user-specific configuration information for Maven. It contains information that should not be distributed with the pom.xml file, such as developer identity, proxy information, local repository location, and other settings specific to a user.
There are two locations where the settings.xml can be found.
In the Maven install
The settings file can be found in the M2_HOME/conf/ directory. These settings are referred to as global settings. The default Maven settings file is a template that can be copied and used as a starting point for the user settings file.
In the user's install
The settings file can be found in the USER_HOME/.m2/ directory. If both the Maven and user settings.xml files exist, the contents are merged. Where there are overlaps, the user's settings.xml file takes precedence.
The following is an example of a Maven settings.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">  
  <profiles>
    <!-- Configure the JBoss EAP Maven repository -->
    <profile>
      <id>jboss-eap-maven-repository</id>
      <repositories>
        <repository>
          <id>jboss-eap</id>
          <url>file:///path/to/repo/jboss-eap-6.0-maven-repository</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>jboss-eap-maven-plugin-repository</id>
          <url>file:///path/to/repo/jboss-eap-6.0-maven-repository</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <!-- Optionally, make the repository active by default -->
    <activeProfile>jboss-eap-maven-repository</activeProfile>
  </activeProfiles>
</settings>
      
The schema for the settings.xml file can be found at http://maven.apache.org/xsd/settings-1.0.0.xsd.

2.2. Install Maven and the JBoss Maven Repository

2.2.1. Download and Install Maven

  1. Go to Apache Maven Project - Download Maven and download the latest distribution for your operating system.
  2. See the Maven documentation for information on how to download and install Apache Maven for your operating system.

2.2.2. Install the JBoss EAP 6 Maven Repository

There are three ways to install the repository; on your local file system, on Apache Web Server, or with a Maven repository manager.

2.2.3. Install the JBoss EAP 6 Maven Repository Locally

Summary
There are three ways to install the repository; on your local file system, on Apache Web Server, or with a Maven repository manager. This example covers the steps to download the JBoss EAP 6 Maven Repository to the local file system. This option is easy to configure and allows you to get up and running quickly on your local machine. It can help you become familiar with the using Maven for development but is not recommended for team production environments.

Procedure 2.1. Download and Install the JBoss EAP 6 Maven Repository to the Local File System

  1. Download the JBoss EAP 6 Maven Repository ZIP archive

  2. Find "Application Platform 6.1.0 Maven Repository" in the list.
  3. Click the Download button to download a .zip file containing the repository.
  4. Unzip the file in the same directory on the local file system into a directory of your choosing.
Result
This creates a Maven repository directory called jboss-eap-6.1.0.maven-repository.

Important

If you want to continue to use an older local repository, you must configure it separately in the Maven settings.xml configuration file. Each local repository must be configured within its own <repository> tag.

Important

When downloading a new Maven repository, remove the cached repository/ subdirectory located under the .m2/directory before attempting to use the new Maven repository.

2.2.4. Install the JBoss EAP 6 Maven Repository for Use with Apache httpd

There are three ways to install the repository; on your local file system, on Apache Web Server, or with a Maven repository manager. This example will cover the steps to download the JBoss EAP 6 Maven Repository for use with Apache httpd. This option is good for multi-user and cross-team development environments because any developer that can access the web server can also access the Maven repository.
Prerequisites
You must configure Apache httpd. See Apache HTTP Server Project documentation for instructions.

Procedure 2.2. Download the JBoss EAP 6 Maven Repository ZIP archive

  1. Find "Application Platform 6.1.0 Maven Repository" in the list.
  2. Click the Download button to download a .zip file containing the repository.
  3. Unzip the files in a directory that is web accessible on the Apache server.
  4. Configure Apache to allow read access and directory browsing in the created directory.
Result
This allows a multi-user environment to access the Maven repository on Apache httpd.

Note

If you're upgrading from a previous version of the repository, note that JBoss EAP 6.1.0 Maven Repository artifacts can be simply extracted into an existing JBoss product Maven repository (such as JBoss EAP 6.0.1) without any conflicts. After the repository archive has been extracted, the artifacts can be used with the existing Maven settings for this repository.

2.2.5. Install the JBoss EAP 6 Maven Repository Using Nexus Maven Repository Manager

There are three ways to install the repository; on your local file system, on Apache Web Server, or with a Maven repository manager. This option is best if you have a licences and already use a repository manager because you can host the JBoss repository alongside your existing repositories. For more information about Maven repository managers, see Section 2.2.6, “About Maven Repository Managers”.
This example will cover the steps to install the JBoss EAP 6 Maven Repository using Sonatype Nexus Maven Repository Manager. For more complete instructions, see Sonatype Nexus: Manage Artifacts.

Procedure 2.3. Download the JBoss EAP 6 Maven Repository ZIP archive

  1. Find "Application Platform 6.1.0 Maven Repository" in the list.
  2. Click the Download button to download a .zip file containing the repository.
  3. Unzip the files into a directory of your choosing.

Procedure 2.4. Add the JBoss EAP 6 Maven Repository using Nexus Maven Repository Manager

  1. Log into Nexus as an Administrator.
  2. Select the Repositories section from the ViewsRepositories menu to the left of your repository manager.
  3. Click the Add... dropdown, then select Hosted Repository.
  4. Give the new repository a name and ID.
  5. Enter the path on disk to the unzipped repository in the field Override Local Storage Location.
  6. Continue if you want the artifact to be available in a repository group. Do not continue with this procedure if this is not what you want.
  7. Select the repository group.
  8. Click on the Configure tab.
  9. Drag the new JBoss Maven repository from the Available Repositories list to the Ordered Group Repositories list on the left.

    Note

    Note that the order of this list determines the priority for searching Maven artifacts.
Result
The repository is configured using Nexus Maven Repository Manager.

2.2.6. About Maven Repository Managers

A repository manager is a tool that allows you to easily manage Maven repositories. Repository managers are useful in multiple ways:
  • They provide the ability to configure proxies between your organization and remote Maven repositories. This provides a number of benefits, including faster and more efficient deployments and a better level of control over what is downloaded by Maven.
  • They provide deployment destinations for your own generated artifacts, allowing collaboration between different development teams across an organization.
For more information about Maven repository managers, see Apache Maven Project - The List of Repository Managers.

Commonly used Maven repository managers

Sonatype Nexus
See Sonatype Nexus: Manage Artifacts for more information about Nexus.
Artifactory
See Artifactory Open Source for more information about Artifactory.
Apache Archiva
See Apache Archiva: The Build Artifact Repository Manager for more information about Apache Archiva.

2.3. Use the Maven Repository

2.3.1. Configure the JBoss EAP Maven Repository

Overview
There are two approaches to direct Maven to use the JBoss EAP 6 Maven Repository in your project:
  • You can configure the repositories in the Maven global or user settings.
  • You can configure the repositories in the project's POM file.

Procedure 2.5. Configure Maven Settings to Use the JBoss EAP 6 Maven Repository

  1. Configure the Maven repository using Maven settings

    This is the recommended approach. Maven settings used with a repository manager or repository on a shared server provide better control and manageability of projects. Settings also provide the ability to use an alternative mirror to redirect all lookup requests for a specific repository to your repository manager without changing the project files. For more information about mirrors, see http://maven.apache.org/guides/mini/guide-mirror-settings.html.
    This method of configuration applies across all Maven projects, as long as the project POM file does not contain repository configuration.
  2. Configure the Maven repository using the project POM

    This method of configuration is generally not recommended. If you decide to configure repositories in your project POM file, plan carefully and be aware that it can slow down your build and you may even end up with artifacts that are not from the expected repository.

    Note

    In an Enterprise environment, where a repository manager is usually used, Maven should query all artifacts for all projects using this manager. Because Maven uses all declared repositories to find missing artifacts, if it can't find what it's looking for, it will try and look for it in the repository central (defined in the built-in parent POM). To override this central location, you can add a definition with central so that the default repository central is now your repository manager as well. This works well for established projects, but for clean or 'new' projects it causes a problem as it creates a cyclic dependency.
    Transitively included POMs are also an issue with this type of configuration. Maven has to query these external repositories for missing artifacts. This not only slows down your build, it also causes you to lose control over where your artifacts are coming from and likely to cause broken builds.
    This method of configuration overrides the global and user Maven settings for the configured project.

2.3.2. Configure the JBoss EAP 6 Maven Repository Using the Maven Settings

There are two approaches to direct Maven to use the JBoss EAP 6 Maven Repository in your project:
  • You can modify the Maven settings.
  • You can configure the project's POM file.
This task shows you how to direct Maven to use the JBoss EAP 6 Maven Repository across all projects using the Maven global or user settings. This is the recommended approach.

Note

The URL of the repository will depend on where the repository is located; on the filesystem, or web server. For information on how to install the repository, refer to the chapter entitled Maven Guide in the Development Guide for JBoss EAP 6 on https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/. The following are examples for each of the installation options:
File System
file:///path/to/repo/jboss-eap-6.x-maven-repository
Apache Web Server
http://intranet.acme.com/jboss-eap-6.x-maven-repository/
Nexus Repository Manager
https://intranet.acme.com/nexus/content/repositories/jboss-eap-6.x-maven-repository
You can configure Maven to use the JBoss EAP 6 Repository using either the Maven install or the user install settings. For more information about the location of the settings and how they behave, refer to the chapter entitled Maven Guide in the Development Guide for JBoss EAP 6 on https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/. .
To use the JBoss EAP 6 repository on a local user system, follow these instructions:

Procedure 2.6. Configure the Settings

  1. Open the settings.xml for the type of configuration you have chosen.
    • Global Settings

      If you are configuring the global settings, open the M2_HOME/conf/settings.xml file.
    • User Settings

      If you are configuring user specific settings and you do not yet have a USER_HOME/.m2/settings.xml file, copy the settings.xml file from the M2_HOME/conf/ directory into the USER_HOME/.m2/ directory.
  2. Copy the following XML into the <profiles> element of the settings.xml file. Be sure to change the <url> to the actual repository location.
    
    <profile>
      <id>jboss-eap-repository</id>
      <repositories>
        <repository>
          <id>jboss-eap-repository</id>
          <name>JBoss EAP Maven Repository</name>
          <url>file:///path/to/repo/jboss-eap-6.x-maven-repository</url>
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>false</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>jboss-eap-repository-group</id>
          <name>JBoss EAP Maven Repository</name>
          <url>
          file:///path/to/repo/jboss-eap-6.x-maven-repository
          </url>
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>false</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
    
    
    
    Copy the following XML into the <activeProfiles> element of the settings.xml file.
    
    <activeProfile>jboss-eap-repository</activeProfile>
    
    
    
    
  3. If you modify the settings.xml file while JBoss Developer Studio is running, you must refresh the user settings. From the menu, choose WindowPreferences. In the Preferences Window, expand Maven and choose User Settings. Click the Update Settings button to refresh the Maven user settings in JBoss Developer Studio.
    Update Maven User Settings

    Figure 2.1. Update Maven User Settings


Important

If your Maven repository contains outdated artifacts, you may encounter one of the following Maven error messages when you build or deploy your project:
  • Missing artifact ARTIFACT_NAME
  • [ERROR] Failed to execute goal on project PROJECT_NAME; Could not resolve dependencies for PROJECT_NAME
To resolve the issue, delete the cached version of your local repository to force a download of the latest Maven artifacts. The cached repository is located in your ~/.m2/repository/ subdirectory on Linux, or the %SystemDrive%\Users\USERNAME\.m2\repository\ subdirectory on Windows.
Result
The JBoss EAP 6 repository has now been configured.

2.3.3. Configure the JBoss EAP 6 Maven Repository Using the Project POM

There are two approaches to direct Maven to use the JBoss EAP 6 Maven Repository in your project:
  • You can modify the Maven settings.
  • You can configure the project's POM file.
This task shows you how to configure a specific project to use the JBoss EAP 6 Maven Repository by adding repository information to the project pom.xml. This configuration method supercedes and overrides the global and user settings configurations.
This method of configuration is generally not recommended. If you decide to configure repositories in your project POM file, plan carefully and be aware that it can slow down your build and you may even end up with artifacts that are not from the expected repository.

Note

In an Enterprise environment, where a repository manager is usually used, Maven should query all artifacts for all projects using this manager. Because Maven uses all declared repositories to find missing artifacts, if it can't find what it's looking for, it will try and look for it in the repository central (defined in the built-in parent POM). To override this central location, you can add a definition with central so that the default repository central is now your repository manager as well. This works well for established projects, but for clean or 'new' projects it causes a problem as it creates a cyclic dependency.
Transitively included POMs are also an issue with this type of configuration. Maven has to query these external repositories for missing artifacts. This not only slows down your build, it also causes you to lose control over where your artifacts are coming from and likely to cause broken builds.

Note

The URL of the repository will depend on where the repository is located; on the filesystem, or web server. For information on how to install the repository, see: Section 2.2.2, “Install the JBoss EAP 6 Maven Repository”. The following are examples for each of the installation options:
File System
file:///path/to/repo/jboss-eap-6.0.0-maven-repository
Apache Web Server
http://intranet.acme.com/jboss-eap-6.0.0-maven-repository/
Nexus Repository Manager
https://intranet.acme.com/nexus/content/repositories/jboss-eap-6.0.0-maven-repository
  1. Open your project's pom.xml file in a text editor.
  2. Add the following repository configuration. If there is already a <repositories> configuration in the file, then add the <repository> element to it. Be sure to change the <url> to the actual repository location.
    <repositories>
       <repository>
          <id>jboss-eap-repository-group</id>
          <name>JBoss EAP Maven Repository</name>
          <url>file:///path/to/repo/jboss-eap-6.0.0-maven-repository/</url>
          <layout>default</layout>
          <releases>
             <enabled>true</enabled>
             <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
             <enabled>true</enabled>
             <updatePolicy>never</updatePolicy>
          </snapshots>
       </repository>
    </repositories>
    
    
    
  3. Add the following plug-in repository configuration. If there is already a <pluginRepositories> configuration in the file, then add the <pluginRepository> element to it.
    <pluginRepositories>
       <pluginRepository>
          <id>jboss-eap-repository-group</id>
          <name>JBoss EAP Maven Repository</name>
          <url>file:///path/to/repo/jboss-eap-6.0.0-maven-repository/</url>
          <releases>
             <enabled>true</enabled>
          </releases>
          <snapshots>
             <enabled>true</enabled>
          </snapshots>
       </pluginRepository>
    </pluginRepositories>
    
    
    

2.3.4. Manage Project Dependencies

This topic describes the usage of Bill of Materials (BOM) POMs for Red Hat JBoss Enterprise Application Platform 6.
A BOM is a Maven pom.xml (POM) file that specifies the versions of all runtime dependencies for a given module. Version dependencies are listed in the dependency management section of the file.
A project uses a BOM by adding its groupId:artifactId:version (GAV) to the dependency management section of the project pom.xml file and specifying the <scope>import</scope> and <type>pom</type> element values.

In many cases, dependencies in project POM files use the provided scope. This is because these classes are provided by the application server at runtime and it is not necessary to package them with the user application.

JBoss JavaEE Specs Bom

The jboss-javaee-6.0 BOM contains the Java EE Specification API JARs used by JBoss EAP.
To use this BOM in a project, add a dependency for the GAV that contains the version of the JSP and Servlet API JARs needed to build and deploy the application.
The following example uses the 3.0.2.Final-redhat-4 version of the jboss-javaee-6.0 BOM.
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.jboss.spec</groupId>
      <artifactId>jboss-javaee-6.0</artifactId>
      <version>3.0.2.Final-redhat-4</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.jboss.spec.javax.servlet<groupId>
    <artifactId>jboss-servlet-api_3.0_spec</artifactId>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>org.jboss.spec.javax.servlet.jsp</groupId>
    <artifactId>jboss-jsp-api_2.2_spec</artifactId>
    <scope>provided</scope>
  </dependency>
  ...
</dependencies>


JBoss BOM and Quickstarts

The JBoss BOMs are located in the jboss-bom project at https://github.com/jboss-eap/jboss-bom.
The quickstarts provide the primary use case examples for the Maven repository. The following table lists the Maven BOMs used by the quickstarts.

Table 2.1. JBoss BOMs Used by the Quickstarts

Maven artifactId Description
jboss-javaee-6.0-with-errai This BOM builds on the Java EE full profile BOM, adding the Errai framework and the Google Web Toolkit (GWT) plus its Maven plugin.
jboss-javaee-6.0-with-hibernate This BOM builds on the Java EE full profile BOM, adding Hibernate Community projects including Hibernate ORM, Hibernate Search and Hibernate Validator. It also provides tool projects such as Hibernate JPA Model Gen and Hibernate Validator Annotation Processor.
jboss-javaee-6.0-with-hibernate3 This BOM builds on the Java EE full profile BOM, adding Hibernate Community projects including Hibernate 3 ORM, Hibernate Entity Manager (JPA 1.0) and Hibernate Validator.
jboss-javaee-6.0-with-infinispan This BOM builds on the Java EE full profile BOM, adding Infinispan.
jboss-javaee-6.0-with-logging This BOM builds on the Java EE full profile BOM, adding the JBoss Logging Tools and Log4 framework.
jboss-javaee-6.0-with-osgi This BOM builds on the Java EE full profile BOM, adding OSGI.
jboss-javaee-6.0-with-security This BOM builds on the Java EE full profile BOM, adding Picketlink.
jboss-javaee-6.0-with-tools This BOM builds on the Java EE full profile BOM, adding Arquillian to the mix. It also provides a version of JUnit and TestNG recommended for use with Arquillian.
jboss-javaee-6.0-with-transactions This BOM includes a world class transaction manager. Use the JBossTS APIs to access its full capabilities.

The following example uses the 1.0.4.Final-redhat-9 version of the jboss-javaee-6.0-with-hibernate BOM.
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.jboss.bom</groupId>
      <artifactId>jboss-javaee-6.0-with-hibernate</artifactId>
      <version>1.0.4.Final-redhat-9</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.hibernate<groupId>
    <artifactId>hibernate-core</artifactId>
    <scope>provided</scope>
  </dependency>
  ...
</dependencies>


JBoss Client BOMs

The JBoss EAP server build includes two client BOMs: jboss-as-ejb-client-bom and jboss-as-jms-client-bom.
The client BOMs do not create a dependency management section or define dependencies. Instead, they are an aggregate of other BOMs and are used to package the set of dependencies necessary for a remote client use case.
The following example uses the 7.2.1.Final-redhat-10 version of the jboss-as-ejb-client-bom client BOM.
<dependencies>
  <dependency>
    <groupId>org.jboss.as<groupId>
    <artifactId>jboss-as-ejb-client-bom</artifactId>
    <version>7.2.1.Final-redhat-10</version>
    <type>pom</type>
  </dependency>
  ...
</dependencies>

This example uses the 7.2.1.Final-redhat-10 version of the jboss-as-jms-client-bom client BOM.
<dependencies>
  <dependency>
    <groupId>org.jboss.as<groupId>
    <artifactId>jboss-as-jms-client-bom</artifactId>
    <version>7.2.1.Final-redhat-10</version>
    <type>pom</type>
  </dependency>
  ...
</dependencies>



For more information about Maven Dependencies and BOM POM files, see Apache Maven Project - Introduction to the Dependency Mechanism.

Chapter 3. Class Loading and Modules

3.1. Introduction

3.1.1. Overview of Class Loading and Modules

JBoss EAP 6 uses a new modular class loading system for controlling the class paths of deployed applications. This system provides more flexibility and control than the traditional system of hierarchical class loaders. Developers have fine-grained control of the classes available to their applications, and can configure a deployment to ignore classes provided by the application server in favour of their own.
The modular class loader separates all Java classes into logical groups called modules. Each module can define dependencies on other modules in order to have the classes from that module added to its own class path. Because each deployed JAR and WAR file is treated as a module, developers can control the contents of their application's class path by adding module configuration to their application.
The following material covers what developers need to know to successfully build and deploy applications on JBoss EAP 6.

3.1.2. Class Loading

Class Loading is the mechanism by which Java classes and resources are loaded into the Java Runtime Environment.

3.1.3. Modules

A Module is a logical grouping of classes used for class loading and dependency management. JBoss EAP 6 identifies two different types of modules, sometimes called static and dynamic modules. However the only difference between the two is how they are packaged. All modules provide the same features.
Static Modules
Static Modules are predefined in the EAP_HOME/modules/ directory of the application server. Each sub-directory represents one module and contains one or more JAR files and a configuration file (module.xml). The name of the module is defined in the module.xml file. All the application server provided APIs are provided as static modules, including the Java EE APIs as well as other APIs such as JBoss Logging.

Example 3.1. Example module.xml file

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.1.15.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>


The module name, com.mysql, should match the directory structure for the module.

Creating custom static modules can be useful if many applications are deployed on the same server that use the same third party libraries. Instead of bundling those libraries with each application, a module containing these libraries can be created and installed by the JBoss administrator. The applications can then declare an explicit dependency on the custom static modules.
Dynamic Modules
Dynamic Modules are created and loaded by the application server for each JAR or WAR deployment (or subdeployment in an EAR). The name of a dynamic module is derived from the name of the deployed archive. Because deployments are loaded as modules, they can configure dependencies and be used as dependencies by other deployments.
Modules are only loaded when required. This usually only occurs when an application is deployed that has explicit or implicit dependencies.

3.1.4. Module Dependencies

A module dependency is a declaration that one module requires the classes of another module in order to function. Modules can declare dependencies on any number of other modules. When the application server loads a module, the modular class loader parses the dependencies of that module and adds the classes from each dependency to its class path. If a specified dependency cannot be found, the module will fail to load.
Deployed applications (JAR and WAR) are loaded as dynamic modules and make use of dependencies to access the APIs provided by JBoss EAP 6.
There are two types of dependencies: explicit and implicit.
Explicit dependencies are declared in configuration by the developer. Static modules can declare dependencies in the modules.xml file. Dynamic modules can have dependencies declared in the MANIFEST.MF or jboss-deployment-structure.xml deployment descriptors of the deployment.
Explicit dependencies can be specified as optional. Failure to load an optional dependency will not cause a module to fail to load. However if the dependency becomes available later it will NOT be added to the module's class path. Dependencies must be available when the module is loaded.
Implicit dependencies are added automatically by the application server when certain conditions or meta-data are found in a deployment. The Java EE 6 APIs supplied with JBoss EAP 6 are examples of modules that are added by detection of implicit dependencies in deployments.
Deployments can also be configured to exclude specific implicit dependencies. This is done with the jboss-deployment-structure.xml deployment descriptor file. This is commonly done when an application bundles a specific version of a library that the application server will attempt to add as an implicit dependency.
A module's class path contains only its own classes and that of it's immediate dependencies. A module is not able to access the classes of the dependencies of one of its dependencies. However a module can specify that an explicit dependency is exported. An exported dependency is provided to any module that depends on the module that exports it.

Example 3.2. Module dependencies

Module A depends on Module B and Module B depends on Module C. Module A can access the classes of Module B, and Module B can access the classes of Module C. Module A cannot access the classes of Module C unless:
  • Module A declares an explicit dependency on Module C, or
  • Module B exports its dependency on Module C.

3.1.5. Class Loading in Deployments

For the purposes of classloading all deployments are treated as modules by JBoss EAP 6. These are called dynamic modules. Class loading behavior varies according to the deployment type.
WAR Deployment
A WAR deployment is considered to be a single module. Classes in the WEB-INF/lib directory are treated the same as classes in WEB-INF/classes directory. All classes packaged in the war will be loaded with the same class loader.
EAR Deployment
EAR deployments are made up more than one module. The definition of these modules follows these rules:
  1. The lib/ directory of the EAR is a single module called the parent module.
  2. Each WAR deployment within the EAR is a single module.
  3. Each EJB JAR deployment within the EAR is a single module.
Subdeployment modules (the WAR and JAR deployments within the EAR) have an automatic dependency on the parent module. However they do not have automatic dependencies on each other. This is called subdeployment isolation and can be disabled on a per deployment basis or for the entire application server.
Explicit dependencies between subdeployment modules can be added by the same means as any other module.

3.1.6. Class Loading Precedence

The JBoss EAP 6 modular class loader uses a precedence system to prevent class loading conflicts.
During deployment a complete list of packages and classes is created for each deployment and each of its dependencies. The list is ordered according to the class loading precedence rules. When loading classes at runtime, the class loader searches this list, and loads the first match. This prevents multiple copies of the same classes and packages within the deployments class path from conflicting with each other.
The class loader loads classes in the following order, from highest to lowest:
  1. Implicit dependencies.
    These are the dependencies that are added automatically by JBoss EAP 6, such as the JAVA EE APIs. These dependencies have the highest class loader precedence because they contain common functionality and APIs that are supplied by JBoss EAP 6.
    Refer to Section 3.7.1, “Implicit Module Dependencies” for complete details about each implicit dependency.
  2. Explicit dependencies.
    These are dependencies that are manually added in the application configuration. This can be done using the application's MANIFEST.MF file or the new optional JBoss deployment descriptor jboss-deployment-structure.xml file.
    Refer to Section 3.2, “Add an Explicit Module Dependency to a Deployment” to learn how to add explicit dependencies.
  3. Local resources.
    Class files packaged up inside the deployment itself, e.g. from the WEB-INF/classes or WEB-INF/lib directories of a WAR file.
  4. Inter-deployment dependencies.
    These are dependencies on other deployments in a EAR deployment. This can include classes in the lib directory of the EAR or classes defined in other EJB jars.

3.1.7. Dynamic Module Naming

All deployments are loaded as modules by JBoss EAP 6 and named according to the following conventions.
  1. Deployments of WAR and JAR files are named with the following format:
     deployment.DEPLOYMENT_NAME 
    For example, inventory.war and store.jar will have the module names of deployment.inventory.war and deployment.store.jar respectively.
  2. Subdeployments within an Enterprise Archive are named with the following format:
     deployment.EAR_NAME.SUBDEPLOYMENT_NAME 
    For example, the subdeployment of reports.war within the enterprise archive accounts.ear will have the module name of deployment.accounts.ear.reports.war.

3.1.8. jboss-deployment-structure.xml

jboss-deployment-structure.xml is a new optional deployment descriptor for JBoss EAP 6. This deployment descriptor provides control over class loading in the deployment.
The XML schema for this deployment descriptor is in EAP_HOME/docs/schema/jboss-deployment-structure-1_2.xsd

3.2. Add an Explicit Module Dependency to a Deployment

This task shows how to add an explicit dependency to an application. Explicit module dependencies can be added to applications to add the classes of those modules to the class path of the application at deployment.
Some dependencies are automatically added to deployments by JBoss EAP 6. Refer to Section 3.7.1, “Implicit Module Dependencies” for details.

Prerequisites

  1. You must already have a working software project that you want to add a module dependency to.
  2. You must know the name of the module being added as a dependency. Refer to Section 3.7.2, “Included Modules” for the list of static modules included with JBoss EAP 6. If the module is another deployment then refer to Section 3.1.7, “Dynamic Module Naming” to determine the module name.
Dependencies can be configured using two different methods:
  1. Adding entries to the MANIFEST.MF file of the deployment.
  2. Adding entries to the jboss-deployment-structure.xml deployment descriptor.

Procedure 3.1. Add dependency configuration to MANIFEST.MF

Maven projects can be configured to create the required dependency entries in the MANIFEST.MF file. Refer to Section 3.3, “Generate MANIFEST.MF entries using Maven”.
  1. Add MANIFEST.MF file

    If the project has no MANIFEST.MF file, create a file called MANIFEST.MF. For a web application (WAR) add this file to the META-INF directory. For an EJB archive (JAR) add it to the META-INF directory.
  2. Add dependencies entry

    Add a dependencies entry to the MANIFEST.MF file with a comma-separated list of dependency module names.
    Dependencies: org.javassist, org.apache.velocity
  3. Optional: Make a dependency optional

    A dependency can be made optional by appending optional to the module name in the dependency entry.
    Dependencies: org.javassist optional, org.apache.velocity
  4. Optional: Export a dependency

    A dependency can be exported by appending export to the module name in the dependency entry.
    Dependencies: org.javassist, org.apache.velocity export

Procedure 3.2. Add dependency configuration to jboss-deployment-structure.xml

  1. Add jboss-deployment-structure.xml

    If the application has no jboss-deployment-structure.xml file then create a new file called jboss-deployment-structure.xml and add it to the project. This file is an XML file with the root element of <jboss-deployment-structure> .
    <jboss-deployment-structure> 
    
    </jboss-deployment-structure>
    
    For a web application (WAR) add this file to the WEB-INF directory. For an EJB archive (JAR) add it to the META-INF directory.
  2. Add dependencies section

    Create a <deployment> element within the document root and a <dependencies> element within that.
  3. Add module elements

    Within the dependencies node, add a module element for each module dependency. Set the name attribute to the name of the module.
    <module name="org.javassist" />
    
  4. Optional: Make a dependency optional

    A dependency can be made optional by adding the optional attribute to the module entry with the value of TRUE. The default value for this attribute is FALSE.
    <module name="org.javassist" optional="TRUE" />
    
  5. Optional: Export a dependency

    A dependency can be exported by adding the export attribute to the module entry with the value of TRUE. The default value for this attribute is FALSE.
    <module name="org.javassist" export="TRUE" />
    

Example 3.3. jboss-deployment-structure.xml with two dependencies

<jboss-deployment-structure>

   <deployment>

      <dependencies>
         <module name="org.javassist" />
         <module name="org.apache.velocity" export="TRUE" />
      </dependencies>

   </deployment>

</jboss-deployment-structure>

JBoss EAP 6 will add the classes from the specified modules to the class path of the application when it is deployed.

3.3. Generate MANIFEST.MF entries using Maven

Maven projects that use the Maven JAR, EJB or WAR packaging plug-ins can generate a MANIFEST.MF file with a Dependencies entry. This does not automatically generate the list of dependencies, this process only creates the MANIFEST.MF file with the details specified in the pom.xml.

Prerequisites

  1. You must already have a working Maven project.
  2. The Maven project must be using one of the JAR, EJB, or WAR plug-ins ( maven-jar-plugin, maven-ejb-plugin, maven-war-plugin).
  3. You must know the name of the project's module dependencies. Refer to Section 3.7.2, “Included Modules” for the list of static modules included with JBoss EAP 6. If the module is another deployment , then refer to Section 3.1.7, “Dynamic Module Naming” to determine the module name.

Procedure 3.3. Generate a MANIFEST.MF file containing module dependencies

  1. Add Configuration

    Add the following configuration to the packaging plug-in configuration in the project's pom.xml file.
    <configuration>
       <archive>
          <manifestEntries>
             <Dependencies></Dependencies>
          </manifestEntries>
       </archive>
    </configuration>
    
  2. List Dependencies

    Add the list of the module dependencies in the <Dependencies> element. Use the same format that is used when adding the dependencies to the MANIFEST.MF. Refer to Section 3.2, “Add an Explicit Module Dependency to a Deployment” for details about that format.
    <Dependencies>org.javassist, org.apache.velocity</Dependencies>
    
  3. Build the Project

    Build the project using the Maven assembly goal.
    [Localhost ]$ mvn assembly:assembly
When the project is built using the assembly goal, the final archive contains a MANIFEST.MF file with the specified module dependencies.

Example 3.4. Configured Module Dependencies in pom.xml

The example here shows the WAR plug-in but it also works with the JAR and EJB plug-ins (maven-jar-plugin and maven-ejb-plugin).
<plugins>
   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <configuration>
         <archive>
            <manifestEntries>
               <Dependencies>org.javassist, org.apache.velocity</Dependencies>
            </manifestEntries>
         </archive>
      </configuration>
   </plugin>
</plugins>

3.4. Prevent a Module Being Implicitly Loaded

This task describes how to configure your application to exclude a list of module dependencies.
You can configure a deployable application to prevent implicit dependencies from being loaded. This is commonly done when the application includes a different version of a library or framework than the one that will be provided by the application server as an implicit dependency.

Prerequisites

  1. You must already have a working software project that you want to exclude an implicit dependency from.
  2. You must know the name of the module to exclude. Refer to Section 3.7.1, “Implicit Module Dependencies” for a list of implicit dependencies and their conditions.

Procedure 3.4. Add dependency exclusion configuration to jboss-deployment-structure.xml

  1. If the application has no jboss-deployment-structure.xml file, create a new file called jboss-deployment-structure.xml and add it to the project. This file is an XML file with the root element of <jboss-deployment-structure> .
    <jboss-deployment-structure>
    
    </jboss-deployment-structure>
    
    For a web application (WAR) add this file to the WEB-INF directory. For an EJB archive (JAR) add it to the META-INF directory.
  2. Create a <deployment> element within the document root and an <exclusions> element within that.
    <deployment>
       <exclusions>
       
       </exclusions>
    </deployment>
    
  3. Within the exclusions element, add a <module> element for each module to be excluded. Set the name attribute to the name of the module.
    <module name="org.javassist" />
    

Example 3.5. Excluding two modules

<jboss-deployment-structure>
   <deployment>
      <exclusions>
         <module name="org.javassist" />
         <module name="org.dom4j" />
      </exclusions>
   </deployment>
</jboss-deployment-structure>

3.5. Exclude a Subsystem from a Deployment

Summary
This topic covers the steps required to exclude a subsystem from a deployment. This is done by editing the jboss-deployment-structure.xml configuration file. Excluding a subsystem provides the same effect as removing the subsystem, but it applies only to a single deployment.

Procedure 3.5. Exclude a Subsystem

  1. Open the jboss-deployment-structure.xml file in a text editor.
  2. Add the following XML inside the <deployment> tags:
    <exclude-subsystems>
      <subsystem name="SUBSYSTEM_NAME" />
    </exclude-subsystems>
    
  3. Save the jboss-deployment-structure.xml file.
Result
The subsystem has been successfully excluded. The subsystem's deployment unit processors will no longer run on the deployment.

Example 3.6. Example jboss-deployment-structure.xml file.

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <ear-subdeployments-isolated>true</ear-subdeployments-isolated>
  <deployment>
    <exclude-subsystems>
      <subsystem name="resteasy" />
    </exclude-subsystems>
    <exclusions>
      <module name="org.javassist" />
    </exclusions>
    <dependencies>
      <module name="deployment.javassist.proxy" />
      <module name="deployment.myjavassist" />
      <module name="myservicemodule" services="import"/>
    </dependencies>
    <resources>
      <resource-root path="my-library.jar" />
    </resources>
  </deployment>
  <sub-deployment name="myapp.war">
    <dependencies>
      <module name="deployment.myear.ear.myejbjar.jar" />
    </dependencies>
    <local-last value="true" />
  </sub-deployment>
  <module name="deployment.myjavassist" >
    <resources>
     <resource-root path="javassist.jar" >
       <filter>
         <exclude path="javassist/util/proxy" />
       </filter>
     </resource-root>
    </resources>
  </module>
  <module name="deployment.javassist.proxy" >
    <dependencies>
      <module name="org.javassist" >
        <imports>
          <include path="javassist/util/proxy" />
          <exclude path="/**" />
        </imports>
      </module>
    </dependencies>
  </module>
</jboss-deployment-structure>

3.6. Class Loading and Subdeployments

3.6.1. Modules and Class Loading in Enterprise Archives

Enterprise Archives (EAR) are not loaded as a single module like JAR or WAR deployments. They are loaded as multiple unique modules.
The following rules determine what modules exist in an EAR.
  • Each WAR and EJB JAR subdeployment is a module.
  • The contents of the lib/ directory in the root of the EAR archive is a module. This is called the parent module.
These modules have the same behaviour as any other module with the following additional implicit dependencies:
  • WAR subdeployments have implicit dependencies on the parent module and any EJB JAR subdeployments.
  • EJB JAR subdeployments have implicit dependencies on the parent module and any other EJB JAR subdeployments.

Important

No subdeployment ever gains an implicit dependency on a WAR subdeployment. Any subdeployment can be configured with explicit dependencies on another subdeployment as would be done for any other module.
The implicit dependencies described above occur because JBoss EAP 6 has subdeployment class loader isolation disabled by default.
Subdeployment class loader isolation can be enabled if strict compatibility is required. This can be enabled for a single EAR deployment or for all EAR deployments. The Java EE 6 specification recommends that portable applications should not rely on subdeployments being able to access each other unless dependencies are explicitly declared as Class-Path entries in the MANIFEST.MF file of each subdeployment.

3.6.2. Subdeployment Class Loader Isolation

Each subdeployment in an Enterprise Archive (EAR) is a dynamic module with its own class loader. By default a subdeployment can access the resources of other subdeployments.
If a subdeployment should not access the resources of other subdeployments (strict subdeployment isolation is required) then this can be enabled.

3.6.3. Disable Subdeployment Class Loader Isolation Within a EAR

This task shows you how to disable Subdeployment class loader isolation in an EAR deployment by using a special deployment descriptor in the EAR. This does not require any changes to be made to the application server and does not affect any other deployments.

Important

Even when subdeployment class loader isolation is disabled it is not possible to add a WAR deployment as a dependency.
  1. Add the deployment descriptor file

    Add the jboss-deployment-structure.xml deployment descriptor file to the META-INF directory of the EAR if it doesn't already exist and add the following content:
    <jboss-deployment-structure>
    
    </jboss-deployment-structure>
    
  2. Add the <ear-subdeployments-isolated> element

    Add the <ear-subdeployments-isolated> element to the jboss-deployment-structure.xml file if it doesn't already exist with the content of false.
    <ear-subdeployments-isolated>false</ear-subdeployments-isolated>
    
Result:
Subdeployment class loader isolation will now be disabled for this EAR deployment. This means that the subdeployments of the EAR will have automatic dependencies on each of the non-WAR subdeployments.

3.7. Reference

3.7.1. Implicit Module Dependencies

The following table lists the modules that are automatically added to deployments as dependencies and the conditions that trigger the dependency.

Table 3.1. Implicit Module Dependencies

Subsystem Modules Always added Modules Conditional added Conditions
Core Server
  • javax.api
  • sun.jdk
  • org.jboss.logging
  • org.apache.log4j
  • org.apache.commons.logging
  • org.slf4j
  • org.jboss.logging.jul-to-slf4j-stub
-
-
EE Subsystem
  • javaee.api
-
-
EJB3 subsystem
-
  • javaee.api
The presence of ejb-jar.xml in valid locations in the deployment, as specified by the Java EE 6 specification or the presence of annotation-based EJBs (e.g. @Stateless, @Stateful, @MessageDriven etc)
JAX-RS (Resteasy) subsystem
  • javax.xml.bind.api
  • org.jboss.resteasy.resteasy-atom-provider
  • org.jboss.resteasy.resteasy-cdi
  • org.jboss.resteasy.resteasy-jaxrs
  • org.jboss.resteasy.resteasy-jaxb-provider
  • org.jboss.resteasy.resteasy-jackson-provider
  • org.jboss.resteasy.resteasy-jsapi
  • org.jboss.resteasy.resteasy-multipart-provider
  • org.jboss.resteasy.async-http-servlet-30
The presence of JAX-RS annotations in the deployment
JCA sub-system
  • javax.resource.api
  • javax.jms.api
  • javax.validation.api
  • org.jboss.logging
  • org.jboss.ironjacamar.api
  • org.jboss.ironjacamar.impl
  • org.hibernate.validator
If the deployment is a resource adaptor (RAR) deployment.
JPA (Hibernate) subsystem
  • javax.persistence.api
  • javaee.api
  • org.jboss.as.jpa
  • org.hibernate
  • org.javassist
The presence of an @PersistenceUnit or @PersistenceContext annotation, or a <persistence-unit-ref> or <persistence-context-ref> in a deployment descriptor.
SAR Subsystem
-
  • org.jboss.logging
  • org.jboss.modules
The deployment is a SAR archive
Security Subsystem
  • org.picketbox
-
-
Web Subsystem
-
  • javaee.api
  • com.sun.jsf-impl
  • org.hibernate.validator
  • org.jboss.as.web
  • org.jboss.logging
The deployment is a WAR archive. JavaServer Faces(JSF) is only added if used.
Web Services Subsystem
  • org.jboss.ws.api
  • org.jboss.ws.spi
-
-
Weld (CDI) Subsystem
-
  • javax.persistence.api
  • javaee.api
  • org.javassist
  • org.jboss.interceptor
  • org.jboss.as.weld
  • org.jboss.logging
  • org.jboss.weld.core
  • org.jboss.weld.api
  • org.jboss.weld.spi
If a beans.xml file is detected in the deployment

3.7.2. Included Modules

  • asm.asm
  • ch.qos.cal10n
  • com.google.guava
  • com.h2database.h2
  • com.sun.jsf-impl
  • com.sun.jsf-impl
  • com.sun.xml.bind
  • com.sun.xml.messaging.saaj
  • gnu.getopt
  • javaee.api
  • javax.activation.api
  • javax.annotation.api
  • javax.api
  • javax.ejb.api
  • javax.el.api
  • javax.enterprise.api
  • javax.enterprise.deploy.api
  • javax.faces.api
  • javax.faces.api
  • javax.inject.api
  • javax.interceptor.api
  • javax.jms.api
  • javax.jws.api
  • javax.mail.api
  • javax.management.j2ee.api
  • javax.persistence.api
  • javax.resource.api
  • javax.rmi.api
  • javax.security.auth.message.api
  • javax.security.jacc.api
  • javax.servlet.api
  • javax.servlet.jsp.api
  • javax.servlet.jstl.api
  • javax.transaction.api
  • javax.validation.api
  • javax.ws.rs.api
  • javax.wsdl4j.api
  • javax.xml.bind.api
  • javax.xml.jaxp-provider
  • javax.xml.registry.api
  • javax.xml.rpc.api
  • javax.xml.soap.api
  • javax.xml.stream.api
  • javax.xml.ws.api
  • jline
  • net.sourceforge.cssparser
  • net.sourceforge.htmlunit
  • net.sourceforge.nekohtml
  • nu.xom
  • org.antlr
  • org.apache.ant
  • org.apache.commons.beanutils
  • org.apache.commons.cli
  • org.apache.commons.codec
  • org.apache.commons.collections
  • org.apache.commons.io
  • org.apache.commons.lang
  • org.apache.commons.logging
  • org.apache.commons.pool
  • org.apache.cxf
  • org.apache.httpcomponents
  • org.apache.james.mime4j
  • org.apache.log4j
  • org.apache.neethi
  • org.apache.santuario.xmlsec
  • org.apache.velocity
  • org.apache.ws.scout
  • org.apache.ws.security
  • org.apache.ws.xmlschema
  • org.apache.xalan
  • org.apache.xerces
  • org.apache.xml-resolver
  • org.codehaus.jackson.jackson-core-asl
  • org.codehaus.jackson.jackson-jaxrs
  • org.codehaus.jackson.jackson-mapper-asl
  • org.codehaus.jackson.jackson-xc
  • org.codehaus.woodstox
  • org.dom4j
  • org.hibernate
  • org.hibernate.envers
  • org.hibernate.infinispan
  • org.hibernate.validator
  • org.hornetq
  • org.hornetq.ra
  • org.infinispan
  • org.infinispan.cachestore.jdbc
  • org.infinispan.cachestore.remote
  • org.infinispan.client.hotrod
  • org.jacorb
  • org.javassist
  • org.jaxen
  • org.jboss.as.aggregate
  • org.jboss.as.appclient
  • org.jboss.as.cli
  • org.jboss.as.clustering.api
  • org.jboss.as.clustering.common
  • org.jboss.as.clustering.ejb3.infinispan
  • org.jboss.as.clustering.impl
  • org.jboss.as.clustering.infinispan
  • org.jboss.as.clustering.jgroups
  • org.jboss.as.clustering.service
  • org.jboss.as.clustering.singleton
  • org.jboss.as.clustering.web.infinispan
  • org.jboss.as.clustering.web.spi
  • org.jboss.as.cmp
  • org.jboss.as.connector
  • org.jboss.as.console
  • org.jboss.as.controller
  • org.jboss.as.controller-client
  • org.jboss.as.deployment-repository
  • org.jboss.as.deployment-scanner
  • org.jboss.as.domain-add-user
  • org.jboss.as.domain-http-error-context
  • org.jboss.as.domain-http-interface
  • org.jboss.as.domain-management
  • org.jboss.as.ee
  • org.jboss.as.ee.deployment
  • org.jboss.as.ejb3
  • org.jboss.as.embedded
  • org.jboss.as.host-controller
  • org.jboss.as.jacorb
  • org.jboss.as.jaxr
  • org.jboss.as.jaxrs
  • org.jboss.as.jdr
  • org.jboss.as.jmx
  • org.jboss.as.jpa
  • org.jboss.as.jpa.hibernate
  • org.jboss.as.jpa.hibernate
  • org.jboss.as.jpa.hibernate.infinispan
  • org.jboss.as.jpa.openjpa
  • org.jboss.as.jpa.spi
  • org.jboss.as.jpa.util
  • org.jboss.as.jsr77
  • org.jboss.as.logging
  • org.jboss.as.mail
  • org.jboss.as.management-client-content
  • org.jboss.as.messaging
  • org.jboss.as.modcluster
  • org.jboss.as.naming
  • org.jboss.as.network
  • org.jboss.as.osgi
  • org.jboss.as.platform-mbean
  • org.jboss.as.pojo
  • org.jboss.as.process-controller
  • org.jboss.as.protocol
  • org.jboss.as.remoting
  • org.jboss.as.sar
  • org.jboss.as.security
  • org.jboss.as.server
  • org.jboss.as.standalone
  • org.jboss.as.threads
  • org.jboss.as.transactions
  • org.jboss.as.web
  • org.jboss.as.webservices
  • org.jboss.as.webservices.server.integration
  • org.jboss.as.webservices.server.jaxrpc-integration
  • org.jboss.as.weld
  • org.jboss.as.xts
  • org.jboss.classfilewriter
  • org.jboss.com.sun.httpserver
  • org.jboss.common-core
  • org.jboss.dmr
  • org.jboss.ejb-client
  • org.jboss.ejb3
  • org.jboss.iiop-client
  • org.jboss.integration.ext-content
  • org.jboss.interceptor
  • org.jboss.interceptor.spi
  • org.jboss.invocation
  • org.jboss.ironjacamar.api
  • org.jboss.ironjacamar.impl
  • org.jboss.ironjacamar.jdbcadapters
  • org.jboss.jandex
  • org.jboss.jaxbintros
  • org.jboss.jboss-transaction-spi
  • org.jboss.jsfunit.core
  • org.jboss.jts
  • org.jboss.jts.integration
  • org.jboss.logging
  • org.jboss.logmanager
  • org.jboss.logmanager.log4j
  • org.jboss.marshalling
  • org.jboss.marshalling.river
  • org.jboss.metadata
  • org.jboss.modules
  • org.jboss.msc
  • org.jboss.netty
  • org.jboss.osgi.deployment
  • org.jboss.osgi.framework
  • org.jboss.osgi.resolver
  • org.jboss.osgi.spi
  • org.jboss.osgi.vfs
  • org.jboss.remoting3
  • org.jboss.resteasy.resteasy-atom-provider
  • org.jboss.resteasy.resteasy-cdi
  • org.jboss.resteasy.resteasy-jackson-provider
  • org.jboss.resteasy.resteasy-jaxb-provider
  • org.jboss.resteasy.resteasy-jaxrs
  • org.jboss.resteasy.resteasy-jsapi
  • org.jboss.resteasy.resteasy-multipart-provider
  • org.jboss.sasl
  • org.jboss.security.negotiation
  • org.jboss.security.xacml
  • org.jboss.shrinkwrap.core
  • org.jboss.staxmapper
  • org.jboss.stdio
  • org.jboss.threads
  • org.jboss.vfs
  • org.jboss.weld.api
  • org.jboss.weld.core
  • org.jboss.weld.spi
  • org.jboss.ws.api
  • org.jboss.ws.common
  • org.jboss.ws.cxf.jbossws-cxf-client
  • org.jboss.ws.cxf.jbossws-cxf-factories
  • org.jboss.ws.cxf.jbossws-cxf-server
  • org.jboss.ws.cxf.jbossws-cxf-transports-httpserver
  • org.jboss.ws.jaxws-client
  • org.jboss.ws.jaxws-jboss-httpserver-httpspi
  • org.jboss.ws.native.jbossws-native-core
  • org.jboss.ws.native.jbossws-native-factories
  • org.jboss.ws.native.jbossws-native-services
  • org.jboss.ws.saaj-impl
  • org.jboss.ws.spi
  • org.jboss.ws.tools.common
  • org.jboss.ws.tools.wsconsume
  • org.jboss.ws.tools.wsprovide
  • org.jboss.xb
  • org.jboss.xnio
  • org.jboss.xnio.nio
  • org.jboss.xts
  • org.jdom
  • org.jgroups
  • org.joda.time
  • org.junit
  • org.omg.api
  • org.osgi.core
  • org.picketbox
  • org.picketlink
  • org.python.jython.standalone
  • org.scannotation.scannotation
  • org.slf4j
  • org.slf4j.ext
  • org.slf4j.impl
  • org.slf4j.jcl-over-slf4j
  • org.w3c.css.sac
  • sun.jdk

3.7.3. JBoss Deployment Structure Deployment Descriptor Reference

The key tasks that can be performed using this deployment descriptor are:
  • Defining explicit module dependencies.
  • Preventing specific implicit dependencies from loading.
  • Defining additional modules from the resources of that deployment.
  • Changing the subdeployment isolation behaviour in that EAR deployment.
  • Adding additional resource roots to a module in an EAR.

Chapter 4. Global Valves

4.1. About Valves

A Valve is a Java class that gets inserted into the request processing pipeline for an application. It is inserted in the pipeline before servlet filters. Valves can make changes to the request before passing it on or perform any other processing such as authentication or even cancelling the request. Valves are usually packaged with an application.
Version 6.1.0 and later supports global valves.

4.2. About Global Valves

A Global Valve is a valve that is inserted into the request processing pipeline of all deployed applications. A valve is made global by being packaged and installed as a static module in JBoss EAP 6. Global valves are configured in the web subsystem.
Only version 6.1.0 and later supports global valves.

4.3. About Authenticator Valves

An authenticator valve is a valve that authenticates the credentials of a request. Such valve is a sub-class of org.apache.catalina.authenticator.AuthenticatorBase and overrides the authenticate() method.
This can be used to implement additional authentication schemes.

4.4. Configure a Web Application to use a Valve

Valves that are not installed as global valves must be included with your application and configured in the jboss-web.xml deployment descriptor.

Important

Valves that are installed a global valves are automatically applied to all deployed applications.

Prerequisites

  • The valve must be created and included in your application's classpath. This can be done by either including it in the application's WAR file or any module that is added as a dependency. Examples of such modules include a static module installed on the server or a JAR file in the lib/ directory of an EAR archive if the WAR is deployed in an EAR.
  • The application must include a jboss-web.xml deployment descriptor.

Procedure 4.1. Configure an application for a local valve

  1. Add Valve element

    Add a valve element with the attributes of name and class-name to the application's jboss-web.xml file. Name is a unique identifier for the valve and class-name is the name of the valve class.
    <valve name="VALVENAME" class-name="VALVECLASSNAME">
       
    </valve>
    
  2. Specific Parameters

    If the valve has configurable parameters, add a param child element to the valve element for each parameter, specifying the name and value for each.
    <param name="PARAMNAME" value = "VALUE" />
    
When the application is deployed, the valve will be enabled for the application with the specified configuration.

Example 4.1. jboss-web.xml valve configuration

<valve name="clientlimiter" class-name="org.jboss.samplevalves.restrictedUserAgentsValve">
    <param name="restricteduseragents"  value = "^.*MS Web Services Client Protocol.*$" />
</valve>

4.5. Configure a Web Application to use an Authenticator Valve

Configuring an application to use an authenticator valve requires the valve to be installed and configured (either local to the application or as a global valve) and the web.xml deployment descriptor of the application to be configured. In the simplest case, the web.xml configuration is the same as using BASIC authentication except the auth-method child element of login-config is set to the name of the valve performing the configuration.

Prerequisites

  • Authentication valve must already be created.
  • If the authentication valve is a global valve then it must already be installed and configured, and you must know the name that it was configured as.
  • You need to know the realm name of the security realm that the application will use.
If you do not know the valve or security realm name to use, ask your server administrator for this information.

Procedure 4.2. Configure an Application to use an Authenticator Valve

  1. Configure the valve

    When using a local valve, it must be configured in the applications jboss-web.xml deployment descriptor. Refer to Section 4.4, “Configure a Web Application to use a Valve”.
    When using a global valve, this is unnecessary.
  2. Add security configuration to web.xml

    Add the security configuration the the web.xml file for your application, using the standard elements such as security-constraint, login-config, and security-role. In the login-config element, set the value of auth-method to the name of the authenticator valve. The realm-name element also needs to be set to the name of the JBoss security realm being used by the application.
    <login-config>
       <auth-method>VALVE_NAME</auth-method>
       <realm-name>REALM_NAME</realm-name>
    </login-config>
    
When the application is deployed, the authentication of requests is handled by the configured authentication valve.

4.6. Create a Custom Valve

A Valve is a Java class that gets inserted into the request processing pipeline for an application before the application's servlet filters. This can be used to modify the request or perform any other behavior. This task demonstrates the basic steps required for implementing a valve.

Procedure 4.3. Create a Custom Valve

  1. Create the Valve class

    Create a subclass of org.apache.catalina.valves.ValveBase.
    package org.jboss.samplevalves;
    
    import org.apache.catalina.valves.ValveBase;
    import org.apache.catalina.connector.Request;
    import org.apache.catalina.connector.Response;
    
    public class restrictedUserAgentsValve extends ValveBase {
    
    }
    
  2. Implement the invoke method

    The invoke() method is called when this valve is executed in the pipeline. The request and response objects are passed as parameters. Perform any processing and modification of the request and response here.
    public void invoke(Request request, Response response)
    {
    
    }
    
  3. Invoke the next pipeline step

    The last thing the invoke method must do is invoke the next step of the pipeline and pass the modified request and response objects along. This is done using the getNext().invoke() method
    getNext().invoke(request, response);
    
  4. Optional: Specify parameters

    If the valve must be configurable, enable this by adding a parameter. Do this by adding an instance variable and a setter method for each parameter.
    private String restrictedUserAgents = null;
    
    public void setRestricteduseragents(String mystring) 
    {
       this.restrictedUserAgents = mystring;
    }
    

Example 4.2. Sample Custom Valve

package org.jboss.samplevalves;

import java.io.IOException;
import java.util.regex.Pattern;

import javax.servlet.ServletException;
import org.apache.catalina.valves.ValveBase;
import org.apache.catalina.connector.Request;
import org.apache.catalina.connector.Response;

public class restrictedUserAgentsValve extends ValveBase 
{
    private String restrictedUserAgents = null;

    public void setRestricteduseragents(String mystring) 
    {
        this.restrictedUserAgents = mystring;
    }

    public void invoke(Request request, Response response) throws IOException, ServletException 
    {
      String agent = request.getHeader("User-Agent");
      System.out.println("user-agent: " + agent + " : " + restrictedUserAgents);
      if (Pattern.matches(restrictedUserAgents, agent)) 
      {
         System.out.println("user-agent: " + agent + " matches: " + restrictedUserAgents);
         response.addHeader("Connection", "close");
      }
      getNext().invoke(request, response);
    }
}

Chapter 5. Logging for Developers

5.1. Introduction

5.1.1. About Logging

Logging is the practice of recording a series of messages from an application that provide a record (or log) of the application's activities.
Log messages provide important information for developers when debugging an application and for system administrators maintaining applications in production.
Most modern logging frameworks in Java also include other details such as the exact time and the origin of the message.

5.1.2. Application Logging Frameworks Supported By JBoss LogManager

JBoss LogManager supports the following logging frameworks:

5.1.3. About Log Levels

Log levels are an ordered set of enumerated values that indicate the nature and severity of a log message. The level of a given log message is specified by the developer using the appropriate methods of their chosen logging framework to send the message.
JBoss EAP 6 supports all the log levels used by the supported application logging frameworks. The most commonly used six log levels are (in order of lowest to highest): TRACE, DEBUG, INFO, WARN, ERROR and FATAL.
Log levels are used by log categories and handlers to limit the messages they are responsible for. Each log level has an assigned numeric value which indicates its order relative to other log levels. Log categories and handlers are assigned a log level and they only process log messages of that level or higher. For example a log handler with the level of WARN will only record messages of the levels WARN, ERROR and FATAL.

5.1.4. Supported Log Levels

Table 5.1. Supported Log Levels

Log Level Value Description
FINEST 300
-
FINER 400
-
TRACE 400
Use for messages that provide detailed information about the running state of an application. Log messages of TRACE are usually only captured when debugging an application.
DEBUG 500
Use for messages that indicate the progress individual requests or activities of an application. Log messages of DEBUG are usually only captured when debugging an application.
FINE 500
-
CONFIG 700
-
INFO 800
Use for messages that indicate the overall progress of the application. Often used for application startup, shutdown and other major lifecycle events.
WARN 900
Use to indicate a situation that is not in error but is not considered ideal. May indicate circumstances that may lead to errors in the future.
WARNING 900
-
ERROR 1000
Use to indicate an error that has occurred that could prevent the current activity or request from completing but will not prevent the application from running.
SEVERE 1000
-
FATAL 1100
Use to indicate events that could cause critical service failure and application shutdown and possibly cause JBoss EAP 6 to shutdown.

5.1.5. Default Log File Locations

These are the log files that get created for the default logging configurations. The default configuration writes the server log files using periodic log handlers

Table 5.2. Default Log File for a standalone server

Log File Description
EAP_HOME/standalone/log/server.log
The Server Log. Contains all server log messages, including server startup messages.

Table 5.3. Default Log Files for a managed domain

Log File Description
EAP_HOME/domain/log/host-controller.log
Host Controller boot log. Contains log messages related to the startup of the host controller.
EAP_HOME/domain/log/process-controller.log
Process controller boot log. Contains log messages related to the startup of the process controller.
EAP_HOME/domain/servers/SERVERNAME/log/server.log
The server log for the named server. Contains all log messages for that server, including server startup messages.

5.2. Logging with the JBoss Logging Framework

5.2.1. About JBoss Logging

JBoss Logging is the application logging framework that is included in JBoss EAP 6.
JBoss Logging provide an easy way to add logging to an application. You add code to your application that uses the framework to send log messages in a defined format. When the application is deployed to an application server, these messages can be captured by the server and displayed and/or written to file according to the server's configuration.

5.2.2. Features of JBoss Logging

  • Provides an innovative, easy to use "typed" logger.
  • Full support for internationalization and localization. Translators work with message bundles in properties files while developers can work with interfaces and annotations.
  • Build-time tooling to generate typed loggers for production, and runtime generation of typed loggers for development.

5.2.3. Add Logging to an Application with JBoss Logging

To log messages from your application you create a Logger object (org.jboss.logging.Logger) and call the appropriate methods of that object. This task describes the steps required to add support for this to your application.

Prerequisites

You must meet the following conditions before continuing with this task:
  • If you are using Maven as your build system, the project must already be configured to include the JBoss Maven Repository. Refer to Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”
  • The JBoss Logging JAR files must be in the build path for your application. How you do this depends on whether you build your application using JBoss Developer Studio or with Maven.
    • When building using JBoss Developer Studio this can be done selecting Project -> Properties from the JBoss Developer Studio menu, selecting Targeted Runtimes and ensuring the runtime for JBoss EAP 6 is checked.
    • When building using Maven this can be done by adding the following dependency configuration to your project's pom.xml file.
      <dependency>
         <groupId>org.jboss.logging</groupId>
         <artifactId>jboss-logging</artifactId>
         <version>3.1.2.GA-redhat-1</version>
         <scope>provided</scope>
      </dependency>
      
    You do not need to include the JARs in your built application because JBoss EAP 6 provides them to deployed applications.
Once your project is setup correctly. You need to follow the following steps for each class that you want to add logging to:
  1. Add imports

    Add the import statements for the JBoss Logging class namespaces that you will be using. At a minimum you will need to import import org.jboss.logging.Logger.
    import org.jboss.logging.Logger;
    
  2. Create a Logger object

    Create an instance of org.jboss.logging.Logger and initialize it by calling the static method Logger.getLogger(Class). Red Hat recommends creating this as a single instance variable for each class.
    private static final Logger LOGGER = Logger.getLogger(HelloWorld.class);
    
  3. Add logging messages

    Add calls to the methods of the Logger object to your code where you want it to send log messages. The Logger object has many different methods with different parameters for different types of messages. The easiest to use are:
    debug(Object message)
    info(Object message)
    error(Object message)
    trace(Object message)
    fatal(Object message)
    These methods send a log message with the corresponding log level and the message parameter as a string.
    LOGGER.error("Configuration file not found.");
    
    For the complete list of JBoss Logging methods refer to the org.jboss.logging package in the JBoss EAP 6 API Documentation.

Example 5.1. Using JBoss Logging when opening a properties file

This example shows an extract of code from a class that loads customized configuration for an application from a properties file. If the specified file is not found, a ERROR level log message is recorded.
import org.jboss.logging.Logger;
public class LocalSystemConfig
{
   private static final Logger LOGGER = Logger.getLogger(LocalSystemConfig.class);

   public Properties openCustomProperties(String configname) throws CustomConfigFileNotFoundException
   {
      Properties props = new Properties();
      try 
      {
         LOGGER.info("Loading custom configuration from "+configname);
         props.load(new FileInputStream(configname));
      }
      catch(IOException e) //catch exception in case properties file does not exist
      {
         LOGGER.error("Custom configuration file ("+configname+") not found. Using defaults.");
         throw new CustomConfigFileNotFoundException(configname);
      }
      
      return props;
   }

5.3. Logging Profiles

5.3.1. About Logging Profiles

Important

Logging Profiles are only available in version 6.1.0 and later.
Logging Profiles are independent sets of logging configuration that can be assigned to deployed applications. A logging profile can define handlers, categories and a root logger just like the regular logging subsystem but cannot refer to configuration in other profiles or the main logging subsystem. The design of logging profiles mimics the logging subsystem for ease of configuration.
The use of logging profiles allows administrators to create logging configuration that is specific to one or more applications without affecting any other logging configuration. Because each profile is defined in the server configuration it means that the logging configuration can be changed without requiring that the affected applications be re-deployed.
Each logging profile can have the following configuration:
  • A unique name. This is required.
  • Any number of log handlers.
  • Any number of log categories.
  • Up to one root logger.
An application can specify a logging profile to use in it's MANIFEST.MF file, using the Logging-profile attribute.

Important

Logging profiles cannot be configured using the management console.

5.3.2. Specify a Logging Profile in an Application

An application specifies the logging profile to use in its MANIFEST.MF file.

Prerequisites:

  1. You must know the name of the logging profile that has been setup on the server for this application to use. Ask your server administrator for the name of the profile to use.

Procedure 5.1. Add Logging Profile configuration to an Application

  • Edit MANIFEST.MF

    If your application does not have a MANIFEST.MF file: create one with the following content, replacing NAME with the required profile name.
    Manifest-Version: 1.0
          Logging-Profile: NAME
    
    If your application already has a MANIFEST.MF file: add the following line to it, replacing NAME with the required profile name.
    Logging-Profile: NAME
    

Note

If you are using Maven and the maven-war-plugin, you can put your MANIFEST.MF file in src/main/resources/META-INF/ and add the following configuration to your pom.xml file.
<plugin>
      <artifactId>maven-war-plugin</artifactId>
      <configuration>
        <archive>
          <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>  
        </archive>
      </configuration>
   </plugin>
When the application is deployed it will use the configuration in the specified logging profile for its log messages.

Chapter 6. Internationalization and Localization

6.1. Introduction

6.1.1. About Internationalization

Internationalization is the process of designing software so that it can be adapted to different languages and regions without engineering changes.

6.1.2. About Localization

Localization is the process of adapting internationalized software for a specific region or language by adding locale-specific components and translations of text.

6.2. JBoss Logging Tools

6.2.1. Overview

6.2.1.1. JBoss Logging Tools Internationalization and Localization

JBoss Logging Tools is a Java API that provides support for the internationalization and localization of log messages, exception messages, and generic strings. In addition to providing a mechanism for translation, JBoss Logging tools also provides support for unique identifiers for each log message.
Internationalized messages and exceptions are created as method definitions inside of interfaces annotated using org.jboss.logging annotations. It is not necessary to implement the interfaces, JBoss Logging Tools does this at compile time. Once defined you can use these methods to log messages or obtain exception objects in your code.
Internationalized logging and exception interfaces created with JBoss Logging Tools can be localized by creating a properties file for each bundle containing the translations for a specific language and region. JBoss Logging Tools can generate template property files for each bundle that can then be edited by a translator.
JBoss Logging Tools creates an implementation of each bundle for each corresponding translations property file in your project. All you have to do is use the methods defined in the bundles and JBoss Logging Tools ensures that the correct implementation is invoked for your current regional settings.
Message ids and project codes are unique identifiers that are prepended to each log message. These unique identifiers can be used in documentation to make it easy to find information about log messages. With adequate documentation, the meaning of a log message can be determined from the identifiers regardless of the language that the message was written in.

6.2.1.2. JBoss Logging Tools Quickstart

The JBoss Logging Tools quickstart, logging-tools, contains a simple Maven project that demonstrates the features of JBoss Logging Tools. It has been used extensively in this documentation for code samples.
Refer to this quickstart for a complete working demonstration of all the features described in this documentation.

6.2.1.3. Message Logger

A Message Logger is an interface that is used to define internationalized log messages. A Message Logger interface is annotated with @org.jboss.logging.MessageLogger.

6.2.1.4. Message Bundle

A message bundle is an interface that can be used to define generic translatable messages and Exception objects with internationalized messages . A message bundle is not used for creating log messages.
A message bundle interface is annotated with @org.jboss.logging.MessageBundle.

6.2.1.5. Internationalized Log Messages

Internationalized Log Messages are log messages created by defining a method in a Message Logger. The method must be annotated with the @LogMessage and @Message annotations and specify the log message using the value attribute of @Message. Internationalized log messages are localized by providing translations in a properties file.
JBoss Logging Tools generates the required logging classes for each translation at compile time and invokes the correct methods for the current locale at runtime.

6.2.1.6. Internationalized Exceptions

An internationalized exception is an exception object returned from a method defined in a message bundle. Message bundle methods that return Java Exception objects can be annotated to define a default exception message. The default message is replaced with a translation if one is found in a matching properties file for the current locale. Internationalized exceptions can also have project codes and message ids assigned to them.

6.2.1.7. Internationalized Messages

An internationalized message is a string returned from a method defined in a message bundle. Message bundle methods that return Java String objects can be annotated to define the default content of that String, known as the message. The default message is replaced with a translation if one is found in a matching properties file for the current locale.

6.2.1.8. Translation Properties Files

Translation properties files are Java properties files that contain the translations of messages from one interface for one locale, country, and variant. Translation properties files are used by the JBoss Logging Tools to generated the classes that return the messages.

6.2.1.9. JBoss Logging Tools Project Codes

Project codes are strings of characters that identify groups of messages. They are displayed at the beginning of each log message, prepended to the message Id. Project codes are defined with the projectCode attribute of the @MessageLogger annotation.

6.2.1.10. JBoss Logging Tools Message Ids

Message Ids are numbers, that when combined with a project code, uniquely identify a log message. Message Ids are displayed at the beginning of each log message, appended to the project code for the message. Message Ids are defined with the id attribute of the @Message annotation.

6.2.2. Creating Internationalized Loggers, Messages and Exceptions

6.2.2.1. Create Internationalized Log Messages

This task shows you how to use JBoss Logging Tools to create internationalized log messages by creating MessageLogger interfaces. It does not cover all optional features or the localization of those log messages.
Refer to the logging-tools quick start for a complete example.

Prerequisites:

  1. You must already have a working Maven project. Refer to Section 6.2.6.1, “JBoss Logging Tools Maven Configuration”.
  2. The project must have the required maven configuration for JBoss Logging Tools.

Procedure 6.1. Create an Internationalized Log Message Bundle

  1. Create an Message Logger interface

    Add a Java interface to your project to contain the log message definitions. Name the interface descriptively for the log messages that will be defined in it.
    The log message interface has the following requirements:
    • It must be annotated with @org.jboss.logging.MessageLogger.
    • It must extend org.jboss.logging.BasicLogger.
    • The interface must define a field of that is a typed logger that implements this interface. Do this with the getMessageLogger() method of org.jboss.logging.Logger.
    package com.company.accounts.loggers;
    
    import org.jboss.logging.BasicLogger;
    import org.jboss.logging.Logger;
    import org.jboss.logging.MessageLogger;
    
    @MessageLogger(projectCode="")
    interface AccountsLogger extends BasicLogger
    {
       AccountsLogger LOGGER = Logger.getMessageLogger(
             AccountsLogger.class,
             AccountsLogger.class.getPackage().getName() );
    }
    
  2. Add method definitions

    Add a method definition to the interface for each log message. Name each method descriptively for the log message that it represents.
    Each method has the following requirements:
    • The method must return void.
    • It must be annotated with the @org.jboss.logging.LogMessage annotation.
    • It must be annotated with the @org.jboss.logging.Message annotation.
    • The value attribute of @org.jboss.logging.Message contains the default log message. This is the message that is used if no translation is available.
    @LogMessage
    @Message(value = "Customer query failed, Database not available.")
    void customerQueryFailDBClosed();
    
    The default log level is INFO.
  3. Invoke the methods

    Add the calls to the interface methods in your code where the messages must be logged from. It is not necessary to create implementations of the interfaces, the annotation processor does this for you when the project is compiled.
    AccountsLogger.LOGGER.customerQueryFailDBClosed();
    
    The custom loggers are sub-classed from BasicLogger so the logging methods of BasicLogger (debug(), error() etc) can also be used. It is not necessary to create other loggers to log non-internationalized messages.
    AccountsLogger.LOGGER.error("Invalid query syntax.");
    
RESULT: the project now supports one or more internationalized loggers that can now be localized.

6.2.2.2. Create and Use Internationalized Messages

This task shows you how to create internationalized messages and how to use them. This task does not cover all optional features or the process of localizing those messages.
Refer to the logging-tools quickstart for a complete example.

Prerequisites

  1. You have a working Maven project using the JBoss EAP 6 repository. Refer to Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.
  2. The required Maven configuration for JBoss Logging Tools has been added. Refer to Section 6.2.6.1, “JBoss Logging Tools Maven Configuration”.

Procedure 6.2. Create and Use Internationalized Messages

  1. Create an interface for the exceptions

    JBoss Logging Tools defines internationalized messages in interfaces. Name each interface descriptively for the messages that will be defined in it.
    The interface has the following requirements:
    • It must be declared as public
    • It must be annotated with @org.jboss.logging.MessageBundle.
    • The interface must define a field that is a message bundle of the same type as the interface.
    @MessageBundle(projectCode="")
    public interface GreetingMessageBundle 
    {
       GreetingMessageBundle MESSAGES = Messages.getBundle(GreetingMessageBundle.class);
    }
    
  2. Add method definitions

    Add a method definition to the interface for each message. Name each method descriptively for the message that it represents.
    Each method has the following requirements:
    • It must return an object of type String.
    • It must be annotated with the @org.jboss.logging.Message annotation.
    • The value attribute of @org.jboss.logging.Message must be set to the default message. This is the message that is used if no translation is available.
    @Message(value = "Hello world.")
       String helloworldString();
    
  3. Invoke methods

    Invoke the interface methods in your application where you need to obtain the message.
    System.console.out.println(helloworldString());
    
RESULT: the project now supports internationalized message strings that can be localized.

6.2.2.3. Create Internationalized Exceptions

This task shows you how to create internationalized exceptions and how to use them. This task does not cover all optional features or the process of localization of those exceptions.
Refer to the logging-tools quick start for a complete example.
For this task it is assumed that you already have a software project, that is being built in either JBoss Developer Studio or Maven, to which you want to add internationalized exceptions.

Procedure 6.3. Create and use Internationalized Exceptions

  1. Add JBoss Logging Tools configuration

    Add the required project configuration to support JBoss Logging Tools. Refer to Section 6.2.6.1, “JBoss Logging Tools Maven Configuration”
  2. Create an interface for the exceptions

    JBoss Logging Tools defines internationalized exceptions in interfaces. Name each interface descriptively for the exceptions that will be defined in it.
    The interface has the following requirements:
    • It must be declared as public.
    • It must be annotated with @org.jboss.logging.MessageBundle.
    • The interface must define a field that is a message bundle of the same type as the interface.
    @MessageBundle(projectCode="")
    public interface ExceptionBundle 
    {
       ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);
    }
    
    
  3. Add method definitions

    Add a method definition to the interface for each exception. Name each method descriptively for the exception that it represents.
    Each method has the following requirements:
    • It must return an object of type Exception or a sub-type of Exception.
    • It must be annotated with the @org.jboss.logging.Message annotation.
    • The value attribute of @org.jboss.logging.Message must be set to the default exception message. This is the message that is used if no translation is available.
    • If the exception being returned has a constructor that requires parameters in addition to a message string, then those parameters must be supplied in the method definition using the @Param annotation. The parameters must be the same type and order as the constructor.
    @Message(value = "The config file could not be opened.")
    IOException configFileAccessError();
    
    @Message(id = 13230, value = "Date string '%s' was invalid.")
    ParseException dateWasInvalid(String dateString, @Param int errorOffset);
    
  4. Invoke methods

    Invoke the interface methods in your code where you need to obtain one of the exceptions. The methods do not throw the exceptions, they return the exception object which you can then throw.
    try 
    {
       propsInFile=new File(configname);
       props.load(new FileInputStream(propsInFile));
    }
    catch(IOException ioex) //in case props file does not exist
    {
       throw ExceptionBundle.EXCEPTIONS.configFileAccessError(); 
    }
    
RESULT: the project now supports internationalized exceptions that can be localized.

6.2.3. Localizing Internationalized Loggers, Messages and Exceptions

6.2.3.1. Generate New Translation Properties Files with Maven

Projects that are being built with Maven can generate empty translation property files for each Message Logger and Message Bundle it contains. These files can then be used as new translation property files.
The following procedure shows how to configure a Maven project to generate new translation property files.
Refer to the logging-tools quick start for a complete example.

Prerequisites:

  1. You must already have a working Maven project.
  2. The project must already be configured for JBoss Logging Tools.
  3. The project must contain one or more interfaces that define internationalized log messages or exceptions.

Procedure 6.4. Generate New Translation Properties Files with Maven

  1. Add Maven configuration

    Add the -AgenereatedTranslationFilePath compiler argument to the Maven compiler plug-in configuration and assign it the path where the new files will be created.
    <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-compiler-plugin</artifactId>
       <version>2.3.2</version>
       <configuration> 
          <source>1.6</source>
          <target>1.6</target>             
          <compilerArgument>
          -AgeneratedTranslationFilesPath=${project.basedir}/target/generated-translation-files
          </compilerArgument>
          <showDeprecation>true</showDeprecation>
       </configuration>
    </plugin>
    
    The above configuration will create the new files in the target/generated-translation-files directory of your Maven project.
  2. Build the project

    Build the project using Maven.
    [Localhost]$ mvn compile
One properties files is created per interface annotated with @MessageBundle or @MessageLogger. The new files are created in a subdirectory corresponding to the Java package that each interface is declared in.
Each new file is named using the following syntax where InterfaceName is the name of the interface that this file was generated for: InterfaceName.i18n_locale_COUNTRY_VARIANT.properties.
These files can now be copied into your project as the basis for new translations.

6.2.3.2. Translate an Internationalized Logger, Exception or Message

Logging and Exception messages defined in interfaces using JBoss Logging Tools can have translations provided in properties files.
The following procedure shows how to create and use a translation properties file. It is assumed that you already have a project with one or more interfaces defined for internationalized exceptions or log messages.
Refer to the logging-tools quick start for a complete example.

Prerequisites

  1. You must already have a working Maven project.
  2. The project must already be configured for JBoss Logging Tools.
  3. The project must contain one or interfaces that define internationalized log messages or exceptions.
  4. The project must be configured to generate template translation property files.

Procedure 6.5. Translate an internationalized logger, exception or message

  1. Generate the template properties files

    Run the mvn compile command to create the template translation properties files.
  2. Add the template file to your project

    Copy the template for the interfaces that you want to translate from the directory where they were created into the src/main/resources directory of your project. The properties files must be in the same package as the interfaces they are translating.
  3. Rename the copied template file

    Rename the copy of the template file according to the translation it will contain. E.g. GreeterLogger.i18n_fr_FR.properties.
  4. Translate the contents of the template.

    Edit the new translation properties file to contain the appropriate translation.
    # Level: Logger.Level.INFO
    # Message: Hello message sent.
    logHelloMessageSent=Bonjour message envoyé.
    
    Repeat steps two, three, and four for each translation of each bundle being performed.
RESULT: The project now contains translations for one or more message or logger bundles. Building the project will generate the appropriate classes to log messages with the supplied translations. It is not necessary to explicitly invoke methods or supply parameters for specific languages, JBoss Logging Tools automatically uses the correct class for the current locale of the application server.
The source code of the generated classes can be viewed under target/generated-sources/annotations/.

6.2.4. Customizing Internationalized Log Messages

6.2.4.1. Add Message Ids and Project Codes to Log Messages

This task shows how to add message ids and project codes to internationalized log messages created using JBoss Logging Tools. A log message must have both a project code and message id for them to be displayed in the log. If a message does not have both a project code and a message id, then neither is displayed.
Refer to the logging-tools quick start for a complete example.

Prerequisites

  1. You must already have a project with internationalized log messages. Refer to Section 6.2.2.1, “Create Internationalized Log Messages”.
  2. You need to know what the project code you will be using is. You can use a single project code, or define different ones for each interface.

Procedure 6.6. Add message Ids and Project Codes to Log Messages

  1. Specify the project code for the interface.

    Specify the project code using the projectCode attribute of the @MessageLogger annotation attached to a custom logger interface. All messages that are defined in the interface will use that project code.
    @MessageLogger(projectCode="ACCNTS")
    interface AccountsLogger extends BasicLogger
    {
    
    }
    
  2. Specify Message Ids

    Specify a message id for each message using the id attribute of the @Message annotation attached to the method that defines the message.
    @LogMessage
    @Message(id=43, value = "Customer query failed, Database not available.")  void customerQueryFailDBClosed();
    
The log messages that have both a message ID and project code have been associated with them will prepend these to the logged message.
10:55:50,638 INFO  [com.company.accounts.ejb] (MSC service thread 1-4) ACCNTS000043: Customer query failed, Database not available.

6.2.4.2. Specify the Log Level for a Message

The default log level of a message defined by an interface by JBoss Logging Tools is INFO. A different log level can be specified with the level attribute of the @LogMessage annotation attached to the logging method.

Procedure 6.7. Specify the log level for a message

  1. Specify level attribute

    Add the level attribute to the @LogMessage annotation of the log message method definition.
  2. Assign log level

    Assign the level attribute the value of the log level for this message. The valid values for level are the six enumerated constants defined in org.jboss.logging.Logger.Level: DEBUG, ERROR, FATAL, INFO, TRACE, and WARN.
    Import org.jboss.logging.Logger.Level;
    
    @LogMessage(level=Level.ERROR)
    @Message(value = "Customer query failed, Database not available.")
    void customerQueryFailDBClosed();
    
    
Invoking the logging method in the above sample will produce a log message at the level of ERROR.
10:55:50,638 ERROR  [com.company.app.Main] (MSC service thread 1-4) 
 Customer query failed, Database not available.

6.2.4.3. Customize Log Messages with Parameters

Custom logging methods can define parameters. These parameters are used to pass additional information to be displayed in the log message. Where the parameters appear in the log message is specified in the message itself using either explicit or ordinary indexing.

Procedure 6.8. Customize log messages with parameters

  1. Add parameters to method definition

    Parameters of any type can be added to the method definition. Regardless of type, the String representation of the parameter is what is displayed in the message.
  2. Add parameter references to the log message

    References can use explicit or ordinary indexes.
    • To use ordinary indexes, insert the characters %s in the message string where you want each parameter to appear. The first instance of %s will insert the first parameter, the second instance will insert the second parameter, and so on.
    • To use explicit indexes, insert the characters %{#} in the message where # is the number of the parameter you want to appear.

Important

Using explicit indexes allows the parameter references in the message to be in a different order than they are defined in the method. This is important for translated messages which may require different ordering of parameters.
The number of parameters must match the number of references to the parameters in the specified message or the code will not compile. A parameter marked with the @Cause annotation is not included in the number of parameters.

Example 6.1. Message parameters using ordinary indexes

@LogMessage(level=Logger.Level.DEBUG)
@Message(id=2, value="Customer query failed, customerid:%s, user:%s")
void customerLookupFailed(Long customerid, String username);

Example 6.2. Message parameters using explicit indexes

@LogMessage(level=Logger.Level.DEBUG)
@Message(id=2, value="Customer query failed, customerid:%{1}, user:%{2}")
void customerLookupFailed(Long customerid, String username);

6.2.4.4. Specify an Exception as the Cause of a Log Message

JBoss Logging Tools allows one parameter of a custom logging method to be defined as the cause of the message. This parameter must be of the type Throwable or any of its sub-classes and is marked with the @Cause annotation. This parameter cannot be referenced in the log message like other parameters and is displayed after the log message.
The following procedure shows how to update a logging method using the @Cause parameter to indicate the "causing" exception. It is assumed that you have already created internationalized logging messages to which you want to add this functionality.

Procedure 6.9. Specify an exception as the cause of a log message

  1. Add the parameter

    Add a parameter of the type Throwable or a sub-class to the method.
    @Message(id=404, value="Loading configuration failed. Config file:%s")
    void loadConfigFailed(Exception ex, File file);
    
  2. Add the annotation

    Add the @Cause annotation to the parameter.
    import org.jboss.logging.Cause
    
    @Message(value = "Loading configuration failed. Config file: %s")
    void loadConfigFailed(@Cause Exception ex, File file);
    
    
  3. Invoke the method

    When the method is invoked in your code, an object of the correct type must be passed and will be displayed after the log message.
    try 
    {
       confFile=new File(filename);
       props.load(new FileInputStream(confFile));
    }
    catch(Exception ex) //in case properties file cannot be read
    {
         ConfigLogger.LOGGER.loadConfigFailed(ex, filename);
    }
    
    
    Below is the output of the above code samples if the code threw an exception of type FileNotFoundException.
    10:50:14,675 INFO [com.company.app.Main] (MSC service thread 1-3) Loading configuration failed. Config file: customised.properties
    java.io.FileNotFoundException: customised.properties (No such file or directory)
       at java.io.FileInputStream.open(Native Method)
       at java.io.FileInputStream.<init>(FileInputStream.java:120)
       at com.company.app.demo.Main.openCustomProperties(Main.java:70)
       at com.company.app.Main.go(Main.java:53)
       at com.company.app.Main.main(Main.java:43)
    

6.2.5. Customizing Internationalized Exceptions

6.2.5.1. Add Message Ids and Project Codes to Exception Messages

The following procedure shows the steps required to add message IDs and project codes to internationalized Exception messages created using JBoss Logging Tools.
Message IDs and project codes are unique identifiers that are prepended to each message displayed by internationalized exceptions. These identifying codes make it possible to create a reference of all the exception messages for an application so that someone can lookup the meaning of an exception message written in language that they do not understand.

Prerequisites

  1. You must already have a project with internationalized exceptions. Refer to Section 6.2.2.3, “Create Internationalized Exceptions”.
  2. You need to know what the project code you will be using is. You can use a single project code, or define different ones for each interface.

Procedure 6.10. Add message IDs and project codes to exception messages

  1. Specify a project code

    Specify the project code using the projectCode attribute of the @MessageBundle annotation attached to a exception bundle interface. All messages that are defined in the interface will use that project code.
    @MessageBundle(projectCode="ACCTS")
    interface ExceptionBundle
    {
       ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);
    }
    
  2. Specify message IDs

    Specify a message id for each exception using the id attribute of the @Message annotation attached to the method that defines the exception.
    @Message(id=143, value = "The config file could not be opened.")
    IOException configFileAccessError();
    

Important

A message that has both a project code and message ID displays them prepended to the message. If a message does not have both a project code and a message ID, neither is displayed.

Example 6.3. Creating internationalized exceptions

This exception bundle interface has the project code of ACCTS, with a single exception method with the id of 143.
@MessageBundle(projectCode="ACCTS")
interface ExceptionBundle
{
    ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);

    @Message(id=143, value = "The config file could not be opened.")
    IOException configFileAccessError();
}
The exception object can be obtained and thrown using the following code.
throw ExceptionBundle.EXCEPTIONS.configFileAccessError();
This would display an exception message like the following:
Exception in thread "main" java.io.IOException: ACCTS000143: The config file could not be opened.
at com.company.accounts.Main.openCustomProperties(Main.java:78)
at com.company.accounts.Main.go(Main.java:53)
at com.company.accounts.Main.main(Main.java:43)

6.2.5.2. Customize Exception Messages with Parameters

Exception bundle methods that define exceptions can specify parameters to pass additional information to be displayed in the exception message. Where the parameters appear in the exception message is specified in the message itself using either explicit or ordinary indexing.
The following procedure shows the steps required to use method parameters to customize method exceptions.

Procedure 6.11. Customize an exception message with parameters

  1. Add parameters to method definition

    Parameters of any type can be added to the method definition. Regardless of type, the String representation of the parameter is what is displayed in the message.
  2. Add parameter references to the exception message

    References can use explicit or ordinary indexes.
    • To use ordinary indexes, insert the characters %s in the message string where you want each parameter to appear. The first instance of %s will insert the first parameter, the second instance will insert the second parameter, and so on.
    • To use explicit indexes, insert the characters %{#} in the message where #is the number of the parameter you want to appear.
    Using explicit indexes allows the parameter references in the message to be in a different order than they are defined in the method. This is important for translated messages which may require different ordering of parameters.

Important

The number of parameters must match the number of references to the parameters in the specified message or the code will not compile. A parameter marked with the @Cause annotation is not included in the number of parameters.

Example 6.4. Using ordinary indexes

@Message(id=143, value = "The config file %s could not be opened.")
IOException configFileAccessError(File config);

Example 6.5. Using explicit indexes

@Message(id=143, value = "The config file %{1} could not be opened.")
IOException configFileAccessError(File config);

6.2.5.3. Specify One Exception as the Cause of Another Exception

Exceptions returned by exception bundle methods can have another exception specified as the underlying cause. This is done by adding a parameter to the method and annotating the parameter with @Cause. This parameter is used to pass the causing exception. This parameter cannot be referenced in the exception message.
The following procedure shows how to update a method from an exception bundle using the @Cause parameter to indicate the causing exception. It is assumed that you have already created an exception bundle to which you want to add this functionality.

Procedure 6.12. Specify one exception as the cause of another exception

  1. Add the parameter

    Add the a parameter of the type Throwable or a sub-class to the method.
    @Message(id=328, value = "Error calculating: %s.")
    ArithmeticException calculationError(Throwable cause, String msg);
    
  2. Add the annotation

    Add the @Cause annotation to the parameter.
    import org.jboss.logging.Cause
    
    @Message(id=328, value = "Error calculating: %s.")
    ArithmeticException calculationError(@Cause Throwable cause, String msg);
    
  3. Invoke the method

    Invoke the interface method to obtain an exception object. The most common use case is to throw a new exception from a catch block using the caught exception as the cause.
    try 
    {
       ...
    }
    catch(Exception ex)
    {
       throw ExceptionBundle.EXCEPTIONS.calculationError(
                                        ex, "calculating payment due per day");
    }
    

Example 6.6. Specify one exception as the cause of another exception

This exception bundle defines a single method that returns an exception of type ArithmeticException.
@MessageBundle(projectCode = "TPS")
interface CalcExceptionBundle 
{
	CalcExceptionBundle EXCEPTIONS = Messages.getBundle(CalcExceptionBundle.class);

    @Message(id=328, value = "Error calculating: %s.")
    ArithmeticException calcError(@Cause Throwable cause, String value);

}
This code snippet performs an operation that throws an exception because it attempts to divide an integer by zero. The exception is caught and a new exception is created using the first one as the cause.
int totalDue = 5;
int daysToPay = 0;
int amountPerDay;

try
{
   amountPerDay = totalDue/daysToPay;
}
catch (Exception ex)
{
   throw CalcExceptionBundle.EXCEPTIONS.calcError(ex, "payments per day");
}
This is what the exception message looks like:
Exception in thread "main" java.lang.ArithmeticException: TPS000328: Error calculating: payments per day.
	at com.company.accounts.Main.go(Main.java:58)
	at com.company.accounts.Main.main(Main.java:43)
Caused by: java.lang.ArithmeticException: / by zero
	at com.company.accounts.Main.go(Main.java:54)
	... 1 more

6.2.6. Reference

6.2.6.1. JBoss Logging Tools Maven Configuration

To build a Maven project that uses JBoss Logging Tools for internationalization you must make the following changes to the project's configuration in the pom.xml file.
Refer to the logging-tools quick start for an example of a complete working pom.xml file.
  1. JBoss Maven Repository must be enabled for the project. Refer to Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.
  2. The Maven dependencies for jboss-logging and jboss-logging-processor must be added. Both of dependencies are available in JBoss EAP 6 so the scope element of each can be set to provided as shown.
    <dependency>
       <groupId>org.jboss.logging</groupId>
       <artifactId>jboss-logging-processor</artifactId>
       <version>1.0.0.Final</version>
       <scope>provided</scope>
    </dependency>
    
    <dependency>
       <groupId>org.jboss.logging</groupId>
       <artifactId>jboss-logging</artifactId>
       <version>3.1.0.GA</version>
       <scope>provided</scope>
    </dependency>
    
  3. The maven-compiler-plugin must be at least version 2.2 and be configured for target and generated sources of 1.6.
    <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-compiler-plugin</artifactId>
       <version>2.3.2</version>
       <configuration>
          <source>1.6</source>
          <target>1.6</target>
       </configuration>
    </plugin>
    

6.2.6.2. Translation Property File Format

The property files used for translations of messages in JBoss Logging Tools are standard Java property files. The format of the file is the simple line-oriented, key=value pair format described in the documentation for the java.util.Properties class, http://docs.oracle.com/javase/6/docs/api/java/util/Properties.html.
The file name format has the following format:
InterfaceName.i18n_locale_COUNTRY_VARIANT.properties 
  • InterfaceName is the name of the interface that the translations apply to.
  • locale, COUNTRY, and VARIANT identify the regional settings that the translation applies to.
  • locale and COUNTRY specify the language and country using the ISO-639 and ISO-3166 Language and Country codes respectively. COUNTRY is optional.
  • VARIANT is an optional identifier that can be used to identify translations that only apply to a specific operating system or browser.
The properties contained in the translation file are the names of the methods from the interface being translated. The assigned value of the property is the translation. If a method is overloaded then this is indicated by appending a dot and then the number of parameters to the name. Methods for translation can only be overloaded by supplying a different number of parameters.

Example 6.7. Sample Translation Properties File

File name: GreeterService.i18n_fr_FR_POSIX.properties.
# Level: Logger.Level.INFO
# Message: Hello message sent.
logHelloMessageSent=Bonjour message envoyé.

6.2.6.3. JBoss Logging Tools Annotations Reference

The following annotations are defined in JBoss Logging for use with internationalization and localization of log messages, strings, and exceptions.

Table 6.1. JBoss Logging Tools Annotations

Annotation Target Description Attributes
@MessageBundle Interface
Defines the interface as a Message Bundle.
projectCode
@MessageLogger Interface
Defines the interface as a Message Logger.
projectCode
@Message Method
Can be used in Message Bundles and Message Loggers. In a Message Logger it defines a method as being a localized logger. In a Message Bundle it defines the method as being one that returns a localized String or Exception object.
value, id
@LogMessage Method
Defines a method in a Message Logger as being a logging method.
level (default INFO)
@Cause Parameter
Defines a parameter as being one that passes an Exception as the cause of either a Log message or another Exception.
-
@Param Parameter
Defines a parameter as being one that is passed to the constructor of the Exception.
-

Chapter 7. Enterprise JavaBeans

7.1. Introduction
7.1.1. Overview of Enterprise JavaBeans
7.1.2. EJB 3.1 Feature Set
7.1.3. EJB 3.1 Lite
7.1.4. EJB 3.1 Lite Features
7.1.5. Enterprise Beans
7.1.6. Overview of Writing Enterprise Beans
7.1.7. Session Bean Business Interfaces
7.2. Creating Enterprise Bean Projects
7.2.1. Create an EJB Archive Project Using JBoss Developer Studio
7.2.2. Create an EJB Archive Project in Maven
7.2.3. Create an EAR Project containing an EJB Project
7.2.4. Add a Deployment Descriptor to an EJB Project
7.3. Session Beans
7.3.1. Session Beans
7.3.2. Stateless Session Beans
7.3.3. Stateful Session Beans
7.3.4. Singleton Session Beans
7.3.5. Add Session Beans to a Project in JBoss Developer Studio
7.4. Message-Driven Beans
7.4.1. Message-Driven Beans
7.4.2. Resource Adapters
7.4.3. Create a JMS-based Message-Driven Bean in JBoss Developer Studio
7.5. Invoking Session Beans
7.5.1. Invoke a Session Bean Remotely using JNDI
7.5.2. About EJB Client Contexts
7.5.3. Considerations When Using a Single EJB Context
7.5.4. Using Scoped EJB Client Contexts
7.5.5. Configure EJBs Using a Scoped EJB Client Context
7.5.6. EJB Client Properties
7.6. Container Interceptors
7.6.1. About Container Interceptors
7.6.2. Create a Container Interceptor Class
7.6.3. Configure a Container Interceptor
7.6.4. Change the Security Context Identity
7.6.5. Pass Additional Security For EJB Authentication
7.6.6. Use a Client Side Interceptor in an Application
7.7. Clustered Enterprise JavaBeans
7.7.1. About Clustered Enterprise JavaBeans (EJBs)
7.8. Reference
7.8.1. EJB JNDI Naming Reference
7.8.2. EJB Reference Resolution
7.8.3. Project dependencies for Remote EJB Clients
7.8.4. jboss-ejb3.xml Deployment Descriptor Reference

7.1. Introduction

7.1.1. Overview of Enterprise JavaBeans

Enterprise JavaBeans (EJB) 3.1 is an API for developing distributed, transactional, secure and portable Java EE applications through the use of server-side components called Enterprise Beans. Enterprise Beans implement the business logic of an application in a decoupled manner that encourages reuse. Enterprise JavaBeans 3.1 is documented as the Java EE specification JSR-318.
JBoss EAP 6 has full support for applications built using the Enterprise JavaBeans 3.1 specification. The EJB Container is implemented using the JBoss EJB3 community project, http://www.jboss.org/ejb3.

7.1.2. EJB 3.1 Feature Set

The following features are supported in EJB 3.1
  • Session Beans
  • Message Driven Beans
  • No-interface views
  • local interfaces
  • remote interfaces
  • JAX-WS web services
  • JAX-RS web services
  • Timer Service
  • Asynchronous Calls
  • Interceptors
  • RMI/IIOP interoperability
  • Transaction support
  • Security
  • Embeddable API
The following features are supported in EJB 3.1 but are proposed for "pruning". This means that these features may become optional in Java EE 7.
  • Entity Beans (container and bean-managed persistence)
  • EJB 2.1 Entity Bean client views
  • EJB Query Language (EJB QL)
  • JAX-RPC based Web Services (endpoints and client views)

7.1.3. EJB 3.1 Lite

EJB Lite is a sub-set of the EJB 3.1 specification. It provides a simpler version of the full EJB 3.1 specification as part of the Java EE 6 web profile.
EJB Lite simplifies the implementation of business logic in web applications with enterprise beans by:
  1. Only supporting the features that make sense for web-applications, and
  2. allowing EJBs to be deployed in the same WAR file as a web-application.

7.1.4. EJB 3.1 Lite Features

EJB Lite includes the following features:
  • Stateless, stateful, and singleton session beans
  • Local business interfaces and "no interface" beans
  • Interceptors
  • Container-managed and bean-managed transactions
  • Declarative and programmatic security
  • Embeddable API
The following features of EJB 3.1 are specifically not included:
  • Remote interfaces
  • RMI-IIOP Interoperability
  • JAX-WS Web Service Endpoints
  • EJB Timer Service
  • Asynchronous session bean invocations
  • Message-driven beans

7.1.5. Enterprise Beans

Enterprise beans are server-side application components as defined in the Enterprise JavaBeans (EJB) 3.1 specification, JSR-318. Enterprise beans are designed for the implementation of application business logic in a decoupled manner to encourage reuse.
Enterprise beans are written as Java classes and annotated with the appropriate EJB annotations. They can be deployed to the application server in their own archive (a JAR file) or be deployed as part of a Java EE application. The application server manages the lifecycle of each enterprise bean and provides services to them such as security, transactions, and concurrency management.
An enterprise bean can also define any number of business interfaces. Business interfaces provide greater control over which of the bean's methods are available to clients and can also allow access to clients running in remote JVMs.
There are three types of Enterprise Bean: Session beans, Message-driven beans and Entity beans.

Important

Entity beans are now deprecated in EJB 3.1 and Red Hat recommends the use of JPA entities instead. Red Hat only recommends the use of Entity beans for backwards compatibility with legacy systems.

7.1.6. Overview of Writing Enterprise Beans

Enterprise beans are server-side components designed to encapsulate business logic in a manner decoupled from any one specific application client. By implementing your business logic within enterprise beans you will be able to reuse those beans in multiple applications.
Enterprise beans are written as annotated Java classes and do not have to implement any specific EJB interfaces or be sub-classed from any EJB super classes to be considered an enterprise bean.
EJB 3.1 enterprise beans are packaged and deployed in Java archive (JAR) files. An enterprise bean JAR file can be deployed to your application server, or included in an enterprise archive (EAR) file and deployed with that application. It is also possible to deploy enterprise beans in a WAR file along side a web application if the beans comply with the EJB 3.1 Lite specification.

7.1.7. Session Bean Business Interfaces

7.1.7.1. Enterprise Bean Business Interfaces

An EJB business interface is a Java interface written by the bean developer which provides declarations of the public methods of a session bean that are available for clients. Session beans can implement any number of interfaces including none (a "no-interface" bean).
Business interfaces can be declared as local or remote interfaces but not both.

7.1.7.2. EJB Local Business Interfaces

An EJB local business interface declares the methods which are available when the bean and the client are in the same JVM. When a session bean implements a local business interface only the methods declared in that interface will be available to clients.

7.1.7.3. EJB Remote Business Interfaces

An EJB remote business interface declares the methods which are available to remote clients. Remote access to a session bean that implements a remote interface is automatically provided by the EJB container.
A remote client is any client running in a different JVM and can include desktop applications as well as web applications, services and enterprise beans deployed to a different application server.
Local clients can access the methods exposed by a remote business interface. This is done using the same methods as remote clients and incurs all the normal overhead of making a remote request.

7.1.7.4. EJB No-interface Beans

A session bean that does not implement any business interfaces is called a no-interface bean. All of the public methods of no-interface beans are accessible to local clients.
A session bean that implements a business interface can also be written to expose a "no-interface" view.

7.2. Creating Enterprise Bean Projects

7.2.1. Create an EJB Archive Project Using JBoss Developer Studio

This task describes how to create an Enterprise JavaBeans (EJB) project in JBoss Developer Studio.

Prerequisites

  • A server and server runtime for JBoss EAP 6 has been set up.

Procedure 7.1. Create an EJB Project in JBoss Developer Studio

  1. Create new project

    To open the New EJB Project wizard, navigate to the File menu, select New, and then EJB Project.
    New EJB Project wizard

    Figure 7.1. New EJB Project wizard


  2. Specify Details

    Supply the following details:
    • Project name.
      As well as the being the name of the project that appears in JBoss Developer Studio this is also the default filename for the deployed JAR file.
    • Project location.
      The directory where the project's files will be saved. The default is a directory in the current workspace.
    • Target Runtime.
      This is the server runtime used for the project. This will need to be set to the same JBoss EAP 6 runtime used by the server that you will be deploying to.
    • EJB module version. This is the version of the EJB specification that your enterprise beans will comply with. Red Hat recommends using 3.1.
    • Configuration. This allows you to adjust the supported features in your project. Use the default configuration for your selected runtime.
    Click Next to continue.
  3. Java Build Configuration

    This screen allows you to customize the directories will contain Java source files and the directory where the built output is placed.
    Leave this configuration unchanged and click Next.
  4. EJB Module settings

    Check the Generate ejb-jar.xml deployment descriptor checkbox if a deployment descriptor is required. The deployment descriptor is optional in EJB 3.1 and can be added later if required.
    Click Finish and the project is created and will be displayed in the Project Explorer.
    Newly created EJB Project in the Project Explorer

    Figure 7.2. Newly created EJB Project in the Project Explorer


  5. Add Build Artifact to Server for Deployment

    Open the Add and Remove dialog by right-clicking on the server you want to deploy the built artifact to in the server tab, and select "Add and Remove".
    Select the resource to deploy from the Available column and click the Add button. The resource will be moved to the Configured column. Click Finish to close the dialog.
    Add and Remove dialog

    Figure 7.3. Add and Remove dialog


Result
You now have an EJB Project in JBoss Developer Studio that can build and deploy to the specified server.
If no enterprise beans are added to the project then JBoss Developer Studio will display the warning "An EJB module must contain one or more enterprise beans." This warning will disappear once one or more enterprise beans have been added to the project.

7.2.2. Create an EJB Archive Project in Maven

This task demonstrates how to create a project using Maven that contains one or more enterprise beans packaged in a JAR file.

Prerequisites:

  • Maven is already installed.
  • You understand the basic usage of Maven.

Procedure 7.2. Create an EJB Archive project in Maven

  1. Create the Maven project

    An EJB project can be created using Maven's archetype system and the ejb-javaee6 archetype. To do this run the mvn command with parameters as shown:
     mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=ejb-javaee6 
    Maven will prompt you for the groupId, artifactId, version and package for your project.
    [localhost]$ mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=ejb-javaee6
    [INFO] Scanning for projects...
    [INFO]                                                                         
    [INFO] ------------------------------------------------------------------------
    [INFO] Building Maven Stub Project (No POM) 1
    [INFO] ------------------------------------------------------------------------
    [INFO] 
    [INFO] >>> maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom >>>
    [INFO] 
    [INFO] <<< maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom <<<
    [INFO] 
    [INFO] --- maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom ---
    [INFO] Generating project in Interactive mode
    [INFO] Archetype [org.codehaus.mojo.archetypes:ejb-javaee6:1.5] found in catalog remote
    Define value for property 'groupId': : com.shinysparkly
    Define value for property 'artifactId': : payment-arrangments
    Define value for property 'version':  1.0-SNAPSHOT: : 
    Define value for property 'package':  com.shinysparkly: : 
    Confirm properties configuration:
    groupId: com.company
    artifactId: payment-arrangments
    version: 1.0-SNAPSHOT
    package: com.company.collections
    Y: : 
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 32.440s
    [INFO] Finished at: Mon Oct 31 10:11:12 EST 2011
    [INFO] Final Memory: 7M/81M
    [INFO] ------------------------------------------------------------------------
    [localhost]$
    
  2. Add your enterprise beans

    Write your enterprise beans and add them to the project under the src/main/java directory in the appropriate sub-directory for the bean's package.
  3. Build the project

    To build the project, run the mvn package command in the same directory as the pom.xml file. This will compile the Java classes and package the JAR file. The built JAR file is named artifactId-version.jar and is placed in the target/ directory.
RESULT: You now have a Maven project that builds and packages a JAR file. This project can contain enterprise beans and the JAR file can be deployed to an application server.

7.2.3. Create an EAR Project containing an EJB Project

This task describes how to create a new Enterprise Archive (EAR) project in JBoss Developer Studio that contains an EJB Project.

Prerequisites

Procedure 7.3. Create an EAR Project containing an EJB Project

  1. Open the New EAR Application Project Wizard

    Navigate to the File menu, select New, then Project and the New Project wizard appears. Select Java EE/Enterprise Application Project and click Next.
    New EAR Application Project Wizard

    Figure 7.4. New EAR Application Project Wizard


  2. Supply details

    Supply the following details:
    • Project name.
      As well as the being the name of the project that appears in JBoss Developer Studio this is also the default filename for the deployed EAR file.
    • Project location.
      The directory where the project's files will be saved. The default is a directory in the current workspace.
    • Target Runtime.
      This is the server runtime used for the project. This will need to be set to the same JBoss EAP 6 runtime used by the server that you will be deploying to.
    • EAR version.
      This is the version of the Java Enterprise Edition specification that your project will comply with. Red Hat recommends using 6.
    • Configuration. This allows you to adjust the supported features in your project. Use the default configuration for your selected runtime.
    Click Next to continue.
  3. Add a new EJB Module

    New Modules can be added from the Enterprise Application page of the wizard. To add a new EJB Project as a module follow the steps below:
    1. Add new EJB Module

      Click New Module, uncheck Create Default Modules checkbox, select the Enterprise Java Bean and click Next. The New EJB Project wizard appears.
    2. Create EJB Project

      New EJB Project wizard is the same as the wizard used to create new standalone EJB Projects and is described in Section 7.2.1, “Create an EJB Archive Project Using JBoss Developer Studio”.
      The minimal details required to create the project are:
      • Project name
      • Target Runtime
      • EJB Module version
      • Configuration
      All the other steps of the wizard are optional. Click Finish to complete creating the EJB Project.
    The newly created EJB project is listed in the Java EE module dependencies and the checkbox is checked.
  4. Optional: add an application.xml deployment descriptor

    Check the Generate application.xml deployment descriptor checkbox if one is required.
  5. Click Finish

    Two new project will appear, the EJB project and the EAR project
  6. Add Build Artifact to Server for Deployment

    Open the Add and Remove dialog by right-clicking in the Servers tab on the server you want to deploy the built artifact to in the server tab, and select Add and Remove.
    Select the EAR resource to deploy from the Available column and click the Add button. The resource will be moved to the Configured column. Click Finish to close the dialog.
    Add and Remove dialog

    Figure 7.5. Add and Remove dialog


Result
You now have an Enterprise Application Project with a member EJB Project. This will build and deploy to the specified server as a single EAR deployment containing an EJB subdeployment.

7.2.4. Add a Deployment Descriptor to an EJB Project

An EJB deployment descriptor can be added to an EJB project that was created without one. To do this, follow the procedure below.

Perquisites:

  • You have a EJB Project in JBoss Developer Studio to which you want to add an EJB deployment descriptor.

Procedure 7.4. Add an Deployment Descriptor to an EJB Project

  1. Open the Project

    Open the project in JBoss Developer Studio.
  2. Add Deployment Descriptor

    Right-click on the Deployment Descriptor folder in the project view and select Generate Deployment Descriptor Stub.
    Adding a Deployment Descriptor

    Figure 7.6. Adding a Deployment Descriptor


The new file, ejb-jar.xml, is created in ejbModule/META-INF/. Double-clicking on the Deployment Descriptor folder in the project view will also open this file.

7.3. Session Beans

7.3.1. Session Beans

Session Beans are Enterprise Beans that encapsulate a set of related business processes or tasks and are injected into the classes that request them. There are three types of session bean: stateless, stateful, and singleton.

7.3.2. Stateless Session Beans

Stateless session beans are the simplest yet most widely used type of session bean. They provide business methods to client applications but do not maintain any state between method calls. Each method is a complete task that does not rely on any shared state within that session bean. Because there is no state, the application server is not required to ensure that each method call is performed on the same instance. This makes stateless session beans very efficient and scalable.

7.3.3. Stateful Session Beans

Stateful session beans are Enterprise Beans that provide business methods to client applications and maintain conversational state with the client. They should be used for tasks that must be done in several steps (method calls), each of which replies on the state of the previous step being maintained. The application server ensures that each client receives the same instance of a stateful session bean for each method call.

7.3.4. Singleton Session Beans

Singleton session beans are session beans that are instantiated once per application and every client request for a singleton bean goes to the same instance. Singleton beans are an implementation of the Singleton Design Pattern as described in the book Design Patterns: Elements of Reusable Object-Oriented Software by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides; published by Addison-Wesley in 1994.
Singleton beans provide the smallest memory footprint of all the session bean types but must be designed as thread-safe. EJB 3.1 provides container-managed concurrency (CMC) to allow developers to implement thread safe singleton beans easily. However singleton beans can also be written using traditional multi-threaded code (bean-managed concurrency or BMC) if CMC does not provide enough flexibility.

7.3.5. Add Session Beans to a Project in JBoss Developer Studio

JBoss Developer Studio has several wizards that can be used to quickly create enterprise bean classes. The following procedure shows how to use the JBoss Developer Studio wizards to add a session bean to a project.

Prerequisites:

  • You have a EJB or Dynamic Web Project in JBoss Developer Studio to which you want to add one or more session beans.

Procedure 7.5. Add Session Beans to a Project in JBoss Developer Studio

  1. Open the Project

    Open the project in JBoss Developer Studio.
  2. Open the "Create EJB 3.x Session Bean" wizard

    To open the Create EJB 3.x Session Bean wizard, navigate to the File menu, select New, and then Session Bean (EJB 3.x).
    Create EJB 3.x Session Bean wizard

    Figure 7.7. Create EJB 3.x Session Bean wizard


  3. Specify class information

    Supply the following details:
    • Project
      Verify the correct project is selected.
    • Source folder
      This is the folder that the Java source files will be created in. This should not usually need to be changed.
    • Package
      Specify the package that the class belongs to.
    • Class name
      Specify the name of the class that will be the session bean.
    • Superclass
      The session bean class can inherit from a super class. Specify that here if your session has a super class.
    • State type
      Specify the state type of the session bean: stateless, stateful, or singleton.
    • Business Interfaces
      By default the No-interface box is checked so no interfaces will be created. Check the boxes for the interfaces you wish to define and adjust the names if necessary.
      Remember that enterprise beans in a web archive (WAR) only support EJB 3.1 Lite and this does not include remote business interfaces.
    Click Next.
  4. Session Bean Specific Information

    You can enter in additional information here to further customize the session bean. It is not required to change any of the information here.
    Items that you can change are:
    • Bean name.
    • Mapped name.
    • Transaction type (Container managed or Bean managed).
    • Additional interfaces can be supplied that the bean must implement.
    • You can also specify EJB 2.x Home and Component interfaces if required.
  5. Finish

    Click Finish and the new session bean will be created and added to the project. The files for any new business interfaces will also be created if they were specified.
RESULT: A new session bean is added to the project.
New Session Bean in JBoss Developer Studio

Figure 7.8. New Session Bean in JBoss Developer Studio


7.4. Message-Driven Beans

7.4.1. Message-Driven Beans

Message-driven Beans (MDBs) provide an event driven model for application development. The methods of MDBs are not injected into or invoked from client code but are triggered by the receipt of messages from a messaging service such as a Java Messaging Service (JMS) server. The Java EE 6 specification requires that JMS is supported but other messaging systems can be supported as well.

7.4.2. Resource Adapters

A resource adapter is a deployable Java EE component that provides communication between a Java EE application and an Enterprise Information System (EIS) using the Java Connector Architecture (JCA) specification. A resource adapter is often provided by EIS vendors to allow easy integration of their products with Java EE applications.
An Enterprise Information System can be any other software system within an organization. Examples include Enterprise Resource Planning (ERP) systems, database systems, e-mail servers and proprietary messaging systems.
A resource adapter is packaged in a Resource Adapter Archive (RAR) file which can be deployed to JBoss EAP 6. A RAR file may also be included in an Enterprise Archive (EAR) deployment.

7.4.3. Create a JMS-based Message-Driven Bean in JBoss Developer Studio

This procedure shows how to add a JMS-based Message-Driven Bean to a project in JBoss Developer Studio. This procedure creates an EJB 3.x Message-Driven Bean that uses annotations.

Prerequisites:

  1. You must have an existing project open in JBoss Developer Studio.
  2. You must know the name and type of the JMS destination that the bean will be listening to.
  3. Support for Java Messaging Service (JMS) must be enabled in the JBoss EAP 6 configuration to which this bean will be deployed.

Procedure 7.6. Add a JMS-based Message-Driven Bean in JBoss Developer Studio

  1. Open the Create EJB 3.x Message-Driven Bean Wizard

    Go to FileNewOther. Select EJB/Message-Driven Bean (EJB 3.x) and click the Next button.
    Create EJB 3.x Message-Driven Bean Wizard

    Figure 7.9. Create EJB 3.x Message-Driven Bean Wizard


  2. Specify class file destination details

    There are three sets of details to specify for the bean class here: Project, Java class, and message destination.
    Project
    • If multiple projects exist in the Workspace, ensure that the correct one is selected in the Project menu.
    • The folder where the source file for the new bean will be created is ejbModule under the selected project's directory. Only change this if you have a specific requirement.
    Java class
    • The required fields are: Java package and class name.
    • It is not necessary to supply a Superclass unless the business logic of your application requires it.
    Message Destination
    These are the details you must supply for a JMS-based Message-Driven Bean:
    • Destination name. This is the queue or topic name that contains the messages that the bean will respond to.
    • By default the JMS checkbox is selected. Do not change this.
    • Set Destination type to Queue or Topic as required.
    Click the Next button.
  3. Enter Message-Driven Bean specific information

    The default values here are suitable for a JMS-based Message-Driven bean using Container-managed transactions.
    • Change the Transaction type to Bean if the Bean will use Bean-managed transactions.
    • Change the Bean name if a different bean name than the class name is required.
    • The JMS Message Listener interface will already be listed. You do not need to add or remove any interfaces unless they are specific to your applications business logic.
    • Leave the checkboxes for creating method stubs selected.
    Click the Finish button.
Result: The Message-Driven Bean is created with stub methods for the default constructor and the onMessage() method. A JBoss Developer Studio editor window opened with the corresponding file.

7.5. Invoking Session Beans

7.5.1. Invoke a Session Bean Remotely using JNDI

This task describes how to add support to a remote client for the invocation of session beans using JNDI. The task assumes that the project is being built using Maven.
The ejb-remote quickstart contains working Maven projects that demonstrate this functionality. The quickstart contains projects for both the session beans to deploy and the remote client. The code samples below are taken from the remote client project.
This task assumes that the session beans do not require authentication.

Prerequisites

The following prerequisites must be satisfied before beginning:
  • You must already have a Maven project created ready to use.
  • Configuration for the JBoss EAP 6 Maven repository has already been added.
  • The session beans that you want to invoke are already deployed.
  • The deployed session beans implement remote business interfaces.
  • The remote business interfaces of the session beans are available as a Maven dependency. If the remote business interfaces are only available as a JAR file then it is recommended to add the JAR to your Maven repository as an artifact. Refer to the Maven documentation for the install:install-file goal for directions, http://maven.apache.org/plugins/maven-install-plugin/usage.html
  • You need to know the hostname and JNDI port of the server hosting the session beans.
To invoke a session bean from a remote client you must first configure the project correctly.

Procedure 7.7. Add Maven Project Configuration for Remote Invocation of Session Beans

  1. Add the required project dependencies

    The pom.xml for the project must be updated to include the necessary dependencies.
  2. Add the jboss-ejb-client.properties file

    The JBoss EJB client API expects to find a file in the root of the project named jboss-ejb-client.properties that contains the connection information for the JNDI service. Add this file to the src/main/resources/ directory of your project with the following content.
    remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
    
    remote.connections=default
    
    remote.connection.default.host=localhost
    remote.connection.default.port = 4447
    remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
    
    
    Change the host name and port to match your server. 4447 is the default port number. For a secure connection, set the SSL_ENABLED line to true and uncomment the SSL_STARTTLS lines. The Remoting interface in the container supports secured and unsecured connections using the same port.
  3. Add dependencies for the remote business interfaces

    Add the Maven dependencies to the pom.xml for the remote business interfaces of the session beans.
    <dependency>
       <groupId>org.jboss.as.quickstarts</groupId>
       <artifactId>jboss-as-ejb-remote-server-side</artifactId>
       <type>ejb-client</type>
       <version>${project.version}</version>
    </dependency>
    
Now that the project has been configured correctly, you can add the code to access and invoke the session beans.

Procedure 7.8. Obtain a Bean Proxy using JNDI and Invoke Methods of the Bean

  1. Handle checked exceptions

    Two of the methods used in the following code (InitialContext() and lookup()) have a checked exception of type javax.naming.NamingException. These method calls must either be enclosed in a try/catch block that catches NamingException or in a method that is declared to throw NamingException. The ejb-remote quickstart uses the second technique.
  2. Create a JNDI Context

    A JNDI Context object provides the mechanism for requesting resources from the server. Create a JNDI context using the following code:
    final Hashtable jndiProperties = new Hashtable();
    jndiProperties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
    final Context context = new InitialContext(jndiProperties);
    
    The connection properties for the JNDI service are read from the jboss-ejb-client.properties file.
  3. Use the JNDI Context's lookup() method to obtain a bean proxy

    Invoke the lookup() method of the bean proxy and pass it the JNDI name of the session bean you require. This will return an object that must be cast to the type of the remote business interface that contains the methods you want to invoke.
    
    final RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
        "ejb:/jboss-as-ejb-remote-server-side/CalculatorBean!" + 
        RemoteCalculator.class.getName());
    
    
    
    Session bean JNDI names are defined using a special syntax.
  4. Invoke methods

    Now that you have a proxy bean object you can invoke any of the methods contained in the remote business interface.
    int a = 204;
    int b = 340;
    System.out.println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server");
    int sum = statelessRemoteCalculator.add(a, b);
    System.out.println("Remote calculator returned sum = " + sum);
    
    The proxy bean passes the method invocation request to the session bean on the server, where it is executed. The result is returned to the proxy bean which then returns it to the caller. The communication between the proxy bean and the remote session bean is transparent to the caller.
You should now be able to configure a Maven project to support invoking session beans on a remote server and write the code invoke the session beans methods using a proxy bean retrieved from the server using JNDI.

7.5.2. About EJB Client Contexts

JBoss EAP 6 introduced the EJB client API for managing remote EJB invocations. The JBoss EJB client API uses the EJBClientContext, which may be associated with and be used by one or more threads concurrently. The means an EJBClientContext can potentially contain any number of EJB receivers. An EJB receiver is a component that knows how to communicate with a server that is capable of handling the EJB invocation. Typically, EJB remote applications can be classified into the following:
  • A remote client, which runs as a standalone Java application.
  • A remote client, which runs within another JBoss EAP 6 instance.
Depending on the type of remote client, from an EJB client API point of view, there can potentially be more than one EJBClientContext within a JVM.
While standalone applications typically have a single EJBClientContext that may be backed by any number of EJB receivers, this isn't mandatory. If a standalone application has more than one EJBClientContext, an EJB client context selector is responsible for returning the appropriate context.
In case of remote clients that run within another JBoss EAP 6 instance, each deployed application will have a corresponding EJB client context. Whenever that application invokes another EJB, the corresponding EJB client context is used to find the correct EJB receiver, which then handles the invocation.

7.5.3. Considerations When Using a Single EJB Context

Summary
You must consider your application requirements when using a single EJB client context with standalone remote clients. For more information about the different types of remote clients, refer to: Section 7.5.2, “About EJB Client Contexts” .
Typical Process for a Remote Standalone Client with a Single EJB Client Context
A remote standalone client typically has just one EJB client context backed by any number of EJB receivers. The following is an example of a standalone remote client application:
public class MyApplication {
    public static void main(String args[]) {
        final javax.naming.Context ctxOne = new javax.naming.InitialContext();
        final MyBeanInterface beanOne = ctxOne.lookup("ejb:app/module/distinct/bean!interface");
        beanOne.doSomething();
        ...
    }
}
Remote client JNDI lookups are usually backed by a jboss-ejb-client.properties file, which is used to set up the EJB client context and the EJB receivers. This configuration also includes the security credentials, which are then used to create the EJB receiver that connects to the JBoss EAP 6 server. When the above code is invoked, the EJB client API looks for the EJB client context, which is then used to select the EJB receiver that will receive and process the EJB invocation request. In this case, there is just the single EJB client context, so that context is used by the above code to invoke the bean. The procedure to invoke a session bean remotely using JNDI is described in greater detail here: Section 7.5.1, “Invoke a Session Bean Remotely using JNDI” .
Remote Standalone Client Requiring Different Credentials
A user application may want to invoke a bean more than once, but connect to the JBoss EAP 6 server using different security credentials. The following is an example of a standalone remote client application that invokes the same bean twice:
public class MyApplication {
    public static void main(String args[]) {
        // Use the "foo" security credential connect to the server and invoke this bean instance
        final javax.naming.Context ctxOne = new javax.naming.InitialContext();
        final MyBeanInterface beanOne = ctxOne.lookup("ejb:app/module/distinct/bean!interface");
        beanOne.doSomething();
        ...
 
        // Use the "bar" security credential to connect to the server and invoke this bean instance
        final javax.naming.Context ctxTwo = new javax.naming.InitialContext();
        final MyBeanInterface beanTwo = ctxTwo.lookup("ejb:app/module/distinct/bean!interface");
        beanTwo.doSomething();
        ...
    }
}
In this case, the application wants to connect to the same server instance to invoke the EJB hosted on that server, but wants to use two different credentials while connecting to the server. Because the client application has a single EJB client context, which can have only one EJB receiver for each server instance, this means the above code uses just one credential to connect to the server and the code does not execute as the application expects it to.
Solution
Scoped EJB client contexts offer a solution to this issue. They provide a way to have more control over the EJB client contexts and their associated JNDI contexts, which are typically used for EJB invocations. For more information about scoped EJB client contexts, refer to Section 7.5.4, “Using Scoped EJB Client Contexts” and Section 7.5.5, “Configure EJBs Using a Scoped EJB Client Context” .

7.5.4. Using Scoped EJB Client Contexts

Summary
To invoke an EJB In earlier versions of JBoss EAP 6, you would typically create a JNDI context and pass it the PROVIDER_URL, which would point to the target server. Any invocations done on EJB proxies that were looked up using that JNDI context, would end up on that server. With scoped EJB client contexts, user applications have control over which EJB receiver is used for a specific invocation.
Use Scoped EJB Client Context in a Remote Standalone Client
Prior to the introduction of scoped EJB client contexts, the context was typically scoped to the client application. Scoped client contexts now allow the EJB client contexts to be scoped with the JNDI contexts. The following is an example of a standalone remote client application that invokes the same bean twice using a scoped EJB client context:
public class MyApplication { 
    public static void main(String args[]) {
 
        // Use the "foo" security credential connect to the server and invoke this bean instance
        final Properties ejbClientContextPropsOne = getPropsForEJBClientContextOne():
        final javax.naming.Context ctxOne = new javax.naming.InitialContext(ejbClientContextPropsOne);
        final MyBeanInterface beanOne = ctxOne.lookup("ejb:app/module/distinct/bean!interface");
        beanOne.doSomething();
        ...
        ctxOne.close();
 
        // Use the "bar" security credential to connect to the server and invoke this bean instance
        final Properties ejbClientContextPropsTwo = getPropsForEJBClientContextTwo():
        final javax.naming.Context ctxTwo = new javax.naming.InitialContext(ejbClientContextPropsTwo);
        final MyBeanInterface beanTwo = ctxTwo.lookup("ejb:app/module/distinct/bean!interface");
        beanTwo.doSomething();
        ...
        ctxTwo.close();
    }
}
To use the scoped EJB client context, you configure EJB client properties programmatically and pass the properties on context creation. The properties are the same set of properties that are used in the standard jboss-ejb-client.properties file. To scope the EJB client context to the JNDI context, you must also specify the org.jboss.ejb.client.scoped.context property and set its value to true. This property notifies the EJB client API that it must create an EJB client context, which is backed by EJB receivers, and that the created context is then scoped or visible only to the JNDI context that created it. Any EJB proxies looked up or invoked using this JNDI context will only know of the EJB client context associated with this JNDI context. Other JNDI contexts used by the application to lookup and invoke EJBs will not know about the other scoped EJB client contexts.
JNDI contexts that do not pass the org.jboss.ejb.client.scoped.context property and aren't scoped to an EJB client context will use the default behavior, which is to use the existing EJB client context that is typically tied to the entire application.
Scoped EJB client contexts provide user applications with the flexibility that was associated with the JNP based JNDI invocations in previous versions of JBoss EAP. It provides user applications with more control over which JNDI context communicates to which server and how it connects to that server.

Note

With the scoped context, the underlying resources are no longer handled by the container or the API, so you must close the InitialContext when it is no longer needed. When the InitialContext is closed, the resources are released immediately. The proxies that are bound to it are no longer valid and any invocation will throw an Exception. Failure to close the InitialContext may result in resource and performance issues.

7.5.5. Configure EJBs Using a Scoped EJB Client Context

Summary
EJBs can be configured using a map-based scoped context. This is achieved by programmatically populating a Properties map using the standard properties found in the jboss-ejb-client.properties, specifying true for the org.jboss.ejb.client.scoped.context property, and passing the properties on the InitialContext creation.
The benefit of using a scoped context is that it allows you to configure access without directly referencing the EJB or importing JBoss classes. It also provides a way to configure and load balance a host at runtime in a multithreaded environment.

Procedure 7.9. Configure an EJB Using a Map-Based Scoped Context

  1. Set the Properties

    Configure the EJB client properties programmatically, specifiying the same set of properties that are used in the standard jboss-ejb-client.properties file. To enable the scoped context, you must specify the org.jboss.ejb.client.scoped.context property and set its value to true. The following is an example that configures the properties programmatically.
    // Configure  EJB Client properties for the InitialContext
    Properties ejbClientContextProps = new Properties();
    ejbClientContextProps.put(“remote.connections”,”name1”);
    ejbClientContextProps.put(“remote.connection.name1.host”,”localhost”);
    ejbClientContextProps.put(“remote.connection.name1.port”,”4447”);
    // Property to enable scoped EJB client context which will be tied to the JNDI context
    ejbClientContextProps.put("org.jboss.ejb.client.scoped.context", “true”);
    
  2. Pass the Properties on the Context Creation

    // Create the context using the configured properties
    InitialContext ic = new InitialContext(ejbClientContextProps);
    MySLSB bean = ic.lookup("ejb:myapp/ejb//MySLSBBean!" + MySLSB.class.getName());
    
Additional Information
  • Contexts generated by lookup EJB proxies are bound by this scoped context and use only the relevant connection parameters. This makes it possible to create different contexts to access data within a client application or to independently access servers using different logins.
  • In the client, both the scoped InitialContext and the scoped proxy are passed to threads, allowing each thread to work with the given context. It is also possible to pass the proxy to multiple threads that can use it concurrently.
  • The scoped context EJB proxy is serialized on the remote call and then deserialized on the server. When it is deserialized, the scoped context information is removed and it returns to its default state. If the deserialized proxy is used on the remote server, because it no longer has the scoped context that was used when it was created, this can result in an EJBCLIENT000025 error or possibly call an unwanted target by using the EJB name.

7.5.6. EJB Client Properties

Summary
The following tables list properties that can be configured programmatically or in the jboss-ejb-client.properties file.
EJB Client Global Properties
The following table lists properties that are vaild for the whole library within the same scope.

Table 7.1. Global Properties

Property Name Description
endpoint.name
Name of the client endpoint. If not set, the default value is client-endpoint
This can be helpful to distinguish different endpoint settings because the thread name contains this property.
remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED
Boolean value that specifies whether the SSL protocol is enabled for all connections.
deployment.node.selector
The fully qualified name of the implementation of org.jboss.ejb.client.DeploymentNodeSelector.
This is used to load balance the invocation for the EJBs.
invocation.timeout
The timeout for the EJB handshake or method invocation request/response cycle. The value is in milliseconds.
The invocation of any method throws a java.util.concurrent.TimeoutException if the execution takes longer than the timeout period. The execution completes and the server is not interrupted.
reconnect.tasks.timeout
The timeout for the background reconnect tasks. The value is in milliseconds.
If a number of connections are down, the next client EJB invocation will use an algorithm to decide if a reconnect is necessary to find the right node.
org.jboss.ejb.client.scoped.context
Boolean value that specifies whether to enable the scoped EJB client context. The default value is false.
If set to true, the EJB Client will use the scoped context that is tied to the JNDI context. Otherwise the EJB client context will use the global selector in the JVM to determine the properties used to call the remote EJB and host.

EJB Client Connection Properties
The connection properties start with the prefix remote.connection.CONNECTION_NAME where the CONNECTION_NAME is a local identifer only used to uniquely identify the connection.

Table 7.2. Connection Properties

Property Name Description
remote.connections
A comma-separated list of active connection-names. Each connection is configured by using this name.
remote.connection.CONNECTION_NAME.host
The host name or IP for the connection.
remote.connection.CONNECTION_NAME.port
The port for the connection. The default value is 4447.
remote.connection.CONNECTION_NAME.username
The user name used to authenticate connection security.
remote.connection.CONNECTION_NAME.password
The password used to authenticate the user.
remote.connection.CONNECTION_NAME.connect.timeout
The timeout period for the initial connection. After that, the reconnect task will periodicaly check whether the connection can be established. The value is in milliseconds.
remote.connection.CONNECTION_NAME.callback.handler.class
Full qualified name of the CallbackHandler class. It will be used to establish the connection and can not changed as long as the connection is open.
remote.connection.CONNECTION_NAME.
channel.options.org.jboss.remoting3.RemotingOptions.MAX_OUTBOUND_MESSAGES
Integer value specifying the maximum number of outbound requests. The default is 80.
There is only one connection from the client (JVM) to the server to handle all invocations.
remote.connection.CONNECTION_NAME.
connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS
Boolean value that determines whether credentials must be provided by the client to connect successfully. The default value is true.
If set to true, the client must provide credentials. If set to false, invocation is allowed as long as the remoting connector does not request a security realm.
remote.connection.CONNECTION_NAME.
connect.options.org.xnio.Options.SASL_DISALLOWED_MECHANISMS
Disables certain SASL mechanisms used for authenticating during connection creation.
JBOSS_LOCAL_USER means the silent authentication mechanism, used when the client and server are on the same machine, is disabled.
remote.connection.CONNECTION_NAME.
connect.options.org.xnio.Options.SASL_POLICY_NOPLAINTEXT
Boolean value that enables or disables the use of plain text messages during the authentication. If using JAAS, it must be set to false to allow a plain text password.
remote.connection.CONNECTION_NAME.
connect.options.org.xnio.Options.SSL_ENABLED
Boolean value that specifies whether the SSL protocol is enabled for this connection.
remote.connection.CONNECTION_NAME.
connect.options.org.jboss.remoting3.RemotingOptions.HEARTBEAT_INTERVAL
Interval to send a heartbeat between client and server to preven automatic close, for example, in the case of a firewall. The value is in milliseconds.

EJB Client Cluster Properties
If the initial connection connects to a clustered environment, the topology of the cluster is received automatically and asynchronously. These properties are used to connect to each received member. Each property starts with the prefix remote.cluster.CLUSTER_NAME where the CLUSTER_NAME refers to the related to the servers Infinispan subsystem configuration.

Table 7.3. Cluster Properties

Property Name Description
remote.cluster.CLUSTER_NAME.
clusternode.selector
The fully qualified name of the implementation of org.jboss.ejb.client.ClusterNodeSelector.
This class, rather than org.jboss.ejb.clientDeploymentNodeSelector, is used to load balance EJB invocations in a clustered environment. If the cluster is completely down, the invocation will fail with No ejb receiver available.
remote.cluster.CLUSTER_NAME.
channel.options.org.jboss.remoting3.RemotingOptions.MAX_OUTBOUND_MESSAGES
Integer value specifying the maximum number of outbound requests that can be made to the entire cluster.
remote.cluster.CLUSTER_NAME.
node.NODE_NAME. channel.options.org.jboss.remoting3.RemotingOptions.MAX_OUTBOUND_MESSAGES
Integer value specifying the maximum number of outbound requests that can be made to this specific cluster-node.

7.6. Container Interceptors

7.6.1. About Container Interceptors

Standard Java EE interceptors, as defined by the JSR 318, Enterprise JavaBeans 3.1 specification, are expected to run after the container has completed security context propagation, transaction management, and other container provided invocation processing. This is a problem if the user application needs to intercept a call before a certain container specific interceptor is run.
Releases prior to JBoss EAP 6.0 provided a way to plug server side interceptors into the invocation flow so you could run user application specific logic before the container completed invocation processing. JBoss EAP 6.1 now implements this feature. This implementation allows standard Java EE interceptors to be used as container interceptors, meaning they use the same XSD elements that are allowed in ejb-jar.xml file for the 3.1 version of the ejb-jar deployment descriptor.
Positioning of the Container Interceptor in the Interceptor Chain
The container interceptors configured for an EJB are guaranteed to be run before the JBoss EAP 6.1 provided security interceptors, transaction management interceptors, and other server provided interceptors. This allows the user application specific container interceptors to process or configure any relevant context data before the invocation proceeds.
Differences Between the Container Interceptor and the Java EE Interceptor API
Although container interceptors are modeled to be similar to Java EE interceptors, there are some differences in the API semantics. For example, it is illegal for container interceptors to invoke the javax.interceptor.InvocationContext.getTarget() method because these interceptors are invoked long before the EJB components are setup or instantiated.

7.6.2. Create a Container Interceptor Class

Summary
Container interceptor classes are simple Plain Old Java Objects (POJOs). They use the @javax.annotation.AroundInvoke to mark the method that will be invoked during the invocation on the bean.
The following is an example of a container interceptor class that marks the iAmAround method for invocation:

Example 7.1. Container Interceptor Class Example


public class ClassLevelContainerInterceptor {
    @AroundInvoke
    private Object iAmAround(final InvocationContext invocationContext) throws Exception {
        return this.getClass().getName() + " " + invocationContext.proceed();
    }
}



To see an example of a container interceptor descriptor file configured to use this class, refer to the example jboss-ejb3.xml file here: Section 7.6.3, “Configure a Container Interceptor”.

7.6.3. Configure a Container Interceptor

Summary
Container interceptors use the standard Java EE interceptor libraries, meaning they use the same XSD elements that are allowed in ejb-jar.xml file for the 3.1 version of the ejb-jar deployment descriptor. Because they are based on the standard Jave EE interceptor libraries, container interceptors may only be configured using deployment descriptors. This was done by design so applications would not require any JBoss specific annotation or other library dependencies. For more information about container interceptors, refer to: Section 7.6.1, “About Container Interceptors”.

Procedure 7.10. Create the Descriptor File to Configure the Container Interceptor

  1. Create a jboss-ejb3.xml file in the META-INF directory of the EJB deployment.
  2. Configure the container interceptor elements in the descriptor file.
    1. Use the urn:container-interceptors:1.0 namespace to specify configuration of container interceptor elements.
    2. Use the <container-interceptors> element to specify the container interceptors.
    3. Use the <interceptor-binding> elements to bind the container interceptor to the EJBs. The interceptors can be bound in either of the following ways:
      • Bind the interceptor to all the EJBs in the deployment using the the * wildcard.
      • Bind the interceptor at the individual bean level using the specific EJB name.
      • Bind the interceptor at the specific method level for the EJBs.

      Note

      These elements are configured using the EJB 3.1 XSD in the same way it is done for Java EE interceptors.
  3. Review the following descriptor file for examples of the above elements.

    Example 7.2. jboss-ejb3.xml

    <jboss xmlns="http://www.jboss.com/xml/ns/javaee"
           xmlns:jee="http://java.sun.com/xml/ns/javaee"
           xmlns:ci ="urn:container-interceptors:1.0">
     
        <jee:assembly-descriptor>
            <ci:container-interceptors>
                <!-- Default interceptor -->
                <jee:interceptor-binding>
                    <ejb-name>*</ejb-name>
                    <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ContainerInterceptorOne</interceptor-class>
                </jee:interceptor-binding>
                <!-- Class level container-interceptor -->
                <jee:interceptor-binding>
                    <ejb-name>AnotherFlowTrackingBean</ejb-name>
                    <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ClassLevelContainerInterceptor</interceptor-class>
                </jee:interceptor-binding>
                <!-- Method specific container-interceptor -->
                <jee:interceptor-binding>
                    <ejb-name>AnotherFlowTrackingBean</ejb-name>
                    <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor</interceptor-class>
                    <method>
                        <method-name>echoWithMethodSpecificContainerInterceptor</method-name>
                    </method>
                </jee:interceptor-binding>
                <!-- container interceptors in a specific order -->
                <jee:interceptor-binding>
                    <ejb-name>AnotherFlowTrackingBean</ejb-name>
                    <interceptor-order>
                        <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ClassLevelContainerInterceptor</interceptor-class>
                        <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor</interceptor-class>
                        <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ContainerInterceptorOne</interceptor-class>
                    </interceptor-order>
                    <method>
                        <method-name>echoInSpecificOrderOfContainerInterceptors</method-name>
                    </method>
                </jee:interceptor-binding>
            </ci:container-interceptors>
        </jee:assembly-descriptor>
    </jboss>
    
    
    
    

    The XSD for the urn:container-interceptors:1.0 namespace is available here: https://github.com/jbossas/jboss-as/blob/master/ejb3/src/main/resources/jboss-ejb-container-interceptors_1_0.xsd.

7.6.4. Change the Security Context Identity

Summary
By default, when you make a remote call to an EJB deployed to the application server, the connection to the server is authenticated and any request received over this connection is executed as the identity that authenticated the connection. This is true for both client-to-server and server-to-server calls. If you need to use different identities from the same client, you normally need to open multiple connections to the server so that each one is authenticated as a different identity. Rather than open multiple client connections, you can give permission to the authenticated user to execute a request as a different user.
This topic describes how to to switch identities on the existing client connection. Refer to the ejb-security-interceptors quickstart for a complete working example. The following code examples are abridged versions of the code in the quickstart.

Procedure 7.11. Change the Identity of the Security Context

To change the identity of a secured connection, you must create the following 3 components.
  1. Create the client side interceptor

    This interceptor must implement the org.jboss.ejb.client.EJBClientInterceptor. The interceptor is expected to pass the requested identity through the context data map, which can be obtained via a call to EJBClientInvocationContext.getContextData(). The following is an example of client side interceptor code:
    public class ClientSecurityInterceptor implements EJBClientInterceptor {
    
        public void handleInvocation(EJBClientInvocationContext context) throws Exception {
            Principal currentPrincipal = SecurityActions.securityContextGetPrincipal();
    
            if (currentPrincipal != null) {
                Map<String, Object> contextData = context.getContextData();
                contextData.put(ServerSecurityInterceptor.DELEGATED_USER_KEY, currentPrincipal.getName());
            }
            context.sendRequest();
        }
    
        public Object handleInvocationResult(EJBClientInvocationContext context) throws Exception {
            return context.getResult();
        }
    }
    
    
    
    User applications can then plug in the interceptor in the EJBClientContext in one of the following ways:
    • Programmatically

      With this approach, you call the org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor) API and pass the order and the interceptor instance. The order is used to determine where exactly in the client interceptor chain this interceptor is placed.
    • ServiceLoader Mechanism

      This approach requires the creation of a META-INF/services/org.jboss.ejb.client.EJBClientInterceptor file and placing or packaging it in the classpath of the client application. The rules for the file are dictated by the Java ServiceLoader Mechanism. This file is expected to contain in each separate line the fully qualified class name of the EJB client interceptor implementation. The EJB client interceptor classes must be available in the classpath. EJB client interceptors added using the ServiceLoader mechanism are added to the end of the client interceptor chain, in the order they are found in the classpath. The ejb-security-interceptors quickstart uses this approach.
  2. Create and configure the server side container interceptor

    Container interceptor classes are simple Plain Old Java Objects (POJOs). They use the @javax.annotation.AroundInvoke to mark the method that will be invoked during the invocation on the bean. For more information about container interceptors, refer to: Section 7.6.1, “About Container Interceptors”.
    1. Create the container interceptor

      This interceptor receives the InvocationContext with the identity and requests the switch. The following is an abridged version of the actual code example:
          public class ServerSecurityInterceptor {
      
              private static final Logger logger = Logger.getLogger(ServerSecurityInterceptor.class);
              static final String DELEGATED_USER_KEY = ServerSecurityInterceptor.class.getName() + ".DelegationUser";
      
              @AroundInvoke
              public Object aroundInvoke(final InvocationContext invocationContext) throws Exception {
                  Principal desiredUser = null;
                  RealmUser connectionUser = null;
      
                  Map<String, Object> contextData = invocationContext.getContextData();
                  if (contextData.containsKey(DELEGATED_USER_KEY)) {
                      desiredUser = new SimplePrincipal((String) contextData.get(DELEGATED_USER_KEY));
                      Connection con = SecurityActions.remotingContextGetConnection();
                      if (con != null) {
                          UserInfo userInfo = con.getUserInfo();
                          if (userInfo instanceof SubjectUserInfo) {
                              SubjectUserInfo sinfo = (SubjectUserInfo) userInfo;
                              for (Principal current : sinfo.getPrincipals()) {
                                  if (current instanceof RealmUser) {
                                      connectionUser = (RealmUser) current;
                                      break;
                                  }
                              }
                          }
                      } else {
                          throw new IllegalStateException("Delegation user requested but no user on connection found.");
                      }
                  }
      
                  SecurityContext cachedSecurityContext = null;
                  boolean contextSet = false;
                  try {
                      if (desiredUser != null && connectionUser != null
                              && (desiredUser.getName().equals(connectionUser.getName()) == false)) {
                          // The final part of this check is to verify that the change does actually indicate a change in user.
                          try {
                              // We have been requested to switch user and have successfully identified the user from the connection
                              // so now we attempt the switch.
                              cachedSecurityContext = SecurityActions.securityContextSetPrincipalInfo(desiredUser,
                                      new OuterUserCredential(connectionUser));
                              // keep track that we switched the security context
                              contextSet = true;
                              SecurityActions.remotingContextClear();
                          } catch (Exception e) {
                              logger.error("Failed to switch security context for user", e);
                              // Don't propagate the exception stacktrace back to the client for security reasons
                              throw new EJBAccessException("Unable to attempt switching of user.");
                          }
                      }
                      return invocationContext.proceed();
                  } finally {
                      // switch back to original security context
                      if (contextSet) {
                          SecurityActions.securityContextSet(cachedSecurityContext);
                      }
                  }
              }
          }
      
    2. Configure the container interceptor

      For information on how to configure server side container interceptors, refer to: Section 7.6.3, “Configure a Container Interceptor”.
  3. Create the JAAS LoginModule

    This component is responsible for verifying that user is allowed to execute requests as the requested identity. The following code examples show the methods that peform the login and validation:
    @SuppressWarnings("unchecked")
    @Override
    public boolean login() throws LoginException {
        if (super.login() == true) {
            log.debug("super.login()==true");
            return true;
        }
    
        // Time to see if this is a delegation request.
        NameCallback ncb = new NameCallback("Username:");
        ObjectCallback ocb = new ObjectCallback("Password:");
    
        try {
            callbackHandler.handle(new Callback[] { ncb, ocb });
        } catch (Exception e) {
            if (e instanceof RuntimeException) {
                throw (RuntimeException) e;
            }
            return false; // If the CallbackHandler can not handle the required callbacks then no chance.
        }
        String name = ncb.getName();
        Object credential = ocb.getCredential();
        if (credential instanceof OuterUserCredential) {
            // This credential type will only be seen for a delegation request, if not seen then the request is not for us.
            if (delegationAcceptable(name, (OuterUserCredential) credential)) {
                identity = new SimplePrincipal(name);
                if (getUseFirstPass()) {
                    String userName = identity.getName();
                    if (log.isDebugEnabled())
                        log.debug("Storing username '" + userName + "' and empty password");
                    // Add the username and an empty password to the shared state map
                    sharedState.put("javax.security.auth.login.name", identity);
                    sharedState.put("javax.security.auth.login.password", "");
                }
                loginOk = true;
                return true;
            }
        }
        return false; // Attempted login but not successful.
    }
    
    
    
    protected boolean delegationAcceptable(String requestedUser, OuterUserCredential connectionUser) {
        if (delegationMappings == null) {
            return false;
        }
    
        String[] allowedMappings = loadPropertyValue(connectionUser.getName(), connectionUser.getRealm());
        if (allowedMappings.length == 1 && "*".equals(allowedMappings[1])) {
            // A wild card mapping was found.
            return true;
        }
        for (String current : allowedMappings) {
            if (requestedUser.equals(current)) {
                return true;
            }
        }
        return false;
    }
    
    
    
See the quickstart README file for complete instructions and more detailed information about the code.

7.6.5. Pass Additional Security For EJB Authentication

Summary
By default, when you make a remote call to an EJB deployed to the application server, the connection to the server is authenticated and any request received over this connection is executed using the credentials that authenticated the connection. Authentication at the connection level is dependent on the capabilities of the underlying SASL (Simple Authentication and Security Layer) mechanisms. Rather than write custom SASL mechanisms, you can open and authenticate a connection to the server, then later add additional security tokens prior to invoking an EJB. This topic describes how to to pass additional information on the existing client connection for EJB authentication.
The code examples below are for demonstration purposes only. They present only one possible approach and must be customized to suit the exact needs of the application. The password is exchanged using the SASL mechanism. If SASL DIGEST-MD5 Authentication is used, the password is still hashed with a challenge and not sent in the clear. The remaining tokens, however are sent in the clear. If those tokens contain any sensitive information, you may want to enable encryption for the connection.

Procedure 7.12. Pass Security Information for EJB Authentication

To supply an additional security token for an authenticated connection, you must create the following 3 components.
  1. Create the client side interceptor

    This interceptor must implement the org.jboss.ejb.client.EJBClientInterceptor. The interceptor is expected to pass the additional security token through the context data map, which can be obtained via a call to EJBClientInvocationContext.getContextData(). The following is an example of client side interceptor code that creates an additional security token:
    public class ClientSecurityInterceptor implements EJBClientInterceptor {
    
        public void handleInvocation(EJBClientInvocationContext context) throws Exception {
            Object credential = SecurityActions.securityContextGetCredential();
    
            if (credential != null && credential instanceof PasswordPlusCredential) {
                PasswordPlusCredential ppCredential = (PasswordPlusCredential) credential;
                Map<String, Object> contextData = context.getContextData();
                contextData.put(ServerSecurityInterceptor.SECURITY_TOKEN_KEY, 
                                  ppCredential.getAuthToken());
            }
            context.sendRequest();
        }
    
        public Object handleInvocationResult(EJBClientInvocationContext context) 
                throws Exception {
            return context.getResult();
        }
    }
    
    
    
    For information on how to plug the client interceptor into an application, refer to Section 7.6.6, “Use a Client Side Interceptor in an Application”.
  2. Create and configure the server side container interceptor

    Container interceptor classes are simple Plain Old Java Objects (POJOs). They use the @javax.annotation.AroundInvoke to mark the method that is invoked during the invocation on the bean. For more information about container interceptors, refer to: Section 7.6.1, “About Container Interceptors”.
    1. Create the container interceptor

      This interceptor retrieves the security authentication token from the context and passes it to the JAAS (Java Authentication and Authorization Service) domain for verification. The following is an example of container interceptor code:
      public class ServerSecurityInterceptor {
      
          private static final Logger logger = Logger.getLogger(ServerSecurityInterceptor.class);
          static final String SECURITY_TOKEN_KEY = ServerSecurityInterceptor.class.getName() + ".SecurityToken";
      
          @AroundInvoke
          public Object aroundInvoke(final InvocationContext invocationContext) throws Exception {
              Principal userPrincipal = null;
              RealmUser connectionUser = null;
              String authToken = null;
      
              Map<String, Object> contextData = invocationContext.getContextData();
              if (contextData.containsKey(SECURITY_TOKEN_KEY)) {
                  authToken = (String) contextData.get(SECURITY_TOKEN_KEY);
      
                  Connection con = SecurityActions.remotingContextGetConnection();
      
                  if (con != null) {
                      UserInfo userInfo = con.getUserInfo();
                      if (userInfo instanceof SubjectUserInfo) {
                          SubjectUserInfo sinfo = (SubjectUserInfo) userInfo;
                          for (Principal current : sinfo.getPrincipals()) {
                              if (current instanceof RealmUser) {
                                  connectionUser = (RealmUser) current;
                                  break;
                              }
                          }
                      }
                      userPrincipal = new SimplePrincipal(connectionUser.getName());
      
                  } else {
                      throw new IllegalStateException("Token authentication requested but no user on connection found.");
                  }
              }
      
              SecurityContext cachedSecurityContext = null;
              boolean contextSet = false;
              try {
                  if (userPrincipal != null && connectionUser != null && authToken != null) {
                      try {
                          // We have been requested to use an authentication token
                          // so now we attempt the switch.
                          cachedSecurityContext = SecurityActions.securityContextSetPrincipalCredential(userPrincipal,
                                  new OuterUserPlusCredential(connectionUser, authToken));
                          // keep track that we switched the security context
                          contextSet = true;
                          SecurityActions.remotingContextClear();
                      } catch (Exception e) {
                          logger.error("Failed to switch security context for user", e);
                          // Don't propagate the exception stacktrace back to the client for security reasons
                          throw new EJBAccessException("Unable to attempt switching of user.");
                      }
                  }
      
                  return invocationContext.proceed();
              } finally {
                  // switch back to original security context
                  if (contextSet) {
                      SecurityActions.securityContextSet(cachedSecurityContext);
                  }
              }
          }
      }
      
      
      
    2. Configure the container interceptor

      For information on how to configure server side container interceptors, refer to: Section 7.6.3, “Configure a Container Interceptor”.
  3. Create the JAAS LoginModule

    This custom module performs the authentication using the existing authenticated connection information plus any additional security token. The following is an example of code that uses the additional security token and performs the authentication:
    public class SaslPlusLoginModule extends AbstractServerLoginModule {
    
        private static final String ADDITIONAL_SECRET_PROPERTIES = "additionalSecretProperties";
        private static final String DEFAULT_AS_PROPERTIES = "additional-secret.properties";
        private Properties additionalSecrets;
        private Principal identity;
    
        @Override
        public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String, ?> sharedState, Map<String, ?> options) {
            addValidOptions(new String[] { ADDITIONAL_SECRET_PROPERTIES });
            super.initialize(subject, callbackHandler, sharedState, options);
            
            // Load the properties that contain the additional security tokens
            String propertiesName;
            if (options.containsKey(ADDITIONAL_SECRET_PROPERTIES)) {
                propertiesName = (String) options.get(ADDITIONAL_SECRET_PROPERTIES);
            } else {
                propertiesName = DEFAULT_AS_PROPERTIES;
            }
            try {
                additionalSecrets = SecurityActions.loadProperties(propertiesName);
            } catch (IOException e) {
                throw new IllegalArgumentException(String.format("Unable to load properties '%s'", propertiesName), e);
            }
        }
    
        @Override
        public boolean login() throws LoginException {
            if (super.login() == true) {
                log.debug("super.login()==true");
                return true;
            }
    
            // Time to see if this is a delegation request.
            NameCallback ncb = new NameCallback("Username:");
            ObjectCallback ocb = new ObjectCallback("Password:");
    
            try {
                callbackHandler.handle(new Callback[] { ncb, ocb });
            } catch (Exception e) {
                if (e instanceof RuntimeException) {
                    throw (RuntimeException) e;
                }
                return false; // If the CallbackHandler can not handle the required callbacks then no chance.
            }
    
            String name = ncb.getName();
            Object credential = ocb.getCredential();
    
            if (credential instanceof OuterUserPlusCredential) {
                OuterUserPlusCredential oupc = (OuterUserPlusCredential) credential;
                if (verify(name, oupc.getName(), oupc.getAuthToken())) {
                    identity = new SimplePrincipal(name);
                    if (getUseFirstPass()) {
                        String userName = identity.getName();
                        if (log.isDebugEnabled())
                            log.debug("Storing username '" + userName + "' and empty password");
                        // Add the username and an empty password to the shared state map
                        sharedState.put("javax.security.auth.login.name", identity);
                        sharedState.put("javax.security.auth.login.password", oupc);
                    }
                    loginOk = true;
                    return true;
                }
            }
    
            return false; // Attempted login but not successful.
        }
    
        private boolean verify(final String authName, final String connectionUser, final String authToken) {
            // For the purpose of this quick start we are not supporting switching users, this login module is validation an
            // additional security token for a user that has already passed the sasl process.
            return authName.equals(connectionUser) && authToken.equals(additionalSecrets.getProperty(authName));
        }
    
        @Override
        protected Principal getIdentity() {
            return identity;
        }
    
        @Override
        protected Group[] getRoleSets() throws LoginException {
            Group roles = new SimpleGroup("Roles");
            Group callerPrincipal = new SimpleGroup("CallerPrincipal");
            Group[] groups = { roles, callerPrincipal };
            callerPrincipal.addMember(getIdentity());
            return groups;
        }
    }
    
    
    
  4. Add the Custom LoginModule to the Chain

    You must add the new custom LoginModule to the correct location the chain so that it is invoked in the correct order. In this example, the SaslPlusLoginModule must be chained before the LoginModule that loads the roles with the password-stacking option set.
    • Configure the LoginModule Order using the Management CLI

      The following is an example of Management CLI commands that chain the custom SaslPlusLoginModule before the RealmDirect LoginModule that sets the password-stacking option.
      [standalone@localhost:9999 /] ./subsystem=security/security-domain=quickstart-domain:add(cache-type=default)
      [standalone@localhost:9999 /] ./subsystem=security/security-domain=quickstart-domain/authentication=classic:add
      [standalone@localhost:9999 /] ./subsystem=security/security-domain=quickstart-domain/authentication=classic/login-module=DelegationLoginModule:add(code=org.jboss.as.quickstarts.ejb_security_plus.SaslPlusLoginModule,flag=optional,module-options={password-stacking=useFirstPass})
      [standalone@localhost:9999 /] ./subsystem=security/security-domain=quickstart-domain/authentication=classic/login-module=RealmDirect:add(code=RealmDirect,flag=required,module-options={password-stacking=useFirstPass})
      For more information about the Management CLI, refer to the chapter entitled Management Interfaces in the Administration and Configuration Guide for JBoss EAP 6 located on the Customer Portal at https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/
    • Configure the LoginModule Order Manually

      The following is an example of XML that configures the LoginModule order in the security subsystem of the server configuration file. The custom SaslPlusLoginModule must precede the RealmDirect LoginModule so that it can verify the remote user before the user roles are loaded and the password-stacking option is set.
      <security-domain name="quickstart-domain" cache-type="default">
          <authentication>
              <login-module code="org.jboss.as.quickstarts.ejb_security_plus.SaslPlusLoginModule" flag="required">
                  <module-option name="password-stacking" value="useFirstPass"/>
              </login-module>
              <login-module code="RealmDirect" flag="required">
                  <module-option name="password-stacking" value="useFirstPass"/>
              </login-module>
          </authentication>
      </security-domain>
      
      
      
  5. Create the Remote Client

    In the following code example, assume the additional-secret.properties file accessed by the JAAS LoginModule above contains the following property:
    quickstartUser=7f5cc521-5061-4a5b-b814-bdc37f021acc
    
    
    
    The following code demonstrates how create the security token and set it before the the EJB call. The secret token is hard-coded for demonstration purposes only. This client simply prints the results to the console.
    import static org.jboss.as.quickstarts.ejb_security_plus.EJBUtil.lookupSecuredEJB;
    
    public class RemoteClient {
    
        /**
         * @param args
         */
        public static void main(String[] args) throws Exception {
            SimplePrincipal principal = new SimplePrincipal("quickstartUser");
            Object credential = new PasswordPlusCredential("quickstartPwd1!".toCharArray(), "7f5cc521-5061-4a5b-b814-bdc37f021acc");
    
            SecurityActions.securityContextSetPrincipalCredential(principal, credential);
            SecuredEJBRemote secured = lookupSecuredEJB();
    
            System.out.println(secured.getPrincipalInformation());
        }
    }
    
    
    

7.6.6. Use a Client Side Interceptor in an Application

Summary
You can plug a client-side interceptor into an application programmatically or using a ServiceLoader mechanism. The following procedure describes the two methods.

Procedure 7.13. Plug the Interceptor into

    • Programmatically

      With this approach, you call the org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor) API and pass the order and the interceptor instance. The order is used to determine where exactly in the client interceptor chain this interceptor is placed.
    • ServiceLoader Mechanism

      This approach requires the creation of a META-INF/services/org.jboss.ejb.client.EJBClientInterceptor file and placing or packaging it in the classpath of the client application. The rules for the file are dictated by the Java ServiceLoader Mechanism. This file is expected to contain in each separate line the fully qualified class name of the EJB client interceptor implementation. The EJB client interceptor classes must be available in the classpath. EJB client interceptors added using the ServiceLoader mechanism are added to the end of the client interceptor chain, in the order they are found in the classpath.

7.7. Clustered Enterprise JavaBeans

7.7.1. About Clustered Enterprise JavaBeans (EJBs)

EJB components can be clustered for high-availability scenarios. They use different protocols than HTTP components, so they are clustered in different ways. EJB 2 and 3 stateful and stateless beans can be clustered.
For information on singletons, refer here: Section 8.4, “Implement an HA Singleton”.

Note

EJB 2 entity beans cannot be clustered. This limitation is not expected to be changed.

7.8. Reference

7.8.1. EJB JNDI Naming Reference

The JNDI lookup name for a session bean has the syntax of:
 ejb:<appName>/<moduleName>/<distinctName>/<beanName>!<viewClassName>?stateful 
<appName>
If the session bean's JAR file has been deployed within an enterprise archive (EAR) then this is the name of that EAR. By default, the name of an EAR is its filename without the .ear suffix. The application name can also be overridden in its application.xml file. If the session bean is not deployed in an EAR then leave this blank.
<moduleName>
The module name is the name of the JAR file that the session bean is deployed in. By the default, the name of the JAR file is its filename without the .jar suffix. The module name can also be overridden in the JAR's ejb-jar.xml file.
<distinctName>
JBoss EAP 6 allows each deployment to specify an optional distinct name. If the deployment does not have a distinct name then leave this blank.
<beanName>
The bean name is the classname of the session bean to be invoked.
<viewClassName>
The view class name is the fully qualified classname of the remote interface. This includes the package name of the interface.
?stateful
The ?stateful suffix is required when the JNDI name refers to a stateful session bean. It is not included for other bean types.

7.8.2. EJB Reference Resolution

This section covers how JBoss implements @EJB and @Resource. Please note that XML always overrides annotations but the same rules apply.

Rules for the @EJB annotation

  • The @EJB annotation also has a mappedName() attribute. The specification leaves this as vendor specific metadata, but JBoss recognizes mappedName() as the global JNDI name of the EJB you are referencing. If you have specified a mappedName(), then all other attributes are ignored and this global JNDI name is used for binding.
  • If you specify @EJB with no attributes defined:
    @EJB 
    ProcessPayment myEjbref;
    Then the following rules apply:
    • The EJB jar of the referencing bean is searched for an EJB with the interface used in the @EJB injection. If there are more than one EJB that publishes same business interface, then an exception is thrown. If there is only one bean with that interface then that one is used.
    • Search the EAR for EJBs that publish that interface. If there are duplicates, then an exception is thrown. Otherwise the matching bean is returned.
    • Search globally in JBoss runtime for an EJB of that interface. Again, if duplicates are found, an exception is thrown.
  • @EJB.beanName() corresponds to <ejb-link>. If the beanName() is defined, then use the same algorithm as @EJB with no attributes defined except use the beanName() as a key in the search. An exception to this rule is if you use the ejb-link '#' syntax. The '#' syntax allows you to put a relative path to a jar in the EAR where the EJB you are referencing is located. Refer to the EJB 3.1 specification for more details.

7.8.3. Project dependencies for Remote EJB Clients

Maven projects that include the invocation of session beans from remote clients require the following dependencies from the JBoss EAP 6 Maven repository.

Table 7.4. Maven dependencies for Remote EJB Clients

GroupID ArtifactID
org.jboss.spec jboss-javaee-6.0
org.jboss.as jboss-as-ejb-client-bom
org.jboss.spec.javax.transaction jboss-transaction-api_1.1_spec
org.jboss.spec.javax.ejb jboss-ejb-api_3.1_spec
org.jboss jboss-ejb-client
org.jboss.xnio xnio-api
org.jboss.xnio xnio-nio
org.jboss.remoting3 jboss-remoting
org.jboss.sasl jboss-sasl
org.jboss.marshalling jboss-marshalling-river

With the exception of jboss-javaee-6.0 and jboss-as-ejb-client-bom, these dependencies must be added to the <dependencies> section of the pom.xml file.
The jboss-javaee-6.0 and jboss-as-ejb-client-bom dependencies should be added to the <dependencyManagement> section of your pom.xml with the scope of import.

Note

The artifactID's versions are subject to change. Refer to the Maven repository for the relevant version.
<dependencyManagement>
   <dependencies>
      <dependency>
         <groupId>org.jboss.spec</groupId>
         <artifactId>jboss-javaee-6.0</artifactId>
         <version>3.0.0.Final-redhat-1</version>
         <type>pom</type>
         <scope>import</scope>
      </dependency>

      <dependency>
         <groupId>org.jboss.as</groupId>
         <artifactId>jboss-as-ejb-client-bom</artifactId>
         <version>7.1.1.Final-redhat-1</version>
         <type>pom</type>
         <scope>import</scope>
      </dependency>
   </dependencies>
</dependencyManagement>
Refer to the remote-ejb/client/pom.xml for a complete example of dependency configuration for remote session bean invocation.

7.8.4. jboss-ejb3.xml Deployment Descriptor Reference

jboss-ejb3.xml is a custom deployment descriptor that can be used in either EJB JAR or WAR archives. In an EJB JAR archive it must be located in the META-INF/ directory. In a WAR archive it must be located in the WEB-INF/ directory.
The format is similar to ejb-jar.xml, using some of the same namespaces and providing some other additional namespaces. The contents of jboss-ejb3.xml are merged with the contents of ejb-jar.xml, with the jboss-ejb3.xml items taking precedence.
This document only covers the additional non-standard namespaces used by jboss-ejb3.xml. Refer to http://java.sun.com/xml/ns/javaee/ for documentation on the standard namespaces.
The root namespace is http://www.jboss.com/xml/ns/javaee.

Assembly descriptor namespaces

The following namespaces can all be used in the <assembly-descriptor> element. They can be used to apply their configuration to a single bean, or to all beans in the deployment by using \* as the ejb-name.
The clustering namespace: urn:clustering:1.0
xmlns:c="urn:clustering:1.0"
This allows you to mark EJB's as clustered. It is the deployment descriptor equivalent to @org.jboss.ejb3.annotation.Clustered.
<c:clustering>
   <ejb-name>DDBasedClusteredSFSB</ejb-name>
   <c:clustered>true</c:clustered>
</c:clustering>
The security namespace (urn:security)
xmlns:s="urn:security"
This allows you to set the security domain and the run-as principal for an EJB.
<s:security>
  <ejb-name>*</ejb-name>
  <s:security-domain>myDomain</s:security-domain>
  <s:run-as-principal>myPrincipal</s:run-as-principal>
</s:security>
The resource adaptor namespace: urn:resource-adapter-binding
xmlns:r="urn:resource-adapter-binding"
This allows you to set the resource adaptor for an Message-Driven Bean.
<r:resource-adapter-binding>
  <ejb-name>*</ejb-name>
  <r:resource-adapter-name>myResourceAdaptor</r:resource-adapter-name>
</r:resource-adapter-binding>
The IIOP namespace: urn:iiop
xmlns:u="urn:iiop"
The IIOP namespace is where IIOP settings are configured.
The pool namespace: urn:ejb-pool:1.0
xmlns:p="urn:ejb-pool:1.0"
This allows you to select the pool that is used by the included stateless session beans or Message-Driven Beans. Pools are defined in the server configuration.
<p:pool>
   <ejb-name>*</ejb-name>
   <p:bean-instance-pool-ref>my-pool</p:bean-instance-pool-ref>
</p:pool>
The cache namespace: urn:ejb-cache:1.0
xmlns:c="urn:ejb-cache:1.0"
This allows you to select the cache that is used by the included stateful session beans. Caches are defined in the server configuration.
<c:cache>
   <ejb-name>*</ejb-name>
   <c:cache-ref>my-cache</c:cache-ref>
</c:cache>

Example 7.3. Example jboss-ejb3.xml file

<?xml version="1.1" encoding="UTF-8"?>
   <jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
                  xmlns="http://java.sun.com/xml/ns/javaee"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:c="urn:clustering:1.0"
                  xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
                  version="3.1"
                  impl-version="2.0">
      <enterprise-beans>
         <message-driven>
            <ejb-name>ReplyingMDB</ejb-name>
            <ejb-class>org.jboss.as.test.integration.ejb.mdb.messagedestination.ReplyingMDB</ejb-class>
            <activation-config>
               <activation-config-property>
                  <activation-config-property-name>destination</activation-config-property-name>
                  <activation-config-property-value>java:jboss/mdbtest/messageDestinationQueue
                  </activation-config-property-value>
               </activation-config-property>
            </activation-config>
         </message-driven>
      </enterprise-beans>
      <assembly-descriptor>
         <c:clustering>
            <ejb-name>DDBasedClusteredSFSB</ejb-name>
            <c:clustered>true</c:clustered>
         </c:clustering>
      </assembly-descriptor>
   </jboss:ejb-jar>

Chapter 8. Clustering in Web Applications

8.1. Session Replication

8.1.1. About HTTP Session Replication

Session replication ensures that client sessions of distributable applications are not disrupted by failovers by nodes in a cluster. Each node in the cluster shares information about ongoing sessions, and can take them over if the originally-involved node disappears.
Session replication is the mechanism by which mod_cluster, mod_jk, mod_proxy, ISAPI, and NSAPI clusters provide high availability.

8.1.2. About the Web Session Cache

The web session cache can be configured when you use any of the HA profiles, including the standalone-ha.xml profile, or the managed domain profiles ha or full-ha. The most commonly configured elements are the cache mode and the number of cache owners for a distributed cache.
Cache Mode
The cache mode can either be REPL (the default) or DIST.
REPL
The REPL mode replicates the entire cache to every other node in the cluster. This is the safest option, but introduces more overhead.
DIST
The DIST mode is similar to the buddy mode provided in previous implementations. It reduces overhead by distributing the cache to the number of nodes specified in the owners parameter. This number of owners defaults to 2.
Owners
The owners parameter controls how many cluster nodes hold replicated copies of the session. The default is 2.

8.1.3. Configure the Web Session Cache

The web session cache defaults to REPL. If you wish to use DIST mode, run the following two commands in the Management CLI. If you use a different profile, change the profile name in the commands. If you use a standalone server, remove the /profile=ha portion of the commands.

Procedure 8.1. Configure the Web Session Cache

  1. Change the default cache mode to DIST.

    /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=dist)
    
  2. Set the number of owners for a distributed cache.

    The following command sets 5 owners. The default is 2.
    /profile=ha/subsystem=infinispan/cache-container=web/distributed-cache=dist/:write-attribute(name=owners,value=5)
    
  3. Change the default cache mode back to REPL.

    /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=repl)
    
  4. Restart the Server

    After changing the web cache mode, you must restart the server.
Result
Your server is configured for session replication. To use session replication in your own applications, refer to the following topic: Section 8.1.4, “Enable Session Replication in Your Application”.

8.1.4. Enable Session Replication in Your Application

Summary
To take advantage of JBoss EAP 6 High Availability (HA) features, you must configure your application to be distributable. This procedure shows how to do that, and then explains some of the advanced configuration options you can use.

Procedure 8.2. Make your Application Distributable

  1. Required: Indicate that your application is distributable.

    If your application is not marked as distributable, its sessions will never be distributed. Add the <distributable /> element inside the <web-app> tag of your application's web.xml descriptor file. Here is an example.

    Example 8.1. Minimum Configuration for a Distributable Application

    <?xml version="1.0"?>
    <web-app  xmlns="http://java.sun.com/xml/ns/j2ee"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
                                  http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" 
              version="2.4">
              
          <distributable/>
        
    </web-app>
    				
    
    
    

  2. Modify the default replication behavior if desired.

    If you want to change any of the values affecting session replication, you can override them inside a <replication-config> element which is a child element of the <jboss-web> element. For a given element, only include it if you want to override the defaults. The following example lists all of the default settings, and is followed by a table which explains the most commonly changed options.

    Example 8.2. Default <replication-config>Values

    <!DOCTYPE jboss-web PUBLIC
        "-//JBoss//DTD Web Application 5.0//EN"
        "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
    
    <jboss-web>
       
       <replication-config>
          <cache-name>custom-session-cache</cache-name>
          <replication-trigger>SET</replication-trigger>
          <replication-granularity>ATTRIBUTE</replication-granularity>
          <use-jk>false</use-jk>
          <max-unreplicated-interval>30</max-unreplicated-interval>
          <snapshot-mode>INSTANT</snapshot-mode>
          <snapshot-interval>1000</snapshot-interval>
          <session-notification-policy>com.example.CustomSessionNotificationPolicy</session-notification-policy>
      </replication-config>
    
    </jboss-web>
    				
    
    
    

Table 8.1. Common Options for session Replication

Option
Description
<replication-trigger>
Controls which conditions should trigger session data replication across the cluster. This option is necessary because after a mutable object stored as a session attribute is accessed from the session, the container has no clear way to know if the object has been modified and needs to be replicated, unless method setAttribute() is called directly.

Valid Values for <replication-trigger>

SET_AND_GET
This is the safest but worst-performing option. Session data is always replicated, even if its content has only been accessed, and not modified. This setting is preserved for legacy purposes only. To get the same behavior with better performance, you may, instead of using this setting, set <max_unreplicated_interval> to 0.
SET_AND_NON_PRIMITIVE_GET
The default value. Session data is only replicated if an object of a non-primitive type is accessed. This means that the object is not of a well-known Java type such as Integer, Long, or String.
SET
This option assumes that the application will explicitly call setAttributeon the session when the data needs to be replicated. It prevents unnecessary replication and can benefit overall performance, but is inherently unsafe.
Regardless of the setting, you can always trigger session replication by calling setAttribute().
<replication-granularity>
Determines the granularity of data that is replicated. It defaults to SESSION, but can be set to ATTRIBUTE instead, to increase performance on sessions where most attributes remain unchanged.

The following options rarely need to be changed.

Table 8.2. Less Commonly Changed Options for Session Replication

Option
Description
<useJK>
Whether to assume that a load balancer such as mod_cluster, mod_jk, or mod_proxy is in use. The default is false. If set to true, the container examines the session ID associated with each request and replaces the jvmRouteportion of the session ID if there is a failover.
<max-unreplicated-interval>
The maximum interval (in seconds) to wait after a session before triggering a replication of a session's timestamp, even if it is considered to be unchanged. This ensures that cluster nodes are aware of each session's timestamp and that an unreplicated session will not expire incorrectly during a failover. It also ensures that you can rely on a correct value for calls to method HttpSession.getLastAccessedTime()during a failover.
By default, no value is specified. This means that the jvmRoute configuration of the container determines whether JK failover is being used. A value of 0 causes the timestamp to be replicated whenever the session is accessed. A value of -1 causes the timestamp to be replicated only if other activity during the request triggers a replication. A positive value greater than HttpSession.getMaxInactiveInterval() is treated as a misconfiguration and converted to 0.
<snapshot-mode>
Specifies when sessions are replicated to other nodes. The default is INSTANTand the other possible value is INTERVAL.
In INSTANT mode, changes are replicated at the end of a request, by means of the request processing thread. The <snapshot-interval> option is ignored.
In INTERVAL mode, a background task runs at the interval specified by <snapshot-interval>, and replicates modified sessions.
<snapshot-interval>
The interval, in milliseconds, at which modified sessions should be replicated when using INTERVALfor the value of <snapshot-mode>.
<session-notification-policy>
The fully-qualified class name of the implementation of interface ClusteredSessionNotificationPolicy which governs whether servlet specification notifications are emitted to any registered HttpSessionListener, HttpSessionAttributeListener, or HttpSessionBindingListener.

8.2. HttpSession Passivation and Activation

8.2.1. About HTTP Session Passivation and Activation

Passivation is the process of controlling memory usage by removing relatively unused sessions from memory while storing them in persistent storage.
Activation is when passivated data is retrieved from persisted storage and put back into memory.
Passivation occurs at three different times in a HTTP session's lifetime:
  • When the container requests the creation of a new session, if the number of currently active session exceeds a configurable limit, the server attempts to passivate some sessions to make room for the new one.
  • Periodically, at a configured interval, a background task checks to see if sessions should be passivated.
  • When a web application is deployed and a backup copy of sessions active on other servers is acquired by the newly deploying web application's session manager, sessions may be passivated.
A session is passivated if it meets the following conditions:
  • The session has not been in use for longer than a configurable maximum idle time.
  • The number of active sessions exceeds a configurable maximum and the session has not been in use for longer than a configurable minimum idle time.
Sessions are always passivated using a Least Recently Used (LRU) algorithm.

8.2.2. Configure HttpSession Passivation in Your Application

Overview
HttpSession passivation is configured in your application's WEB_INF/jboss-web.xml or META_INF/jboss-web.xml file.

Example 8.3. Example jboss-web.xml File

<!DOCTYPE jboss-web PUBLIC
    "-//JBoss//DTD Web Application 5.0//EN"
    "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">

<jboss-web version="6.0"
           xmlns="http://www.jboss.com/xml/ns/javaee"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-web_6_0.xsd">

   <max-active-sessions>20</max-active-sessions>
   <passivation-config>
      <use-session-passivation>true</use-session-passivation>
      <passivation-min-idle-time>60</passivation-min-idle-time>
      <passivation-max-idle-time>600</passivation-max-idle-time>
   </passivation-config>


</jboss-web>
	  

Passivation Configuration Elements

<max-active-sessions>
The maximum number of active sessions allowed. If the number of sessions managed by the session manager exceeds this value and passivation is enabled, the excess will be passivated based on the configured <passivation-min-idle-time>. Then, if the number of active sessions still exceeds this limit, attempts to create new sessions will fail. The default value of -1 sets no limit on the maximum number of active sessions.
<passivation-config>
This element holds the rest of the passivation configuration parameters, as child elements.

<passivation-config> Child Elements

<use-session-passivation>
Whether or not to use session passivation. The default value is false.
<passivation-min-idle-time>
The minimum time, in seconds, that a session must be inactive before the container will consider passivating it in order to reduce the active session count to conform to value defined by max-active-sessions. The default value of -1 disables passivating sessions before <passivation-max-idle-time> has elapsed. Neither a value of -1 nor a high value are recommended if <max-active-sessions> is set.
<passivation-max-idle-time>
The maximum time, in seconds, that a session can be inactive before the container attempts to passivate it to save memory. Passivation of such sessions takes place regardless of whether the active session count exceeds <max-active-sessions>. This value should be less than the <session-timeout> setting in the web.xml. The default value of -1 disables passivation based on maximum inactivity.

REPL and DIST Replication Modes

The total number of sessions in memory includes sessions replicated from other cluster nodes that are not being accessed on this node. Take this into account when setting <max-active-sessions>. The number of sessions replicated from other nodes also depends on whether REPL or DIST cache mode is enabled. In REPL cache mode, each session is replicated to each node. In DIST cache mode, each session is replicated only to the number of nodes specified by the owner parameter. Refer to Section 8.1.2, “About the Web Session Cache” and Section 8.1.3, “Configure the Web Session Cache” for information on configuring session cache modes.
For example, consider an eight node cluster, where each node handles requests from 100 users. With REPL cache mode, each node would store 800 sessions in memory. With DIST cache mode enabled, and the default owners setting of 2, each node stores 200 sessions in memory.

8.3. Cookie Domain

8.3.1. About the Cookie Domain

The cookie domain refers to the set of hosts able to read a cookie from the client browser which is accessing your application. It is a configuration mechanism to minimize the risk of third parties accessing information your application stores in browser cookies.
The default value for the cookie domain is /. This means that only the issuing host can read the contents of a cookie. Setting a specific cookie domain makes the contents of the cookie available to a wider range of hosts. To set the cookie domain, refer to Section 8.3.2, “Configure the Cookie Domain”.

8.3.2. Configure the Cookie Domain

To enable your SSO valve to share a SSO context, configure the cookie domain in the valve configuration. The following configuration would allow applications on http://app1.xyz.com and http://app2.xyz.com to share an SSO context, even if these applications run on different servers in a cluster or the virtual host with which they are associated has multiple aliases.

Example 8.4. Example Cookie Domain Configuration

<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"
                 cookieDomain="xyz.com" />
	

8.4. Implement an HA Singleton

Summary
In JBoss EAP 5, HA singleton archives were deployed in the deploy-hasingleton/ directory separate from other deployments. This was done to prevent automatic deployment and to ensure the HASingletonDeployer service controlled the deployment and deployed the archive only on the master node in the cluster. There was no hot deployment feature, so redeployment required a server restart. Also, if the master node failed requiring another node to take over as master, the singleton service had to go through the entire deployment process in order to provide the service.
In JBoss EAP 6 this has changed. Using a SingletonService, the target service is installed on every node in the cluster but is only started on one node at any given time. This approach simplifies the deployment requirements and minimizes the time required to relocate the singleton master service between nodes.

Procedure 8.3. Implement an HA Singleton Service

  1. Write the HA singleton service application.

    The following is a simple example of a Service that is wrapped with the SingletonService decorater to be deployed as a singleton service.
    1. Create a singleton service.

      The following listing is an example of a singleton service:
      package com.mycompany.hasingleton.service.ejb;
      
      import java.util.concurrent.atomic.AtomicBoolean;
      import java.util.logging.Logger;
      
      import org.jboss.as.server.ServerEnvironment;
      import org.jboss.msc.inject.Injector;
      import org.jboss.msc.service.Service;
      import org.jboss.msc.service.ServiceName;
      import org.jboss.msc.service.StartContext;
      import org.jboss.msc.service.StartException;
      import org.jboss.msc.service.StopContext;
      import org.jboss.msc.value.InjectedValue;
      
      /**
       * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
       */
      public class EnvironmentService implements Service<String> {
          private static final Logger LOGGER = Logger.getLogger(EnvironmentService.class.getCanonicalName());
          public static final ServiceName SINGLETON_SERVICE_NAME = ServiceName.JBOSS.append("quickstart", "ha", "singleton");
          /**
           * A flag whether the service is started.
           */
          private final AtomicBoolean started = new AtomicBoolean(false);
      
          private String nodeName;
      
          private final InjectedValue<ServerEnvironment> env = new InjectedValue<ServerEnvironment>();
      
          public Injector<ServerEnvironment> getEnvInjector() {
              return this.env;
          }
      
          /**
           * @return the name of the server node
           */
          public String getValue() throws IllegalStateException, IllegalArgumentException {
              if (!started.get()) {
                  throw new IllegalStateException("The service '" + this.getClass().getName() + "' is not ready!");
              }
              return this.nodeName;
          }
      
          public void start(StartContext arg0) throws StartException {
              if (!started.compareAndSet(false, true)) {
                  throw new StartException("The service is still started!");
              }
              LOGGER.info("Start service '" + this.getClass().getName() + "'");
              this.nodeName = this.env.getValue().getNodeName();
          }
      
          public void stop(StopContext arg0) {
              if (!started.compareAndSet(true, false)) {
                  LOGGER.warning("The service '" + this.getClass().getName() + "' is not active!");
              } else {
                  LOGGER.info("Stop service '" + this.getClass().getName() + "'");
              }
          }
      }
      
      
      
    2. Create a singleton EJB to start the service as a SingletonService at server start.

      The following listing is an example of a singleton EJB that startes a SingletonService on server start:
      package com.mycompany.hasingleton.service.ejb;
      
      import java.util.Collection;
      import java.util.EnumSet;
      
      import javax.annotation.PostConstruct;
      import javax.annotation.PreDestroy;
      import javax.ejb.Singleton;
      import javax.ejb.Startup;
      
      import org.jboss.as.clustering.singleton.SingletonService;
      import org.jboss.as.server.CurrentServiceContainer;
      import org.jboss.as.server.ServerEnvironment;
      import org.jboss.as.server.ServerEnvironmentService;
      import org.jboss.msc.service.AbstractServiceListener;
      import org.jboss.msc.service.ServiceController;
      import org.jboss.msc.service.ServiceController.Transition;
      import org.jboss.msc.service.ServiceListener;
      import org.slf4j.Logger;
      import org.slf4j.LoggerFactory;
      
      
      /**
       * A Singleton EJB to create the SingletonService during startup.
       * 
       * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
       */
      @Singleton
      @Startup
      public class StartupSingleton {
        private static final Logger LOGGER = LoggerFactory.getLogger(StartupSingleton.class);
      
        /**
         * Create the Service and wait until it is started.<br/>
         * Will log a message if the service will not start in 10sec. 
         */
        @PostConstruct
        protected void startup() {
          LOGGER.info("StartupSingleton will be initialized!");
      
          EnvironmentService service = new EnvironmentService();
          SingletonService<String> singleton = new SingletonService<String>(service, EnvironmentService.SINGLETON_SERVICE_NAME);
          // if there is a node where the Singleton should deployed the election policy might set,
          // otherwise the JGroups coordinator will start it
          //singleton.setElectionPolicy(new PreferredSingletonElectionPolicy(new NamePreference("node2/cluster"), new SimpleSingletonElectionPolicy()));
          ServiceController<String> controller = singleton.build(CurrentServiceContainer.getServiceContainer())
              .addDependency(ServerEnvironmentService.SERVICE_NAME, ServerEnvironment.class, service.getEnvInjector())
              .install();
      
          controller.setMode(ServiceController.Mode.ACTIVE);
          try {
            wait(controller, EnumSet.of(ServiceController.State.DOWN, ServiceController.State.STARTING), ServiceController.State.UP);
            LOGGER.info("StartupSingleton has started the Service");
          } catch (IllegalStateException e) {
            LOGGER.warn("Singleton Service {} not started, are you sure to start in a cluster (HA) environment?",EnvironmentService.SINGLETON_SERVICE_NAME);
          }
        }
      
        /**
         * Remove the service during undeploy or shutdown
         */
        @PreDestroy
        protected void destroy() {
          LOGGER.info("StartupSingleton will be removed!");
          ServiceController<?> controller = CurrentServiceContainer.getServiceContainer().getRequiredService(EnvironmentService.SINGLETON_SERVICE_NAME);
          controller.setMode(ServiceController.Mode.REMOVE);
          try {
            wait(controller, EnumSet.of(ServiceController.State.UP, ServiceController.State.STOPPING, ServiceController.State.DOWN), ServiceController.State.REMOVED);
          } catch (IllegalStateException e) {
            LOGGER.warn("Singleton Service {} has not be stopped correctly!",EnvironmentService.SINGLETON_SERVICE_NAME);
          }
        }
      
        private static <T> void wait(ServiceController<T> controller, Collection<ServiceController.State> expectedStates, ServiceController.State targetState) {
          if (controller.getState() != targetState) {
            ServiceListener<T> listener = new NotifyingServiceListener<T>();
            controller.addListener(listener);
            try {
              synchronized (controller) {
                int maxRetry = 2;
                while (expectedStates.contains(controller.getState()) && maxRetry > 0) {
                  LOGGER.info("Service controller state is {}, waiting for transition to {}", new Object[] {controller.getState(), targetState});
                  controller.wait(5000);
                  maxRetry--;
                }
              }
            } catch (InterruptedException e) {
              LOGGER.warn("Wait on startup is interrupted!");
              Thread.currentThread().interrupt();
            }
            controller.removeListener(listener);
            ServiceController.State state = controller.getState();
            LOGGER.info("Service controller state is now {}",state);
            if (state != targetState) {
              throw new IllegalStateException(String.format("Failed to wait for state to transition to %s.  Current state is %s", targetState, state), controller.getStartException());
            }
          }
        }
      
        private static class NotifyingServiceListener<T> extends AbstractServiceListener<T> {
          @Override
          public void transition(ServiceController<? extends T> controller, Transition transition) {
            synchronized (controller) {
              controller.notify();
            }
          }
        }
      }
      
      
      
    3. Create a Stateless Session Bean to access the service from a client.

      The following is an example of a stateless session bean that accesses the service from a client:
      package com.mycompany.hasingleton.service.ejb;
      
      import javax.ejb.Stateless;
      
      import org.jboss.as.server.CurrentServiceContainer;
      import org.jboss.msc.service.ServiceController;
      import org.slf4j.Logger;
      import org.slf4j.LoggerFactory;
      
      /**
       * A simple SLSB to access the internal SingletonService.
       * 
       * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
       */
      @Stateless
      public class ServiceAccessBean implements ServiceAccess {
          private static final Logger LOGGER = LoggerFactory.getLogger(ServiceAccessBean.class);
      
          public String getNodeNameOfService() {
              LOGGER.info("getNodeNameOfService() is called()");
              ServiceController<?> service = CurrentServiceContainer.getServiceContainer().getService(
                      EnvironmentService.SINGLETON_SERVICE_NAME);
              LOGGER.debug("SERVICE {}", service);
              if (service != null) {
                  return (String) service.getValue();
              } else {
                  throw new IllegalStateException("Service '" + EnvironmentService.SINGLETON_SERVICE_NAME + "' not found!");
              }
          }
      }
      
      
      
    4. Create the business logic interface for the SingletonService.

      The following is an example of a business logic interface for the SingletonService:
      package com.mycompany.hasingleton.service.ejb;
      
      import javax.ejb.Remote;
      
      /**
       * Business interface to access the SingletonService via this EJB
       * 
       * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
       */
      @Remote
      public interface ServiceAccess {
          public abstract String getNodeNameOfService();
      } 
      
      
      
      
  2. Start each JBoss EAP 6 instance with clustering enabled.

    The method for enabling clustering depends on whether the servers are standalone or running in a managed domain.
    1. Enable clustering for servers running in a managed domain.

      You can enable clustering using the Management CLI or you can manually edit the configuration file.
      • Enable clustering using the Management CLI.

        1. Start your domain controller.

        2. Open a command prompt for your operating system.

        3. Connect to the Management CLI passing the domain controller IP address or DNS name.

          In this example, assume the IP address of the domain controller is 192.168.0.14.
          • For Linux, enter the following at the command line:
            $ EAP_HOME/bin/jboss-cli.sh --connect --controller=192.168.0.14
            
          • For Windows, enter the following at a command line:
            C:\>EAP_HOME\bin\jboss-cli.bat --connect --controller=192.168.0.14
            
          You should see the following response:
          Connected to domain controller at 192.168.0.14
        4. Add the main-server server group.

          [domain@192.168.0.14:9999 /] /server-group=main-server-group:add(profile="ha",socket-binding-group="ha-sockets") 
          {
              "outcome" => "success",
              "result" => undefined,
              "server-groups" => undefined
          }
          
        5. Create a server named server-one and add it to the main-server server group.

          [domain@192.168.0.14:9999 /]  /host=station14Host2/server-config=server-one:add(group=main-server-group,auto-start=false)
          {
              "outcome" => "success",
              "result" => undefined
          }
          
        6. Configure the JVM for the main-server server group.

          [domain@192.168.0.14:9999 /] /server-group=main-server-group/jvm=default:add(heap-size=64m,max-heap-size=512m)
          {
              "outcome" => "success",
              "result" => undefined,
              "server-groups" => undefined
          }
          
        7. Create a server named server-two, put it in a separate server group, and set its port offset to 100.

          [domain@192.168.0.14:9999 /]  /host=station14Host2/server-config=server-two:add(group=distinct2,socket-binding-port-offset=100)
          {
              "outcome" => "success",
              "result" => undefined
          }
          
      • Enable clustering by manually editing the server configuration files.

        1. Stop the JBoss EAP 6 server.

          Important

          You must stop the server before editing the server configuration file for your change to be persisted on server restart.
        2. Open the domain.xml configuration file for editing

          Designate a server group to use the ha profile and ha-sockets socket binding group as follows:
          <server-groups>
            <server-group name="main-server-group" profile="ha">
              <jvm name="default">
                <heap size="64m" max-size="512m"/>
              </jvm>
              <socket-binding-group ref="ha-sockets"/>
            </server-group>
          </server-groups>
          
          
          
        3. Open the host.xml configuration file for editing

          Modify the file as follows:
          <servers>
            <server name="server-one" group="main-server-group" auto-start="false"/>
            <server name="server-two" group="distinct2">
              <socket-bindings port-offset="100"/>
            </server>
          <servers>
          
          
          
        4. Start the server.

          • For Linux, type: EAP_HOME/bin/domain.sh
          • For Microsoft Windows, type: EAP_HOME\bin\domain.bat
    2. Enable clustering for standalone servers

      To enable clustering for standalone servers, start the server using the node name and the standalone-ha.xml configuration file as follows:
      • For Linux, type: EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME
      • For Microsoft Windows, type: EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME

    Note

    To avoid port conflicts when running multiple servers on one machine, configure the standalone-ha.xml file for each server instance to bind on a separate interface. Alternatively, you can start subsequent server instances with a port offset using an argument like the following on the command line: -Djboss.socket.binding.port-offset=100.
  3. Deploy the application to the servers

    If you use Maven to deploy your application, use the following Maven command to deploy to the server running on the default ports:
    mvn clean install jboss-as:deploy
    To deploy to additional servers, pass the server name and port number on the command line:
    mvn clean package jboss-as:deploy -Ddeploy.hostname=localhost -Ddeploy.port=10099

Chapter 9. CDI

9.1. Overview of CDI

9.1.2. About Contexts and Dependency Injection (CDI)

Contexts and Dependency Injection (CDI) is a specification designed to enable EJB 3.0 components "to be used as Java Server Faces (JSF) managed beans, unifying the two component models and enabling a considerable simplification to the programming model for web-based applications in Java." The preceding quote is taken from the JSR-299 specification, which can be found at http://www.jcp.org/en/jsr/detail?id=299.
JBoss EAP 6 includes Weld, which is the reference implementation of JSR-299. For more information, about type-safe dependency injection, see Section 9.1.4, “About Type-safe Dependency Injection”.

9.1.3. Benefits of CDI

  • CDI simplifies and shrinks your code base by replacing big chunks of code with annotations.
  • CDI is flexible, allowing you to disable and enable injections and events, use alternative beans, and inject non-CDI objects easily.
  • It is easy to use your old code with CDI. You only need to include a beans.xml in your META-INF/ or WEB-INF/ directory. The file can be empty.
  • CDI simplifies packaging and deployments and reduces the amount of XML you need to add to your deployments.
  • CDI provides lifecycle management via contexts. You can tie injections to requests, sessions, conversations, or custom contexts.
  • CDI provides type-safe dependency injection, which is safer and easier to debug than string-based injection.
  • CDI decouples interceptors from beans.
  • CDI provides complex event notification.

9.1.4. About Type-safe Dependency Injection

Before JSR-299 and CDI, the only way to inject dependencies in Java was to use strings. This was prone to errors. CDI introduces the ability to inject dependencies in a type-safe way.

9.1.5. Relationship Between Weld, Seam 2, and JavaServer Faces

The goal of Seam 2 was to unify Enterprise Java Beans (EJBs) and JavaServer Faces (JSF) managed beans.
JavaServer Faces (JSF) implements JSR-314. It is an API for building server-side user interfaces. JBoss Web Framework Kit includes RichFaces, which is an implementation of JavaServer Faces and AJAX.
Weld is the reference implementation of Contexts and Dependency Injection (CDI), which is defined in JSR-299. Weld was inspired by Seam 2 and other dependency injection frameworks. Weld is included in JBoss EAP 6.

9.2. Use CDI

9.2.1. First Steps

9.2.1.1. Enable CDI

Summary
Contexts and Dependency Injection (CDI) is one of the core technologies in JBoss EAP 6, and is enabled by default. If for some reason it is disabled and you need to enable it, follow this procedure.

Procedure 9.1. Enable CDI in JBoss EAP 6

  1. Check to see if the CDI subsystem details are commented out of the configuration file.

    A subsystem can be disabled by commenting out the relevant section of the domain.xml or standalone.xml configuration files, or by removing the relevant section altogether.
    To find the CDI subsystem in EAP_HOME/domain/configuration/domain.xml or EAP_HOME/standalone/configuration/standalone.xml, search them for the following string. If it exists, it is located inside the <extensions> section.
    <extension module="org.jboss.as.weld"/>
    The following line must also be present in the profile you are using. Profiles are in individual <profile> elements within the <profiles> section.
    <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
  2. Before editing any files, stop JBoss EAP 6.

    JBoss EAP 6 modifies the configuration files during the time it is running, so you must stop the server before you edit the configuration files directly.
  3. Edit the configuration file to restore the CDI subsystem.

    If the CDI subsystem was commented out, remove the comments.
    If it was removed entirely, restore it by adding this line to the file in a new line directly above the </extensions> tag:
    <extension module="org.jboss.as.weld"/>
  4. You also need to add the following line to the relevant profile in the <profiles> section.
    <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
  5. Restart JBoss EAP 6.

    Start JBoss EAP 6 with your updated configuration.
Result
JBoss EAP 6 starts with the CDI subsystem enabled.

9.2.2. Use CDI to Develop an Application

9.2.2.2. Use CDI with Existing Code

Almost every concrete Java class that has a constructor with no parameters, or a constructor designated with the annotation @Inject, is a bean. The only thing you need to do before you can start injecting beans is create a file called beans.xml in the META-INF/ or WEB-INF/ directory of your archive. The file can be empty.

Procedure 9.2. Use legacy beans in CDI applications

  1. Package your beans into an archive.

    Package your beans into a JAR or WAR archive.
  2. Include a beans.xml file in your archive.

    Place a beans.xml file into your JAR archive's META-INF/ or your WAR archive's WEB-INF/ directory. The file can be empty.
Result:
You can use these beans with CDI. The container can create and destroy instances of your beans and associate them with a designated context, inject them into other beans, use them in EL expressions, specialize them with qualifier annotations, and add interceptors and decorators to them, without any modifications to your existing code. In some circumstances, you may need to add some annotations.

9.2.2.3. Exclude Beans From the Scanning Process

Summary
One of the features of Weld, the JBoss EAP 6 implementation of CDI, is the ability to exclude classes in your archive from scanning, having container lifecycle events fired, and being deployed as beans. This is not part of the JSR-299 specification.

Example 9.1. Exclude packages from your bean

The following example has several <weld:exclude> tags.
  1. The first one excludes all Swing classes.
  2. The second excludes Google Web Toolkit classes if Google Web Toolkit is not installed.
  3. The third excludes classes which end in the string Blether (using a regular expression), if the system property verbosity is set to low.
  4. The fourth excludes Java Server Faces (JSF) classes if Wicket classes are present and the viewlayer system property is not set.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xmlns:weld="http://jboss.org/schema/weld/beans" 
       xsi:schemaLocation="
          http://java.sun.com/xml/ns/javaee http://docs.jboss.org/cdi/beans_1_0.xsd
          http://jboss.org/schema/weld/beans http://jboss.org/schema/weld/beans_1_1.xsd">
    
    <weld:scan>
      
        <!-- Don't deploy the classes for the swing app! -->
        <weld:exclude name="com.acme.swing.**" />
      
        <!-- Don't include GWT support if GWT is not installed -->
        <weld:exclude name="com.acme.gwt.**">
            <weld:if-class-available name="!com.google.GWT"/>
        </weld:exclude>
        
        <!--
            Exclude classes which end in Blether if the system property verbosity is set to low
            i.e.
              java ... -Dverbosity=low            
        -->        
        <weld:exclude pattern="^(.*)Blether$">
            <weld:if-system-property name="verbosity" value="low"/>
        </weld:exclude>
        
       <!--
             Don't include JSF support if Wicket classes are present, and the viewlayer system
             property is not set
        -->
        <weld:exclude name="com.acme.jsf.**">
            <weld:if-class-available name="org.apache.wicket.Wicket"/>
            <weld:if-system-property name="!viewlayer"/>
        </weld:exclude>
    </weld:scan>
</beans>


The formal specification of Weld-specific configuration options can be found at http://jboss.org/schema/weld/beans_1_1.xsd.

9.2.2.4. Use an Injection to Extend an Implementation

Summary
You can use an injection to add or change a feature of your existing code. This example shows you how to add a translation ability to an existing class. The translation is a hypothetical feature and the way it is implemented in the example is pseudo-code, and only provided for illustration.
The example assumes you already have a Welcome class, which has a method buildPhrase. The buildPhrase method takes as an argument the name of a city, and outputs a phrase like "Welcome to Boston." Your goal is to create a version of the Welcome class which can translate the greeting into a different language.

Example 9.2. Inject a Translator Bean Into the Welcome Class

The following pseudo-code injects a hypothetical Translator object into the Welcome class. The Translator object may be an EJB stateless bean or another type of bean, which can translate sentences from one language to another. In this instance, the Translator is used to translate the entire greeting, without actually modifying the original Welcome class at all. The Translator is injected before the buildPhrase method is implemented.
The code sample below is an example Translating Welcome class.
public class TranslatingWelcome extends Welcome {

    @Inject Translator translator;

    public String buildPhrase(String city) {
        return translator.translate("Welcome to " + city + "!");
    }
    ...
}

9.2.3. Ambiguous or Unsatisfied Dependencies

9.2.3.1. About Ambiguous or Unsatisfied Dependencies

Ambiguous dependencies exist when the container is unable to resolve an injection to exactly one bean.
Unsatisfied dependencies exist when the container is unable to resolve an injection to any bean at all.
The container takes the following steps to try to resolve dependencies:
  1. It resolves the qualifier annotations on all beans that implement the bean type of an injection point.
  2. It filters out disabled beans. Disabled beans are @Alternative beans which are not explicitly enabled.
In the event of an ambiguous or unsatisfied dependency, the container aborts deployment and throws an exception.

9.2.3.2. About Qualifiers

A qualifier is an annotation which ties a bean to a bean type. It allows you to specify exactly which bean you mean to inject. Qualifiers have a retention and a target, which are defined as in the example below.

Example 9.3. Define the @Synchronous and @Asynchronous Qualifiers

@Qualifier
@Retention(RUNTIME)
@Target({TYPE, METHOD, FIELD, PARAMETER})
public @interface Synchronous {}
@Qualifier
@Retention(RUNTIME)
@Target({TYPE, METHOD, FIELD, PARAMETER})
public @interface Asynchronous {}

Example 9.4. Use the @Synchronous and @Asynchronous Qualifiers

@Synchronous
public class SynchronousPaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }

}
@Asynchronous
public class AsynchronousPaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }
}

9.2.3.3. Use a Qualifier to Resolve an Ambiguous Injection

Summary
This task shows an ambiguous injection and removes the ambiguity with a qualifier. Read more about ambiguous injections at Section 9.2.3.1, “About Ambiguous or Unsatisfied Dependencies”.

Example 9.5. Ambiguous injection

You have two implementations of Welcome, one which translates and one which does not. In that situation, the injection below is ambiguous and needs to be specified to use the translating Welcome.
public class Greeter {
  private Welcome welcome;

  @Inject
  void init(Welcome welcome) {
    this.welcome = welcome;
  }
  ...
}

Procedure 9.3. Resolve an Ambiguous Injection with a Qualifier

  1. Create a qualifier annotation called @Translating.

    @Qualifier
    @Retention(RUNTIME)
    @Target({TYPE,METHOD,FIELD,PARAMETERS})
    public @interface Translating{}
    
  2. Annotate your translating Welcome with the @Translating annotation.

    @Translating
    public class TranslatingWelcome extends Welcome {
        @Inject Translator translator;
        public String buildPhrase(String city) {
            return translator.translate("Welcome to " + city + "!");
        }
        ...
    }
    
  3. Request the translating Welcome in your injection.

    You must request a qualified implementation explicitly, similar to the factory method pattern. The ambiguity is resolved at the injection point.
    public class Greeter {
      private Welcome welcome;
      @Inject
      void init(@Translating Welcome welcome) {
        this.welcome = welcome;
      } 
      public void welcomeVisitors() {
        System.out.println(welcome.buildPhrase("San Francisco"));
      }
    }
    
Result
The TranslatingWelcome is used, and there is no ambiguity.

9.2.4. Managed Beans

9.2.4.1. About Managed Beans

Managed beans, also called MBeans, are JavaBeans which are created using dependency injection. Each MBean represents a resource which runs in the Java Virtual Machine (JVM).
Java EE 6 expands upon this definition. A bean is implemented by a Java class, which is referred to as its bean class. A managed bean is a top-level Java class.
For more information about managed beans, refer to the JSR-255 specification at http://jcp.org/en/jsr/detail?id=255. For more information about CDI, refer to Section 9.1.2, “About Contexts and Dependency Injection (CDI)”.

9.2.4.2. Types of Classes That are Beans

A managed bean is a Java class. The basic lifecycle and semantics of a managed bean are defined by the Managed Beans specification. You can explicitly declare a managed bean by annotating the bean class @ManagedBean, but in CDI you do not need to. According to the specification, the CDI container treats any class that satisfies the following conditions as a managed bean:
  • It is not a non-static inner class.
  • It is a concrete class, or is annotated @Decorator.
  • It is not annotated with an EJB component-defining annotation or declared as an EJB bean class in ejb-jar.xml.
  • It does not implement interface javax.enterprise.inject.spi.Extension.
  • It has either a constructor with no parameters, or a constructor annotated with @Inject.
The unrestricted set of bean types for a managed bean contains the bean class, every superclass and all interfaces it implements directly or indirectly.
If a managed bean has a public field, it must have the default scope @Dependent.

9.2.4.3. Use CDI to Inject an Object Into a Bean

When your deployment archive includes a META-INF/beans.xml or WEB-INF/beans.xml file, each object in your deployment can be injected using CDI.
This procedure introduces the main ways to inject objects into other objects.
  1. Inject an object into any part of a bean with the @Inject annotation.

    To obtain an instance of a class, within your bean, annotate the field with @Inject.

    Example 9.6. Injecting a TextTranslator instance into a TranslateController

    public class TranslateController {
    
       @Inject TextTranslator textTranslator;
       ...
    

  2. Use your injected object's methods

    You can use your injected object's methods directly. Assume that TextTranslator has a method translate.

    Example 9.7. Use your injected object's methods

    // in TranslateController class
    
    public void translate() {
    
       translation = textTranslator.translate(inputText); 
    
    }
    

  3. Use injection in the constructor of a bean

    You can inject objects into the constructor of a bean, as an alternative to using a factory or service locator to create them.

    Example 9.8. Using injection in the constructor of a bean

    public class TextTranslator {
    
       private SentenceParser sentenceParser;
    
       private Translator sentenceTranslator;
    
        
    
       @Inject
    
       TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator) {
    
          this.sentenceParser = sentenceParser;
    
          this.sentenceTranslator = sentenceTranslator;
    
       }
    
       // Methods of the TextTranslator class
       ...
    }
    

  4. Use the Instance(<T>) interface to get instances programmatically.

    The Instance interface can return an instance of TextTranslator when parameterized with the bean type.

    Example 9.9. Obtaining an instance programmatically

    @Inject Instance<TextTranslator> textTranslatorInstance;
    
    ...
    
    public void translate() {
    
       textTranslatorInstance.get().translate(inputText);
    
    }
    

Result:
When you inject an object into a bean all of the object's methods and properties are available to your bean. If you inject into your bean's constructor, instances of the injected objects are created when your bean's constructor is called, unless the injection refers to an instance which already exists. For instance, a new instance would not be created if you inject a session-scoped bean during the lifetime of the session.

9.2.5. Contexts, Scopes, and Dependencies

9.2.5.1. Contexts and Scopes

A context, in terms of CDI, is a storage area which holds instances of beans associated with a specific scope.
A scope is the link between a bean and a context. A scope/context combination may have a specific lifecycle. Several pre-defined scopes exist, and you can create your own scopes. Examples of pre-defined scopes are @RequestScoped, @SessionScoped, and @ConversationScope.

9.2.5.2. Available Contexts

Table 9.1. Available contexts

Context Description
@Dependent The bean is bound to the lifecycle of the bean holding the reference.
@ApplicationScoped Bound to the lifecycle of the application.
@RequestScoped Bound to the lifecycle of the request.
@SessionScoped Bound to the lifecycle of the session.
@ConversationScoped Bound to the lifecycle of the conversation. The conversation scope is between the lengths of the request and the session, and is controlled by the application.
Custom scopes If the above contexts do not meet your needs, you can define custom scopes.

9.2.6. Bean Lifecycle

9.2.6.1. Manage the Lifecycle of a Bean

Summary
This task shows you how to save a bean for the life of a request. Several other scopes exist, and you can define your own scopes.
The default scope for an injected bean is @Dependent. This means that the bean's lifecycle is dependent upon the lifecycle of the bean which holds the reference. For more information, see Section 9.2.5.1, “Contexts and Scopes”.

Procedure 9.4. Manage Bean Lifecycles

  1. Annotate the bean with the scope corresponding to your desired scope.

    @RequestScoped
    @Named("greeter")
    public class GreeterBean {
      private Welcome welcome;
      private String city; // getter & setter not shown
      @Inject   void init(Welcome welcome) {
        this.welcome = welcome;
      }
      public void welcomeVisitors() {
        System.out.println(welcome.buildPhrase(city));
      }
    }
    
  2. When your bean is used in the JSF view, it holds state.

    <h:form>
      <h:inputText value="#{greeter.city}"/>
      <h:commandButton value="Welcome visitors" action="#{greeter.welcomeVisitors}"/>
    </h:form>
    
Result:
Your bean is saved in the context relating to the scope that you specify, and lasts as long as the scope applies.

9.2.6.2. Use a Producer Method

Summary
This task shows how to use producer methods to produce a variety of different objects which are not beans for injection.

Example 9.10. Use a producer method instead of an alternative, to allow polymorphism after deployment

The @Preferred annotation in the example is a qualifier annotation. For more information about qualifiers, refer to: Section 9.2.3.2, “About Qualifiers”.
@SessionScoped
public class Preferences implements Serializable {
   private PaymentStrategyType paymentStrategy;
   ...
   @Produces @Preferred 
   public PaymentStrategy getPaymentStrategy() {
       switch (paymentStrategy) {
           case CREDIT_CARD: return new CreditCardPaymentStrategy();
           case CHECK: return new CheckPaymentStrategy();
           default: return null;
       } 
   }
}
The following injection point has the same type and qualifier annotations as the producer method, so it resolves to the producer method using the usual CDI injection rules. The producer method is called by the container to obtain an instance to service this injection point.
@Inject @Preferred PaymentStrategy paymentStrategy;

Example 9.11. Assign a scope to a producer method

The default scope of a producer method is @Dependent. If you assign a scope to a bean, it is bound to the appropriate context. The producer method in this example is only called once per session.
@Produces @Preferred @SessionScoped
public PaymentStrategy getPaymentStrategy() {
   ...
}

Example 9.12. Use an injection inside a producer method

Objects instantiated directly by an application cannot take advantage of dependency injection and do not have interceptors. However, you can use dependency injection into the producer method to obtain bean instances.
@Produces @Preferred @SessionScoped
public PaymentStrategy getPaymentStrategy(CreditCardPaymentStrategy ccps,
                                          CheckPaymentStrategy cps ) {
   switch (paymentStrategy) {
      case CREDIT_CARD: return ccps;
      case CHEQUE: return cps;
      default: return null;
   } 
}

If you inject a request-scoped bean into a session-scoped producer, the producer method promotes the current request-scoped instance into session scope. This is almost certainly not the desired behavior, so use caution when you use a producer method in this way.

Note

The scope of the producer method is not inherited from the bean that declares the producer method.
Result
Producer methods allow you to inject non-bean objects and change your code dynamically.

9.2.7. Named Beans and Alternative Beans

9.2.7.1. About Named Beans

A bean is named by using the @Named annotation. Naming a bean allows you to use it directly in Java Server Faces (JSF).
The @Named annotation takes an optional parameter, which is the bean name. If this parameter is omitted, the lower-cased bean name is used as the name.

9.2.7.2. Use Named Beans

  1. Use the @Named annotation to assign a name to a bean.

    @Named("greeter")
    public class GreeterBean {
      private Welcome welcome;
    
      @Inject
      void init (Welcome welcome) {
        this.welcome = welcome;
      }
    
      public void welcomeVisitors() {
        System.out.println(welcome.buildPhrase("San Francisco"));
      }
    }
    
    The bean name itself is optional. If it is omitted, the bean is named after the class name, with the first letter decapitalized. In the example above, the default name would be greeterBean.
  2. Use the named bean in a JSF view.

    <h:form>
      <h:commandButton value="Welcome visitors" action="#{greeter.welcomeVisitors}"/>
    </h:form>
    
Result:
Your named bean is assigned as an action to the control in your JSF view, with a minimum of coding.

9.2.7.3. About Alternative Beans

Alternatives are beans whose implementation is specific to a particular client module or deployment scenario.

Example 9.13. Defining Alternatives

This alternative defines a mock implementation of both @Synchronous PaymentProcessor and @Asynchronous PaymentProcessor, all in one:
@Alternative @Synchronous @Asynchronous

public class MockPaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }

}

By default, @Alternative beans are disabled. They are enabled for a specific bean archive by editing its beans.xml file.

9.2.7.4. Override an Injection with an Alternative

Summary
Alternative beans let you override existing beans. They can be thought of as a way to plug in a class which fills the same role, but functions differently. They are disabled by default. This task shows you how to specify and enable an alternative.

Procedure 9.5. Override an Injection

This task assumes that you already have a TranslatingWelcome class in your project, but you want to override it with a "mock" TranslatingWelcome class. This would be the case for a test deployment, where the true Translator bean cannot be used.
  1. Define the alternative.

    @Alternative
    @Translating 
    public class MockTranslatingWelcome extends Welcome {
      public String buildPhrase(string city) {
        return "Bienvenue à " + city + "!");
      }
    }
    
  2. Substitute the alternative.

    To activate the substitute implementation, add the fully-qualified class name to your META-INF/beans.xml or WEB-INF/beans.xml file.
    <beans>
      <alternatives>
        <class>com.acme.MockTranslatingWelcome</class>
      </alternatives>
    </beans>
    
Result
The alternative implementation is now used instead of the original one.

9.2.8. Stereotypes

9.2.8.1. About Stereotypes

In many systems, use of architectural patterns produces a set of recurring bean roles. A stereotype allows you to identify such a role and declare some common metadata for beans with that role in a central place.
A stereotype encapsulates any combination of:
  • default scope
  • a set of interceptor bindings
A stereotype may also specify either of these two scenarios:
  • all beans with the stereotype have defaulted bean EL names
  • all beans with the stereotype are alternatives
A bean may declare zero, one or multiple stereotypes. Stereotype annotations may be applied to a bean class or producer method or field.
A stereotype is an annotation, annotated @Stereotype, that packages several other annotations.
A class that inherits a scope from a stereotype may override that stereotype and specify a scope directly on the bean.
In addition, if a stereotype has a @Named annotation, any bean it is placed on has a default bean name. The bean may override this name if the @Named annotation is specified directly on the bean. For more information about named beans, see Section 9.2.7.1, “About Named Beans”.

9.2.8.2. Use Stereotypes

Summary
Without stereotypes, annotations can become cluttered. This task shows you how to use stereotypes to reduce the clutter and streamline your code. For more information about what stereotypes are, see Section 9.2.8.1, “About Stereotypes”.

Example 9.14. Annotation clutter

@Secure
@Transactional
@RequestScoped
@Named
public class AccountManager {
  public boolean transfer(Account a, Account b) {
    ...
  }
}

Procedure 9.6. Define and Use Stereotypes

  1. Define the stereotype,

    @Secure
    @Transactional
    @RequestScoped
    @Named
    @Stereotype
    @Retention(RUNTIME)
    @Target(TYPE)
    public @interface BusinessComponent {
     ...
    }
    
  2. Use the stereotype.

    @BusinessComponent
    public class AccountManager {
      public boolean transfer(Account a, Account b) {
        ...
      }
    }
    
Result:
Stereotypes streamline and simplify your code.

9.2.9. Observer Methods

9.2.9.1. About Observer Methods

Observer methods receive notifications when events occur.
CDI provides transactional observer methods, which receive event notifications during the before completion or after completion phase of the transaction in which the event was fired.

9.2.9.2. Fire and Observe Events

Example 9.15. Fire an event

This code shows an event being injected and used in a method.
public class AccountManager {
  @Inject Event<Withdrawal> event;
  
  public boolean transfer(Account a, Account b) {
    ...
    event.fire(new Withdrawal(a));
  }
}

Example 9.16. Fire an event with a qualifier

You can annotate your event injection with a qualifier, to make it more specific. For more information about qualifiers, see Section 9.2.3.2, “About Qualifiers”.
public class AccountManager {
  @Inject @Suspicious Event <Withdrawal> event;
  
  public boolean transfer(Account a, Account b) {
    ...
    event.fire(new Withdrawal(a));
  }
}

Example 9.17. Observe an event

To observe an event, use the @Observes annotation.
public class AccountObserver {
  void checkTran(@Observes Withdrawal w) {
    ...
  }
}

Example 9.18. Observe a qualified event

You can use qualifiers to observe only specific types of events. For more information about qualifiers, see Section 9.2.3.2, “About Qualifiers”.
public class AccountObserver {
  void checkTran(@Observes @Suspicious Withdrawal w) {
    ...
  }
}

9.2.10. Interceptors

9.2.10.1. About Interceptors

Interceptors are defined as part of the Enterprise JavaBeans specification, which can be found at http://jcp.org/aboutJava/communityprocess/final/jsr318/. Interceptors allow you to add functionality to the business methods of a bean without modifying the bean's method directly. The interceptor is executed before any of the business methods of the bean.
CDI enhances this functionality by allowing you to use annotations to bind interceptors to beans.

Interception points

business method interception
A business method interceptor applies to invocations of methods of the bean by clients of the bean.
lifecycle callback interception
A lifecycle callback interceptor applies to invocations of lifecycle callbacks by the container.
timeout method interception
A timeout method interceptor applies to invocations of the EJB timeout methods by the container.

9.2.10.2. Use Interceptors with CDI

Example 9.19. Interceptors without CDI

Without CDI, interceptors have two problems.
  • The bean must specify the interceptor implementation directly.
  • Every bean in the application must specify the full set of interceptors in the correct order. This makes adding or removing interceptors on an application-wide basis time-consuming and error-prone.
@Interceptors({
  SecurityInterceptor.class,
  TransactionInterceptor.class,
  LoggingInterceptor.class
})
@Stateful public class BusinessComponent {
  ...
}


Procedure 9.7. Use interceptors with CDI

  1. Define the interceptor binding type.

    @InterceptorBinding
    @Retention(RUNTIME)
    @Target({TYPE, METHOD})
    public @interface Secure {}
    
  2. Mark the interceptor implementation.

    @Secure
    @Interceptor
    public class SecurityInterceptor {
      @AroundInvoke
      public Object aroundInvoke(InvocationContext ctx) throws Exception {
        // enforce security ...
        return ctx.proceed();
        }
    }
    
  3. Use the interceptor in your business code.

    @Secure
    public class AccountManager {
      public boolean transfer(Account a, Account b) {
        ...
      }
    }
    
  4. Enable the interceptor in your deployment, by adding it to META-INF/beans.xml or WEB-INF/beans.xml.

    <beans>
      <interceptors>
        <class>com.acme.SecurityInterceptor</class>
        <class>com.acme.TransactionInterceptor</class>
      </interceptors>
    </beans>
    
    The interceptors are applied in the order listed.
Result:
CDI simplifies your interceptor code and makes it easier to apply to your business code.

9.2.11. About Decorators

A decorator intercepts invocations from a specific Java interface, and is aware of all the semantics attached to that interface. Decorators are useful for modeling some kinds of business concerns, but do not have the generality of interceptors. They are a bean, or even an abstract class, that implements the type it decorates, and are annotated with @Decorator.

Example 9.20. Example Decorator

@Decorator

public abstract class LargeTransactionDecorator

      implements Account {

   @Inject @Delegate @Any Account account;

   @PersistenceContext EntityManager em;

   public void withdraw(BigDecimal amount) {

      ...

   }
    
   public void deposit(BigDecimal amount);

      ...

   }

}



9.2.12. About Portable Extensions

CDI is intended to be a foundation for frameworks, extensions and integration with other technologies. Therefore, CDI exposes a set of SPIs for the use of developers of portable extensions to CDI. Extensions can provide the following types of functionality:
  • integration with Business Process Management engines
  • integration with third-party frameworks such as Spring, Seam, GWT or Wicket
  • new technology based upon the CDI programming model
According to the JSR-299 specification, a portable extension may integrate with the container in the following ways:
  • Providing its own beans, interceptors and decorators to the container
  • Injecting dependencies into its own objects using the dependency injection service
  • Providing a context implementation for a custom scope
  • Augmenting or overriding the annotation-based metadata with metadata from some other source

9.2.13. Bean Proxies

9.2.13.1. About Bean Proxies

A proxy is a subclass of a bean, which is generated at runtime. It is injected at bean creation time, and dependent scoped beans can be injected from it, because the lifecycles of the dependent beans are tied to proxy. Proxies are used as a substitute for dependency injection, and solve two different problems.

Problems of dependency injection, which are solved by using proxies

  • Performance - Proxies are much faster than dependency injection, so you can use them in beans which need good performance.
  • Thread safety - Proxies forward requests to the correct bean instance, even when multiple threads access a bean at the same time. Dependency injection does not guarantee thread safety.

Types of classes that cannot be proxied

  • Primitive types or array types
  • Classes that are final or have final methods
  • Classes which have a non-private default constructor

9.2.13.2. Use a Proxy in an Injection

Overview
A proxy is used for injection when the lifecycles of the beans are different from each other. The proxy is a subclass of the bean that is created at run-time, and overrides all the non-private methods of the bean class. The proxy forwards the invocation onto the actual bean instance.
In this example, the PaymentProcessor instance is not injected directly into Shop. Instead, a proxy is injected, and when the processPayment() method is called, the proxy looks up the current PaymentProcessor bean instance and calls the processPayment() method on it.

Example 9.21. Proxy Injection

@ConversationScoped
class PaymentProcessor
{
  public void processPayment(int amount)
  {
    System.out.println("I'm taking $" + amount);
  }
}
 
@ApplicationScoped
public class Shop
{
 
  @Inject
  PaymentProcessor paymentProcessor; 
 
  public void buyStuff()
  {
    paymentProcessor.processPayment(100);
  }
}
	

Fore more information about proxies, including which types of classes can be proxied, refer to Section 9.2.13.1, “About Bean Proxies”.

Chapter 10. Java Transaction API (JTA)

10.1. Overview
10.1.1. Overview of Java Transactions API (JTA)
10.2. Transaction Concepts
10.2.1. About Transactions
10.2.2. About ACID Properties for Transactions
10.2.3. About the Transaction Coordinator or Transaction Manager
10.2.4. About Transaction Participants
10.2.5. About Java Transactions API (JTA)
10.2.6. About Java Transaction Service (JTS)
10.2.7. About XA Datasources and XA Transactions
10.2.8. About XA Recovery
10.2.9. About the 2-Phase Commit Protocol
10.2.10. About Transaction Timeouts
10.2.11. About Distributed Transactions
10.2.12. About the ORB Portability API
10.2.13. About Nested Transactions
10.3. Transaction Optimizations
10.3.1. Overview of Transaction Optimizations
10.3.2. About the LRCO Optimization for Single-phase Commit (1PC)
10.3.3. About the Presumed-Abort Optimization
10.3.4. About the Read-Only Optimization
10.4. Transaction Outcomes
10.4.1. About Transaction Outcomes
10.4.2. About Transaction Commit
10.4.3. About Transaction Roll-Back
10.4.4. About Heuristic Outcomes
10.4.5. JBoss Transactions Errors and Exceptions
10.5. Overview of JTA Transactions
10.5.1. About Java Transactions API (JTA)
10.5.2. Lifecycle of a JTA Transaction
10.6. Transaction Subsystem Configuration
10.6.1. Transactions Configuration Overview
10.6.2. Transactional Datasource Configuration
10.6.3. Transaction Logging
10.7. Use JTA Transactions
10.7.1. Transactions JTA Task Overview
10.7.2. Control Transactions
10.7.3. Begin a Transaction
10.7.4. Nest Transactions
10.7.5. Commit a Transaction
10.7.6. Roll Back a Transaction
10.7.7. Handle a Heuristic Outcome in a Transaction
10.7.8. Transaction Timeouts
10.7.9. JTA Transaction Error Handling
10.8. ORB Configuration
10.8.1. About Common Object Request Broker Architecture (CORBA)
10.8.2. Configure the ORB for JTS Transactions
10.9. Transaction References
10.9.1. JBoss Transactions Errors and Exceptions
10.9.2. JTA Clustering Limitations
10.9.3. JTA Transaction Example
10.9.4. API Documentation for JBoss Transactions JTA

10.1. Overview

10.1.1. Overview of Java Transactions API (JTA)

Introduction
These topics provide a foundational understanding of the Java Transactions API (JTA).

10.2. Transaction Concepts

10.2.1. About Transactions

A transaction consists of two or more actions which must either all succeed or all fail. A successful outcome is a commit, and a failed outcome is a roll-back. In a roll-back, each member's state is reverted to its state before the transaction attempted to commit.
The typical standard for a well-designed transaction is that it is Atomic, Consistent, Isolated, and Durable (ACID).

10.2.2. About ACID Properties for Transactions

ACID is an acronym which stands for Atomicity, Consistency, Isolation, and Durability. This terminology is usually used in the context of databases or transactional operations.

ACID Definitions

Atomicity
For a transaction to be atomic, all transaction members must make the same decision. Either they all commit, or they all roll back. If atomicity is broken, what results is termed a heuristic outcome.
Consistency
Consistency means that data written to the database is guaranteed to be valid data, in terms of the database schema. The database or other data source must always be in a consistent state. One example of an inconsistent state would be a field in which half of the data is written before an operation aborts. A consistent state would be if all the data were written, or the write were rolled back when it could not be completed.
Isolation
Isolation means that data being operated on by a transaction must be locked before modification, to prevent processes outside the scope of the transaction from modifying the data.
Durability
Durability means that in the event of an external failure after transaction members have been instructed to commit, all members will be able to continue committing the transaction when the failure is resolved. This failure may be related to hardware, software, network, or any other involved system.

10.2.3. About the Transaction Coordinator or Transaction Manager

The terms Transaction Coordinator and Transaction Manager are mostly interchangeable in terms of transactions with JBoss EAP 6. The term Transaction Coordinator is usually used in the context of distributed transactions.
In JTA transactions, The Transaction Manager runs within JBoss EAP 6 and communicates with transaction participants during the two-phase commit protocol.
The Transaction Manager tells transaction participants whether to commit or roll back their data, depending on the outcome of other transaction participants. In this way, it ensures that transactions adhere to the ACID standard.
In JTS transactions, the Transaction Coordinator manages interactions between transaction managers on different servers.

10.2.4. About Transaction Participants

A transaction participant is any process within a transaction, which has the ability to commit or roll back state. This may be a database or other application. Each participant of a transaction independently decides whether it is able to commit or roll back its state, and only if all participants can commit, does the transaction as a whole succeed. Otherwise, each participant rolls back its state, and the transaction as a whole fails. The Transaction Manager coordinates the commit or rollback operations and determines the outcome of the transaction.

10.2.5. About Java Transactions API (JTA)

Java Transactions API (JTA) is a specification for using transactions in Java Enterprise Edition applications. It is defined in JSR-907.
JTA transactions are not distributed across multiple application servers, and cannot be nested.
JTA transactions are controlled by the EJB container. Annotations are one method for creating and controlling transactions within your code.

10.2.6. About Java Transaction Service (JTS)

Java Transaction Service (JTS) is a mechanism for supporting Java Transaction API (JTA) transactions when participants of the transactions reside in multiple Java Enterprise Edition containers (application servers). Just as in local JTA transactions, each container runs a process called Transaction Manager (TM). The TMs communicate with each other using a process called an Object Request Broker (ORB), using a communication standard called Common Object Request Broker Architecture (CORBA).
From an application standpoint, a JTS transaction behaves in the same ways as a JTA transaction. The difference is that transaction participants and datasources reside in different containers.

Note

The implementation of JTS included in JBoss EAP 6 supports distributed JTA transactions. The difference between distributed JTA transactions and fully-compliant JTS transactions is interoperability with external third-party ORBs. This feature is unsupported with JBoss EAP 6. Supported configurations distribute transactions across multiple JBoss EAP 6 containers only.

10.2.7. About XA Datasources and XA Transactions

An XA datasource is a datasource which can participate in an XA global transaction.
An XA transaction is a transaction which can span multiple resources. It involves a coordinating transaction manager, with one or more databases or other transactional resources, all involved in a single global transaction.

10.2.8. About XA Recovery

The Java Transaction API (JTA) allows distributed transactions across multiple X/Open XA resources. XA stands for Extended Architecture which was developed by the X/Open Group to define a transaction which uses more than one back-end data store. The XA standard describes the interface between a global Transaction Manager (TM) and a local resource manager. XA allows multiple resources, such as application servers, databases, caches, and message queues, to participate in the same transaction, while preserving atomicity of the transaction. Atomicity means that if one of the participants fails to commit its changes, the other participants abort the transaction, and restore their state to the same status as before the transaction occurred.
XA Recovery is the process of ensuring that all resources affected by a transaction are updated or rolled back, even if any of the resources are transaction participants crash or become unavailable. Within the scope of JBoss EAP 6, the Transaction subsystem provides the mechanisms for XA Recovery to any XA resources or subsystems which use them, such as XA datasources, JMS message queues, and JCA resource adapters.
XA Recovery happens without user intervention. In the event of an XA Recovery failure, errors are recorded in the log output. Contact Red Hat Global Support Services if you need assistance.

10.2.9. About the 2-Phase Commit Protocol

The Two-phase commit protocol (2PC) refers to an algorithm to determine the outcome of a transaction.
Phase 1
In the first phase, the transaction participants notify the transaction coordinator whether they are able to commit the transaction or must roll back.
Phase 2
In the second phase, the transaction coordinator makes the decision about whether the overall transaction should commit or roll back. If any one of the participants cannot commit, the transaction must roll back. Otherwise, the transaction can commit. The coordinator directs the transactions about what to do, and they notify the coordinator when they have done it. At that point, the transaction is finished.

10.2.10. About Transaction Timeouts

In order to preserve atomicity and adhere to the ACID standard for transactions, some parts of a transaction can be long-running. Transaction participants need to lock parts of datasources when they commit, and the transaction manager needs to wait to hear back from each transaction participant before it can direct them all whether to commit or roll back. Hardware or network failures can cause resources to be locked indefinitely.
Transaction timeouts can be associated with transactions in order to control their lifecycle. If a timeout threshold passes before the transaction commits or rolls back, the timeout causes the transaction to be rolled back automatically.
You can configure default timeout values for the entire transaction subsystem, or you disable default timeout values, and specify timeouts on a per-transaction basis.

10.2.11. About Distributed Transactions

A distributed transaction, or distributed Java Transaction API (JTA) transaction is a transaction with participants on multiple JBoss EAP 6 servers. Distributed transactions differ from Java Transaction Service (JTS) transactions in that the JTS specifications mandate that transactions be able to be distributed across application servers from different vendors. JBoss EAP 6 supports distributed JTA transactions.

10.2.12. About the ORB Portability API

The Object Request Broker (ORB) is a process which sends and receives messages to transaction participants, coordinators, resources, and other services distributed across multiple application servers. An ORB uses a standardized Interface Description Language (IDL) to communicate and interpret messages. Common Object Request Broker Architecture (CORBA) is the IDL used by the ORB in JBoss EAP 6.
The main type of service which uses an ORB is a system of distributed Java Transactions, using the Java Transaction Service (JTS) protocol. Other systems, especially legacy systems, may choose to use an ORB for communication, rather than other mechanisms such as remote Enterprise JavaBeans or JAX-WS or JAX-RS Web Services.
The ORB Portability API provides mechanisms to interact with an ORB. This API provides methods for obtaining a reference to the ORB, as well as placing an application into a mode where it listens for incoming connections from an ORB. Some of the methods in the API are not supported by all ORBs. In those cases, an exception is thrown.
The API consists of two different classes:

ORB Portability API Classes

  • com.arjuna.orbportability.orb
  • com.arjuna.orbportability.oa
Refer to the JBoss EAP 6 Javadocs bundle on the Red Hat Customer Portal for specific details about the methods and properties included in the ORB Portability API.

10.2.13. About Nested Transactions

Nested transactions are transactions where some participants are also transactions.

Benefits of Nested Transactions

Fault Isolation
If a subtransaction rolls back, perhaps because an object it is using fails, the enclosing transaction does not need to roll back.
Modularity
If a transaction is already associated with a call when a new transaction begins, the new transaction is nested within it. Therefore, if you know that an object requires transactions, you can them within the object. If the object's methods are invoked without a client transaction, then the object's transactions are top-level. Otherwise, they are nested within the scope of the client's transactions. Likewise, a client does not need to know whether an object is transactional. It can begin its own transaction.
Nested Transactions are only supported as part of the Java Transaction Service (JTS) API, and not part of the Java Transaction API (JTA). Attempting to nest (non-distributed) JTA transactions results in an exception.

10.3. Transaction Optimizations

10.3.1. Overview of Transaction Optimizations

Introduction
The Transactions subsystem of JBoss EAP 6 includes several optimizations which you can take advantage of in your applications.

10.3.2. About the LRCO Optimization for Single-phase Commit (1PC)

Although the 2-phase commit protocol (2PC) is more commonly encountered with transactions, some situations do not require, or cannot accommodate, both phases. In these cases, you can use the single phase commit (1PC) protocol. One situation where this might happen is when a non-XA-aware datasource needs to participate in the transaction.
In these situations, an optimization known as the Last Resource Commit Optimization (LRCO) is employed. The single-phase resource is processed last in the prepare phase of the transaction, and an attempt is made to commit it. If the commit succeeds, the transaction log is written and the remaining resources go through the 2PC. If the last resource fails to commit, the transaction is rolled back.
While this protocol allows for most transactions to complete normally, certain types of error can cause an inconsistent transaction outcome. Therefore, use this approach only as a last resort.
Where a single local TX datasource is used in a transaction, the LRCO is automatically applied to it.

10.3.3. About the Presumed-Abort Optimization

If a transaction is going to roll back, it can record this information locally and notify all enlisted participants. This notification is only a courtesy, and has no effect on the transaction outcome. After all participants have been contacted, the information about the transaction can be removed.
If a subsequent request for the status of the transaction occurs there will be no information available. In this case, the requester assumes that the transaction has aborted and rolled back. This presumed-abort optimization means that no information about participants needs to be made persistent until the transaction has decided to commit, since any failure prior to this point will be assumed to be an abort of the transaction.

10.3.4. About the Read-Only Optimization

When a participant is asked to prepare, it can indicate to the coordinator that it has not modified any data during the transaction. Such a participant does not need to be informed about the outcome of the transaction, since the fate of the participant has no affect on the transaction. This read-only participant can be omitted from the second phase of the commit protocol.

10.4. Transaction Outcomes

10.4.1. About Transaction Outcomes

There are three possible outcomes for a transaction.
Roll-back
If any transaction participant cannot commit, or the transaction coordinator cannot direct participants to commit, the transaction is rolled back. See Section 10.4.3, “About Transaction Roll-Back” for more information.
Commit
If every transaction participant can commit, the transaction coordinator directs them to do so. See Section 10.4.2, “About Transaction Commit” for more information.
Heuristic outcome
If some transaction participants commit and others roll back. it is termed a heuristic outcome. Heuristic outcomes require human intervention. See Section 10.4.4, “About Heuristic Outcomes” for more information.

10.4.2. About Transaction Commit

When a transaction participant commits, it makes its new state durable. The new state is created by the participant doing the work involved in the transaction. The most common example is when a transaction member writes records to a database.
After commit, information about the transaction is removed from the transaction coordinator, and the newly-written state is now the durable state.

10.4.3. About Transaction Roll-Back

A transaction participant rolls back by restoring its state to reflect the state before the transaction began. After a roll-back, the state is the same as if the transaction had never been started.

10.4.4. About Heuristic Outcomes

A heuristic outcome, or non-atomic outcome, is a transaction anomaly. It refers to a situation where some transaction participants committed their state, and others rolled back. A heuristic outcome causes state to be inconsistent.
Heuristic outcomes typically happen during the second phase of the 2-phase commit (2PC) protocol. They are often caused by failures to the underlying hardware or communications subsystems of the underlying servers.
There are four different types of heuristic outcome.
Heuristic rollback
The commit operation failed because some or all of the participants unilaterally rolled back the transaction.
Heuristic commit
An attempted rollback operation failed because all of the participants unilaterally committed. This may happen if, for example, the coordinator is able to successfully prepare the transaction but then decides to roll it back because of a failure on its side, such as a failure to update its log. In the interim, the participants may decide to commit.
Heuristic mixed
Some participants committed and others rolled back.
Heuristic hazard
The outcome of some of the updates is unknown. For the ones that are known, they have either all committed or all rolled back.
Heuristic outcomes can cause loss of integrity to the system, and usually require human intervention to resolve. Do not write code which relies on them.

10.4.5. JBoss Transactions Errors and Exceptions

For details about exceptions thrown by methods of the UserTransaction class, see the UserTransaction API specification at http://download.oracle.com/javaee/1.3/api/javax/transaction/UserTransaction.html.

10.5. Overview of JTA Transactions

10.5.1. About Java Transactions API (JTA)

Java Transactions API (JTA) is a specification for using transactions in Java Enterprise Edition applications. It is defined in JSR-907.
JTA transactions are not distributed across multiple application servers, and cannot be nested.
JTA transactions are controlled by the EJB container. Annotations are one method for creating and controlling transactions within your code.

10.5.2. Lifecycle of a JTA Transaction

When a resource asks to participate in a transaction, a chain of events is set in motion. The Transaction Manager is a process that lives within the application server and manages transactions. Transaction participants are objects which participate in a transaction. Resources are datasources, JMS connection factories, or other JCA connections.
  1. Your application starts a new transaction

    To begin a transaction, your application obtains an instance of class UserTransaction from JNDI or, if it is an EJB, from an annotation. The UserTransaction interface includes methods for beginning, committing, and rolling back top-level transactions. Newly-created transactions are automatically associated with their invoking thread. Nested transactions are not supported in JTA, so all transactions are top-level transactions.
    Calling UserTransaction.begin() starts a new transaction. Any resource that is used after that point is associated with the transaction. If more than one resource is enlisted, your transaction becomes an XA transaction, and participates in the two-phase commit protocol at commit time.
  2. Your application modifies its state.

    In the next step, your transaction performs its work and makes changes to its state.
  3. Your application decides to commit or roll back

    When your application has finished changing its state, it decides whether to commit or roll back. It calls the appropriate method. It calls UserTransaction.commit() or UserTransaction.rollback(). This is when the two-phase commit protocol (2PC) happens if you have enlisted more than one resource. Section 10.2.9, “About the 2-Phase Commit Protocol”
  4. The transaction manager removes the transaction from its records.

    After the commit or rollback completes, the transaction manager cleans up its records and removes information about your transaction.
Failure recovery
Failure recovery happens automatically. If a resource, transaction participant, or the application server become unavailable, the Transaction Manager handles recovery when the underlying failure is resolved.

10.6. Transaction Subsystem Configuration

10.6.2. Transactional Datasource Configuration

10.6.2.1. Configure Your Datasource to Use JTA Transactions

Summary
This task shows you how to enable Java Transactions API (JTA) on your datasource.
Prerequisites
You must meet the following conditions before continuing with this task:

Procedure 10.1. Configure the Datasource to use JTA Transactions

  1. Open the configuration file in a text editor.

    Depending on whether you run JBoss EAP 6 in a managed domain or standalone server, your configuration file will be in a different location.
    • Managed domain

      The default configuration file for a managed domain is in EAP_HOME/domain/configuration/domain.xml for Red Hat Enterprise Linux, and EAP_HOME\domain\configuration\domain.xml for Microsoft Windows Server.
    • Standalone server

      The default configuration file for a standalone server is in EAP_HOME/standalone/configuration/standalone.xml for Red Hat Enterprise Linux, and EAP_HOME\standalone\configuration\standalone.xml for Microsoft Windows Server.
  2. Locate the <datasource> tag that corresponds to your datasource.

    The datasource will have the jndi-name attribute set to the one you specified when you created it. For example, the ExampleDS datasource looks like this:
    <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="H2DS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
  3. Set the jta attribute to true.

    Add the following to the contents of your <datasource> tag, as they appear in the previous step: jta="true"
  4. Save the configuration file.

    Save the configuration file and exit the text editor.
  5. Start JBoss EAP 6.

    Relaunch the JBoss EAP 6 server.
Result:
JBoss EAP 6 starts, and your datasource is configured to use JTA transactions.

10.6.2.2. Configure an XA Datasource

Prerequisites
In order to add an XA Datasource, you need to log into the Management Console. See Section 10.6.2.3, “Log in to the Management Console” for more information.
  1. Add a new datasource.

    Add a new datasource to JBoss EAP 6. Follow the instructions in Section 10.6.2.4, “Create a Non-XA Datasource with the Management Interfaces”, but click the XA Datasource tab at the top.
  2. Configure additional properties as appropriate.

    All datasource parameters are listed in Section 10.6.2.5, “Datasource Parameters”.
Result
Your XA Datasource is configured and ready to use.

10.6.2.3. Log in to the Management Console

Prerequisites

  • JBoss EAP 6 must be running.

Procedure 10.2. Log in to the Management Console

  1. Navigate to the Management Console start page

    Navigate to the Management Console in your web browser. The default location is http://localhost:9990/console/, where port 9990 is predefined as the Management Console socket binding.
  2. Log in to the Management Console

    Enter the username and password of the account that you created previously to log into the Management Console login screen.
    The login screen for the Management console.

    Figure 10.1. Log in screen for the Management Console


Result

Once logged in, one of the Management Console landing pages appears:
Managed domain
Standalone server

10.6.2.4. Create a Non-XA Datasource with the Management Interfaces

Summary
This topic covers the steps required to create a non-XA datasource, using either the Management Console or the Management CLI.

Prerequisites

  • The JBoss EAP 6 server must be running.

Oracle Datasources

Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.

Procedure 10.3. Create a Datasource using either the Management CLI or the Management Console

    • Management CLI

      1. Launch the CLI tool and connect to your server.
      2. Run the following command to create a non-XA datasource, configuring the variables as appropriate:
        data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME  --connection-url=CONNECTION_URL
      3. Enable the datasource:
        data-source enable --name=DATASOURCE_NAME
    • Management Console

      1. Login to the Management Console.
      2. Navigate to the Datasources panel in the Management Console

          • Standalone Mode

            Select the Profile tab from the top-right of the console.
          • Domain Mode

            1. Select the Profiles tab from the top-right of the console.
            2. Select the appropriate profile from the drop-down box in the top left.
            3. Expand the Subsystems menu on the left of the console.
        1. Select ConnectorDatasources from the menu on the left of the console.
        Datasources panel

        Figure 10.2. Datasources panel


      3. Create a new datasource

        1. Select the Add button at the top of the Datasources panel.
        2. Enter the new datasource attributes in the Create Datasource wizard and proceed with the Next button.
        3. Enter the JDBC driver details in the Create Datasource wizard and proceed with the Next button.
        4. Enter the connection settings in the Create Datasource wizard and select the Done button.
Result
The non-XA datasource has been added to the server. It is now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

10.6.2.5. Datasource Parameters

Table 10.1. Datasource parameters common to non-XA and XA datasources

Parameter Description
jndi-name The unique JNDI name for the datasource.
pool-name The name of the management pool for the datasource.
enabled Whether or not the datasource is enabled.
use-java-context
Whether to bind the datasource to global JNDI.
spy
Enable spy functionality on the JDBC layer. This logs all JDBC traffic to the datasource. The logging-category parameter must also be set to org.jboss.jdbc.
use-ccm Enable the cached connection manager.
new-connection-sql A SQL statement which executes when the connection is added to the connection pool.
transaction-isolation
One of the following:
  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_SERIALIZABLE
  • TRANSACTION_NONE
url-delimiter The delimiter for URLs in a connection-url for High Availability (HA) clustered databases.
url-selector-strategy-class-name A class that implements interface org.jboss.jca.adapters.jdbc.URLSelectorStrategy.
security
Contains child elements which are security settings. Refer to Table 10.6, “Security parameters”.
validation
Contains child elements which are validation settings. Refer to Table 10.7, “Validation parameters”.
timeout
Contains child elements which are timeout settings. Refer to Table 10.8, “Timeout parameters”.
statement
Contains child elements which are statement settings. Refer to Table 10.9, “Statement parameters”.

Table 10.2. Non-XA datasource parameters

Parameter Description
jta Enable JTA integration for non-XA datasources. Does not apply to XA datasources.
connection-url The JDBC driver connection URL.
driver-class The fully-qualified name of the JDBC driver class.
connection-property
Arbitrary connection properties passed to the method Driver.connect(url,props). Each connection-property specifies a string name/value pair. The property name comes from the name, and the value comes from the element content.
pool
Contains child elements which are pooling settings. Refer to Table 10.4, “Pool parameters common to non-XA and XA datasources”.

Table 10.3. XA datasource parameters

Parameter Description
xa-datasource-property
A property to assign to implementation class XADataSource. Specified by name=value. If a setter method exists, in the format setName, the property is set by calling a setter method in the format of setName(value).
xa-datasource-class
The fully-qualified name of the implementation class javax.sql.XADataSource.
driver
A unique reference to the classloader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
xa-pool
recovery
Contains child elements which are recovery settings. Refer to Table 10.10, “Recovery parameters”.

Table 10.4. Pool parameters common to non-XA and XA datasources

Parameter Description
min-pool-size The minimum number of connections a pool holds.
max-pool-size The maximum number of connections a pool can hold.
prefill Whether to try to prefill the connection pool. An empty element denotes a true value. The default is false.
use-strict-min Whether the pool-size is strict. Defaults to false.
flush-strategy
Whether the pool should be flushed in the case of an error. Valid values are:
  • FailingConnectionOnly
  • IdleConnections
  • EntirePool
The default is FailingConnectionOnly.
allow-multiple-users Specifies if multiple users will access the datasource through the getConnection(user, password) method, and whether the internal pool type should account for this behavior.

Table 10.5. XA pool parameters

Parameter Description
is-same-rm-override Whether the javax.transaction.xa.XAResource.isSameRM(XAResource) class returns true or false.
interleaving Whether to enable interleaving for XA connection factories.
no-tx-separate-pools Whether to create separate sub-pools for each context. This is required for Oracle datasources, which do not allow XA connections to be used both inside and outside of a JTA transaction.
pad-xid Whether to pad the Xid.
wrap-xa-resource
Whether to wrap the XAResource in an org.jboss.tm.XAResourceWrapper instance.

Table 10.6. Security parameters

Parameter Description
user-name The username to use to create a new connection.
password The password to use to create a new connection.
security-domain Contains the name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration.
reauth-plugin Defines a reauthentication plugin to use to reauthenticate physical connections.

Table 10.7. Validation parameters

Parameter Description
valid-connection-checker
An implementation of interface org.jboss.jca.adaptors.jdbc.ValidConnectionChecker which provides a SQLException.isValidConnection(Connection e) method to validate a connection. An exception means the connection is destroyed. This overrides the parameter check-valid-connection-sql if it is present.
check-valid-connection-sql An SQL statement to check validity of a pool connection. This may be called when a managed connection is taken from a pool for use.
validate-on-match
Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set.
Specifying "true" for validate-on-match is typically not done in conjunction with specifying "true" for background-validation. Validate-on-match is needed when a client must have a connection validated prior to use. This parameter is true by default.
background-validation
Specifies that connections are validated on a background thread. Background validation is a performance optimization when not used with validate-on-match. If validate-on-match is true, using background-validation could result in redundant checks. Background validation does leave open the opportunity for a bad connection to be given to the client for use (a connection goes bad between the time of the validation scan and prior to being handed to the client), so the client application must account for this possibility.
background-validation-millis The amount of time, in milliseconds, that background validation runs.
use-fast-fail
If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to false.
stale-connection-checker
An instance of org.jboss.jca.adapters.jdbc.StaleConnectionChecker which provides a Boolean isStaleConnection(SQLException e) method. If this method returns true, the exception is wrapped in an org.jboss.jca.adapters.jdbc.StaleConnectionException, which is a subclass of SQLException.
exception-sorter
An instance of org.jboss.jca.adapters.jdbc.ExceptionSorter which provides a Boolean isExceptionFatal(SQLException e) method. This method validates whether an exception should be broadcast to all instances of javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message.

Table 10.8. Timeout parameters

Parameter Description
use-try-lock Uses tryLock() instead of lock(). This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Defaults to 60 seconds. As an example, to set a timeout of 5 minutes, set <use-try-lock>300</use-try-lock>.
blocking-timeout-millis The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, an exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds.
idle-timeout-minutes
The maximum time, in minutes, before an idle connection is closed. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest idle-timeout-minutes of any pool.
set-tx-query-timeout
Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to false.
query-timeout Timeout for queries, in seconds. The default is no timeout.
allocation-retry The number of times to retry allocating a connection before throwing an exception. The default is 0, so an exception is thrown upon the first failure.
allocation-retry-wait-millis
How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
xa-resource-timeout
If non-zero, this value is passed to method XAResource.setTransactionTimeout.

Table 10.9. Statement parameters

Parameter Description
track-statements
Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked.

Valid values

  • true: statements and result sets are tracked, and a warning is issued if they are not closed.
  • false: neither statements or result sets are tracked.
  • nowarn: statements are tracked but no warning is issued. This is the default.
prepared-statement-cache-size The number of prepared statements per connection, in a Least Recently Used (LRU) cache.
share-prepared-statements
Whether asking for the same statement twice without closing it uses the same underlying prepared statement. The default is false.

Table 10.10. Recovery parameters

Parameter Description
recover-credential A username/password pair or security domain to use for recovery.
recover-plugin
An implementation of the org.jboss.jca.core.spi.recoveryRecoveryPlugin class, to be used for recovery.

10.6.3. Transaction Logging

10.6.3.1. About Transaction Log Messages

To track transaction status while keeping the log files readable, use the DEBUG log level for the transaction logger. For detailed debugging, use the TRACE log level. Refer to Section 10.6.3.2, “Configure Logging for the Transaction Subsystem” for information on configuring the transaction logger.
The transaction manager can generate a lot of logging information when configured to log in the TRACE log level. Following are some of the most commonly-seen messages. This list is not comprehensive, so you may see other messages than these.

Table 10.11. Transaction State Change

Transaction Begin
When a transaction begins, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::Begin:1342
tsLogger.logger.trace("BasicAction::Begin() for action-id "+ get_uid());
Transaction Commit
When a transaction commits, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::End:1342
tsLogger.logger.trace("BasicAction::End() for action-id "+ get_uid());
Transaction Rollback
When a transaction rolls back, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::Abort:1575
tsLogger.logger.trace("BasicAction::Abort() for action-id "+ get_uid());
Transaction Timeout
When a transaction times out, the following code is executed:
com.arjuna.ats.arjuna.coordinator.TransactionReaper::doCancellations:349
tsLogger.logger.trace("Reaper Worker " + Thread.currentThread() + " attempting to cancel " + e._control.get_uid());
You will then see the same thread rolling back the transaction as shown above.

10.6.3.2. Configure Logging for the Transaction Subsystem

Summary
Use this procedure to control the amount of information logged about transactions, independent of other logging settings in JBoss EAP 6. The main procedure shows how to do this in the web-based Management Console. The Management CLI command is given afterward.

Procedure 10.4. Configure the Transaction Logger Using the Management Console

  1. Navigate to the Logging configuration area.

    In the Management Console, click the Profiles tab at the top left of the screen. If you use a managed domain, choose the server profile you wish to configure, from the Profile selection box at the top right.
    Expand the Core menu, and click the Logging label.
  2. Edit the com.arjuna attributes.

    Click the Edit button in the Details section, toward the bottom of the page. This is where you can add class-specific logging information. The com.arjuna class is already present. You can change the log level and whether to use parent handlers.
    Log Level
    The log level is WARN by default. Because transactions can produce a large quantity of logging output, the meaning of the standard logging levels is slightly different for the transaction logger. In general, messages tagged with levels at a lower severity than the chosen level are discarded.

    Transaction Logging Levels, from Most to Least Verbose

    • TRACE
    • DEBUG
    • INFO
    • WARN
    • ERROR
    • FAILURE
    Use Parent Handlers
    Whether the logger should send its output to its parent logger. The default behavior is true.
  3. Changes take effect immediately.

10.6.3.3. Browse and Manage Transactions

The command-line based Management CLI supports the ability to browse and manipulate transaction records. This functionality is provided by the interaction between the Transaction Manager and the Management API of JBoss EAP 6.
The transaction manager stores information about each pending transaction and the participants involved the transaction, in a persistent storage called the object store. The Management API exposes the object store as a resource called the log-store. An API operation called probe reads the transaction logs and creates a node for each log. You can call the probe command manually, whenever you need to refresh the log-store. It is normal for transaction logs to appear and disappear quickly.

Example 10.1. Refresh the Log Store

This command refreshes the Log Store for server groups which use the profile default in a managed domain. For a standalone server, remove the profile=default from the command.
/profile=default/subsystem=transactions/log-store=log-store/:probe

Example 10.2. View All Prepared Transactions

To view all prepared transactions, first refresh the log store (see Example 10.1, “Refresh the Log Store”), then run the following command, which functions similarly to a filesystem ls command.
ls /profile=default/subsystem=transactions/log-store=log-store/transactions
Each transaction is shown, along with its unique identifier. Individual operations can be run against an individual transaction (see Manage a Transaction).

Manage a Transaction

View a transaction's attributes.
To view information about a transaction, such as its JNDI name, EIS product name and version, or its status, use the :read-resource CLI command.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:read-resource
View the participants of a transaction.
Each transaction log contains a child element called participants. Use the read-resource CLI command on this element to see the participants of the transaction. Participants are identified by their JNDI names.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9/participants=java\:\/JmsXA:read-resource
The result may look similar to this:
{
   "outcome" => "success",
   "result" => {
       "eis-product-name" => "HornetQ",
       "eis-product-version" => "2.0",
       "jndi-name" => "java:/JmsXA",
       "status" => "HEURISTIC",
       "type" => "/StateManager/AbstractRecord/XAResourceRecord"
   }
}
The outcome status shown here is in a HEURISTIC state and is eligible for recover. Refer to Recover a transaction. for more details.
Delete a transaction.
Each transaction log supports a :delete operation, to delete the transaction log representing the transaction.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:delete
Recover a transaction.
Each transaction log supports recovery via the :recover CLI command.

Recovery of Heuristic Transactions and Participants

  • If the transaction's status is HEURISTIC, the recovery operation changes the state to PREPARE and triggers a recovery.
  • If one of the transaction's participants is heuristic, the recovery operation tries to replay the commit operation. If successful, the participant is removed from the transaction log. You can verify this by re-running the :probe operation on the log-store and checking that the participant is no longer listed. If this is the last participant, the transaction is also deleted.
Refresh the status of a transaction which needs recovery.
If a transaction needs recovery, you can use the :refresh CLI command to be sure it still requires recovery, before attempting the recovery.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:refresh

Note: Browsing JTS Transactions

For JTS transactions, if participants are on remote servers, a limited amount of information may be available to the Transaction Manager. In this case, it is recommended that you use the file-based object store, rather than the HornetQ storage mode. This is the default behavior. To use the HornetQ storage mode, you can set the value of the use-hornetq-store option to true, in the Transaction Manager configuration. Refer to Section 10.7.8.2, “Configure the Transaction Manager” for information on configuring the Transaction Manager.
View Transaction Statistics
If Transaction Manager (TM) statistics are enabled, you can view statistics about the Transaction Manager and transaction subsystem. Refer to Section 10.7.8.2, “Configure the Transaction Manager” for information about how to enable TM statistics.
You can view statistics either via the web-based Management Console or the command-line Management CLI. In the web-based Management Console, Transaction statistics are available via RuntimeSubsystem MetricsTransactions. Transaction statistics are available for each server in a managed domain, as well. You can specify the server in the Server selection box at the top left.
The following table shows each available statistic, its description, and the CLI command to view the statistic.

Table 10.12. Transaction Subsystem Statistics

Statistic Description CLI Command
Total
The total number of transactions processed by the Transaction Manager on this server.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-transactions,include-defaults=true)
Committed
The number of committed transactions processed by the Transaction Manager on this server.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-committed-transactions,include-defaults=true)
Aborted
The number of aborted transactions processed by the Transaction Manager on this server.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-aborted-transactions,include-defaults=true)
Timed Out
The number of timed out transactions processed by the Transaction Manager on this server.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-timed-out-transactions,include-defaults=true)
Heuristics
Not available in the Management Console. Number of transactions in a heuristic state.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-heuristics,include-defaults=true)
In-Flight Transactions
Not available in the Management Console. Number of transactions which have begun but not yet terminated.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-inflight-transactions,include-defaults=true)
Failure Origin - Applications
The number of failed transactions whose failure origin was an application.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-application-rollbacks,include-defaults=true)
Failure Origin - Resources
The number of failed transactions whose failure origin was a resource.
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-resource-rollbacks,include-defaults=true)

10.7. Use JTA Transactions

10.7.2. Control Transactions

Introduction
This list of procedures outlines the different ways to control transactions in your applications which use JTA or JTS APIs.

10.7.3. Begin a Transaction

This procedure shows how to begin a new JTA transaction, or how to participate in a distributed transaction using the Java Transaction Service (JTS) protocol.
Distributed Transactions
A distributed transaction is one where the transaction participants are in separate applications on multiple servers. If a participant joins a transaction that already exists, rather than creating a new transaction context, the two (or more) participants which share the context are participating a distributed transaction. In order to use distribured transactions, you must configure the ORB. Refer to Refer to the ORB Configuration section of the Administration and Configuration Guide for more information on ORB configuration.
  1. Get an instance of UserTransaction.

    You can get the instance using JNDI, injection, or an EJB's EjbContext, if the EJB uses bean-managed transactions, by means of a @TransactionManagement(TransactionManagementType.BEAN) annotation.
    • JNDI

      new InitialContext().lookup("java:comp/UserTransaction")
    • Injection

      @Resource UserTransaction userTransaction;
    • EjbContext

      EjbContext.getUserTransaction()
  2. Call UserTransaction.begin() after you connect to your datasource.

    ...
    try {
        System.out.println("\nCreating connection to database: "+url);
        stmt = conn.createStatement();  // non-tx statement
        try {
            System.out.println("Starting top-level transaction.");
            userTransaction.begin();
            stmtx = conn.createStatement(); // will be a tx-statement
            ...
        }
    }
    
Participate in an existing transaction using the JTS API.
One of the benefits of EJBs is that the container manages all of the transactions. If you have set up the ORB, the container will manage distributed transactions for you.
Result:
The transaction begins. All uses of your datasource until you commit or roll back the transaction are transactional.

Note

10.7.4. Nest Transactions

Nested transactions are only supported when you use distributed transactions, with the JTS API. In addition, many database vendors do not support nested transactions, so check with your database vendor before you add nested transactions to your application.
The OTS specifications allow for a limited type of nested transaction, where the subtransaction commit protocol is the same as a top-level transactions. There are two phases, a prepare phase and a commit or abort phase. This type of nested transaction can lead to inconsistent results, such as in a scenario in which a subtransaction coordinator discovers part of the way through committing that a resources cannot commit. The coordinator may not be able to tell the committed resources to abort, and a heuristic outcome occurs. This strict OTS nested transaction is available via the CosTransactions::SubtransactionAwareResource interface.
The JBoss EAP 6 implementation of JTS supports this type of nested transaction. It also supports a type of nested transaction with a multi-phase commit protocol, which avoids the problems that are possible with the strict OTS model. This type of nested transaction is available via the ArjunaOTS::ArjunaSubtranAwareResource. It is driven by a two-phase commit protocol whenever a nested transaction commits.
To create a nested transaction, you create a new transaction within a parent transaction. Refer to Section 10.7.3, “Begin a Transaction” for information on creating a transaction.
The effect of a nested transaction depends on upon the commit/roll back of its enclosing transactions. The effects are recovered if the enclosing transaction aborts, even if the nested transaction has committed.

10.7.5. Commit a Transaction

This procedure shows how to commit a transaction using the Java Transaction API (JTA). This API is used for both local transactions and distributed transactions. Distributed transactions are managed by the Java Transaction Server (JTS) and require configuration of an Object Request Broker (ORB). For more information on ORB configuration, refer to the ORB Configuration section of the Administration and Configuration Guide.
Prerequisites
You must begin a transaction before you can commit it. For information on how to begin a transaction, refer to Section 10.7.3, “Begin a Transaction”.
  1. Call the commit() method on the UserTransaction.

    When you call the commit() method on the UserTransaction, the Transaction Manager attempts to commit the transaction.
    @Inject
    private UserTransaction userTransaction;
    
    public void updateTable(String key, String value)
        EntityManager entityManager = entityManagerFactory.createEntityManager();
        try {
            userTransaction.begin():
            <!-- Perform some data manipulation using entityManager -->
    			  ...
    			  // Commit the transaction
            userTransaction.commit();
        } catch (Exception ex) {
            <!-- Log message or notify Web page -->
            ...
            try {
                userTransaction.rollback();
            } catch (SystemException se) {
                throw new RuntimeException(se);
            }
            throw new RuntimeException(e);
        } finally {
            entityManager.close();
        }
    }
    
    
    
  2. If you use Container Managed Transactions (CMT), you do not need to manually commit.

    If you configure your bean to use Container Managed Transactions, the container will manage the transaction lifecycle for you based on annotations you configure in the code.
Result
Your datasource commits and your transaction ends, or an exception is thrown.

Note

10.7.6. Roll Back a Transaction

This procedure shows how to roll back a transaction using the Java Transaction API (JTA). This API is used for both local transactions and distributed transactions. Distributed transactions are managed by the Java Transaction Server (JTS) and require configuration of an Object Request Broker (ORB). For more information on ORB configuration, refer to the ORB Configuration section of the Administration and Configuration Guide.
Prerequisites
You must begin a transaction before you can roll it back. For information on how to begin a transaction, refer to Section 10.7.3, “Begin a Transaction”.
  1. Call the rollback() method on the UserTransaction.

    When you call the rollback() method on the UserTransaction, the Transaction Manager attempts to roll back the transaction and return the data to its previous state.
     
    @Inject
    private UserTransaction userTransaction;
    
    public void updateTable(String key, String value)
        EntityManager entityManager = entityManagerFactory.createEntityManager();
        try {
            userTransaction.begin():
            <!-- Perform some data manipulation using entityManager -->
    			  ...
    			  // Commit the transaction
            userTransaction.commit();
        } catch (Exception ex) {
            <!-- Log message or notify Web page -->
            ...
            try {
                userTransaction.rollback();
            } catch (SystemException se) {
                throw new RuntimeException(se);
            }
            throw new RuntimeException(e);
        } finally {
            entityManager.close();
        }
    }
    
    
    
  2. If you use Container Managed Transactions (CMT), you do not need to manually roll back the transaction.

    If you configure your bean to use Container Managed Transactions, the container will manage the transaction lifecycle for you based on annotations you configure in the code.
Result
Your transaction is rolled back by the Transaction Manager.

Note

10.7.7. Handle a Heuristic Outcome in a Transaction

This procedure shows how to handle a heuristic outcome in a JTA transaction, whether it is local or distributed, using the Java Transaction Service (JTS). To use distributed transactions, you need to configure the ORB. Refer to the ORB Configuration section of the Administration and Configuration Guide for more information on ORB configuration.
Heuristic transaction outcomes are uncommon and usually have exceptional causes. The word heuristic means "by hand", and that is the way that these outcomes usually have to be handled. Refer to Section 10.4.4, “About Heuristic Outcomes” for more information about heuristic transaction outcomes.

Procedure 10.5. Handle a heuristic outcome in a transaction

  1. Determine the cause

    The over-arching cause of a heuristic outcome in a transaction is that a resource manager promised it could commit or roll-back, and then failed to fulfill the promise. This could be due to a problem with a third-party component, the integration layer between the third-party component and JBoss EAP 6, or JBoss EAP 6 itself.
    By far, the most common two causes of heuristic errors are transient failures in the environment and coding errors in the code dealing with resource managers.
  2. Fix transient failures in the environment

    Typically, if there is a transient failure in your environment, you will know about it before you find out about the heuristic error. This could be a network outage, hardware failure, database failure, power outage, or a host of other things.
    If you experienced the heuristic outcome in a test environment, during stress testing, it provides information about weaknesses in your environment.

    Heuristic transactions are not recovered

    JBoss EAP 6 will automatically recover transactions that were in a non-heuristic state at the time of the failure, but it does not attempt to recover heuristic transactions.
  3. Contact resource manager vendors

    If you have no obvious failure in your environment, or the heuristic outcome is easily reproducible, it is probably a coding error. Contact third-party vendors to find out if a solution is available. If you suspect the problem is in the transaction manager of JBoss EAP 6 itself, contact Red Hat Global Support Services.
  4. In a test environment, delete the logs and restart JBoss EAP 6.

    In a test environment, or if you do not care about the integrity of the data, deleting the transaction logs and restarting JBoss EAP 6 gets rid of the heuristic outcome. The transaction logs are located in EAP_HOME/standalone/data/tx-object-store/ for a standalone server, or EAP_HOME/domain/servers/SERVER_NAME/data/tx-object-store in a managed domain, by default. In the case of a managed domain, SERVER_NAME refers to the name of the individual server participating in a server group.
  5. Resolve the outcome by hand

    The process of resolving the transaction outcome by hand is very dependent on the exact circumstance of the failure. Typically, you need to take the following steps, applying them to your situation:
    1. Identify which resource managers were involved.
    2. Examine the state in the transaction manager and the resource managers.
    3. Manually force log cleanup and data reconciliation in one or more of the involved components.
    The details of how to perform these steps are out of the scope of this documentation.

10.7.8. Transaction Timeouts

10.7.8.1. About Transaction Timeouts

In order to preserve atomicity and adhere to the ACID standard for transactions, some parts of a transaction can be long-running. Transaction participants need to lock parts of datasources when they commit, and the transaction manager needs to wait to hear back from each transaction participant before it can direct them all whether to commit or roll back. Hardware or network failures can cause resources to be locked indefinitely.
Transaction timeouts can be associated with transactions in order to control their lifecycle. If a timeout threshold passes before the transaction commits or rolls back, the timeout causes the transaction to be rolled back automatically.
You can configure default timeout values for the entire transaction subsystem, or you disable default timeout values, and specify timeouts on a per-transaction basis.

10.7.8.2. Configure the Transaction Manager

You can configure the Transaction Manager (TM) using the web-based Management Console or the command-line Management CLI. For each command or option given, the assumption is made that you are running JBoss EAP 6 as a Managed Domain. If you use a Standalone Server or you want to modify a different profile than default, you may need to modify the steps and commands in the following ways.

Notes about the Example Commands

  • For the Management Console, the default profile is the one which is selected when you first log into the console. If you need to modify the Transaction Manager's configuration in a different profile, select your profile instead of default, in each instruction.
    Similarly, substitute your profile for the default profile in the example CLI commands.
  • If you use a Standalone Server, only one profile exists. Ignore any instructions to choose a specific profile. In CLI commands, remove the /profile=default portion of the sample commands.

Note

In order for the TM options to be visible in the Management Console or Management CLI, the transactions subsystem must be enabled. It is enabled by default, and required for many other subsystems to function properly, so it is very unlikely that it would be disabled.
Configure the TM Using the Management Console
To configure the TM using the web-based Management Console, select the Runtime tab from the list in the upper left side of the Management Console screen. If you use a managed domain, you have the choice of several profiles. Choose the correct one from the Profile selection box at the upper right of the Profiles screen. Expand the Container menu and select Transactions.
Most options are shown in the Transaction Manager configuration page. The Recovery options are hidden by default. Click the Recovery header to expand them. Click the Edit button to edit any of the options. Changes take effect immediately.
Click the Need Help? label to display in-line help text.
Configure the TM using the Management CLI
In the Management CLI, you can configure the TM using a series of commands. The commands all begin with /profile=default/subsystem=transactions/ for a managed domain with profile default, or /subsystem=transactions for a Standalone Server.

Table 10.13. TM Configuration Options

Option Description CLI Command
Enable Statistics
Whether to enable transaction statistics. These statistics can be viewed in the Management Console in the Subsystem Metrics section of the Runtime tab.
/profile=default/subsystem=transactions/:write-attribute(name=enable-statistics,value=true)
Enable TSM Status
Whether to enable the transaction status manager (TSM) service, which is used for out-of-process recovery.
/profile=default/subsystem=transactions/:write-attribute(name=enable-tsm-status,value=false)
Default Timeout
The default transaction timeout. This defaults to 300 seconds. You can override this programmatically, on a per-transaction basis.
/profile=default/subsystem=transactions/:write-attribute(name=default-timeout,value=300)
Path
The relative or absolute filesystem path where the transaction manager core stores data. By default the value is a path relative to the value of the relative-to attribute.
/profile=default/subsystem=transactions/:write-attribute(name=path,value=var)
Relative To
References a global path configuration in the domain model. The default value is the data directory for JBoss EAP 6, which is the value of the property jboss.server.data.dir, and defaults to EAP_HOME/domain/data/ for a Managed Domain, or EAP_HOME/standalone/data/ for a Standalone Server instance. The value of the path TM attribute is relative to this path. Use an empty string to disable the default behavior and force the value of the path attribute to be treated as an absolute path.
/profile=default/subsystem=transactions/:write-attribute(name=relative-to,value=jboss.server.data.dir)
Object Store Path
A relative or absolute filesystem path where the TM object store stores data. By default relative to the object-store-relative-to parameter's value.
/profile=default/subsystem=transactions/:write-attribute(name=object-store-path,value=tx-object-store)
Object Store Path Relative To
References a global path configuration in the domain model. The default value is the data directory for JBoss EAP 6, which is the value of the property jboss.server.data.dir, and defaults to EAP_HOME/domain/data/ for a Managed Domain, or EAP_HOME/standalone/data/ for a Standalone Server instance. The value of the path TM attribute is relative to this path. Use an empty string to disable the default behavior and force the value of the path attribute to be treated as an absolute path.
/profile=default/subsystem=transactions/:write-attribute(name=object-store-relative-to,value=jboss.server.data.dir)
Socket Binding
Specifies the name of the socket binding used by the Transaction Manager for recovery and generating transaction identifiers, when the socket-based mechanism is used. Refer to process-id-socket-max-ports for more information on unique identifier generation. Socket bindings are specified per server group in the Server tab of the Management Console.
/profile=default/subsystem=transactions/:write-attribute(name=socket-binding,value=txn-recovery-environment)
Status Socket Binding
Specifies the socket binding to use for the Transaction Status manager.
/profile=default/subsystem=transactions/:write-attribute(name=status-socket-binding,value=txn-status-manager)
Recovery Listener
Whether or not the Transaction Recovery process should listen on a network socket. Defaults to false.
/profile=default/subsystem=transactions/:write-attribute(name=recovery-listener,value=false)

The following options are for advanced use and can only be modified using the Management CLI. Be cautious when changing them from the default configuration. Contact Red Hat Global Support Services for more information.

Table 10.14. Advanced TM Configuration Options

Option Description CLI Command
jts
Whether to use Java Transaction Service (JTS) transactions. Defaults to false, which uses JTA transactions only.
/profile=default/subsystem=transactions/:write-attribute(name=jts,value=false)
node-identifier
The node identifier for the JTS service. This should be unique per JTS service, because the Transaction Manager uses this for recovery.
/profile=default/subsystem=transactions/:write-attribute(name=node-identifier,value=1)
process-id-socket-max-ports
The Transaction Manager creates a unique identifier for each transaction log. Two different mechanisms are provided for generating unique identifiers: a socket-based mechanism and a mechanism based on the process identifier of the process.
In the case of the socket-based identifier, a socket is opened and its port number is used for the identifier. If the port is already in use, the next port is probed, until a free one is found. The process-id-socket-max-ports represents the maximum number of sockets the TM will try before failing. The default value is 10.
/profile=default/subsystem=transactions/:write-attribute(name=process-id-socket-max-ports,value=10)
process-id-uuid
Set to true to use the process identifier to create a unique identifier for each transaction. Otherwise, the socket-based mechanism is used. Defaults to true. Refer to process-id-socket-max-ports for more information.
/profile=default/subsystem=transactions/:write-attribute(name=process-id-uuid,value=true)
use-hornetq-store
Use HornetQ's journaled storage mechanisms instead of file-based storage, for the transaction logs. This is disabled by default, but can improve I/O performance. It is not recommended for JTS transactions on separate Transaction Managers. .
/profile=default/subsystem=transactions/:write-attribute(name=use-hornetq-store,value=false)

10.7.9. JTA Transaction Error Handling

10.7.9.1. Handle Transaction Errors

Transaction errors are challenging to solve because they are often dependent on timing. Here are some common errors and ideas for troubleshooting them.

Handle transaction errors

These guidelines do not apply to heuristic errors. If you experience heuristic errors, refer to Section 10.7.7, “Handle a Heuristic Outcome in a Transaction” and contact Red Hat Global Support Services for assistance.
The transaction timed out but the business logic thread did not notice
This type of error often manifests itself when Hibernate is unable to obtain a database connection for lazy loading. If it happens frequently, you can lengthen the timeout value. Refer to Section 10.7.8.2, “Configure the Transaction Manager”.
If that is not feasible, you may be able to tune your external environment to perform more quickly, or restructure your code to be more efficient. Contact Red Hat Global Support Services if you still have trouble with timeouts.
The transaction is already running on a thread, or you receive a NotSupportedException exception
The NotSupportedException exception usually indicates that you attempted to nest a JTA transaction, and this is not supported. If you were not attempting to nest a transaction, it is likely that another transaction was started in a thread pool task, but finished the task without suspending or ending the transaction.
Applications typically use UserTransaction, which handles this automatically. If so, there may be a problem with a framework.
If your code does use TransactionManager or Transaction methods directly, be aware of the following behavior when committing or rolling back a transaction. If your code uses TransactionManager methods to control your transactions, committing or rolling back a transaction disassociates the transaction from the current thread. However, if your code uses Transaction methods, the transaction may not be associated with the running thread, and you need to disassociate it from its threads manually, before returning it to the thread pool.
You are unable to enlist a second local resource
This error happens if you try to enlist a second non-XA resource into a transaction. If you need multiple resources in a transaction, they must be XA.

10.8. ORB Configuration

10.8.1. About Common Object Request Broker Architecture (CORBA)

Common Object Request Broker Architecture (CORBA) is a standard that enables applications and services to work together even when they are written in multiple, otherwise-incompatible, languages or hosted on separate platforms. CORBA requests are brokered by a server-side component called an Object Request Broker (ORB). JBoss EAP 6 provides an ORB instance, by means of the JacORB component.
The ORB is used internally for Java Transaction Service (JTS) transactions, and is also available for use by your own applications.

10.8.2. Configure the ORB for JTS Transactions

In a default installation of JBoss EAP 6, the ORB is disabled. You can enable the ORB using the command-line Management CLI.

Note

In a managed domain, the JacORB subsystem is available in full and full-ha profiles only. In a standalone server, it is available when you use the standalone-full.xml or standalone-full-ha.xml configurations.

Procedure 10.6. Configure the ORB using the Management Console

  1. View the profile settings.

    Select Profiles (managed domain) or Profile (standalone server) from the top right of the management console. If you use a managed domain, select either the full or full-ha profile from the selection box at the top left.
  2. Modify the Initializers Settings

    Expand the Subsystems menu at the left, if necessary. Expand the Container sub-menu and click JacORB.
    In the form that appears in the main screen, select the Initializers tab and click the Edit button.
    Enable the security interceptors by setting the value of Security to on.
    To enable the ORB for JTS, set the Transaction Interceptors value to on, rather than the default spec.
    Refer to the Need Help? link in the form for detailed explanations about these values. Click Save when you have finished editing the values.
  3. Advanced ORB Configuration

    Refer to the other sections of the form for advanced configuration options. Each section includes a Need Help? link with detailed information about the parameters.
Configure the ORB using the Management CLI
You can configure each aspect of the ORB using the Management CLI. The following commands configure the initializers to the same values as the procedure above, for the Management Console. This is the minimum configuration for the ORB to be used with JTS.
These commands are configured for a managed domain using the full profile. If necessary, change the profile to suit the one you need to configure. If you use a standalone server, omit the /profile=full portion of the commands.

Example 10.3. Enable the Security Interceptors

/profile=full/subsystem=jacorb/:write-attribute(name=security,value=on)

Example 10.4. Enable the ORB for JTS

/profile=full/subsystem=jacorb/:write-attribute(name=transactions,value=on)

10.9. Transaction References

10.9.1. JBoss Transactions Errors and Exceptions

For details about exceptions thrown by methods of the UserTransaction class, see the UserTransaction API specification at http://download.oracle.com/javaee/1.3/api/javax/transaction/UserTransaction.html.

10.9.2. JTA Clustering Limitations

JTA transactions cannot be clustered across multiple instances of JBoss EAP 6. For this behavior, use JTS transactions.
To use JTS transactions, you need to configure the ORB: Section 10.8.2, “Configure the ORB for JTS Transactions”.

10.9.3. JTA Transaction Example

This example illustrates how to begin, commit, and roll back a JTA transaction. You need to adjust the connection and datasource parameters to suit your environment, and set up two test tables in your database.

Example 10.5. JTA Transaction example

public class JDBCExample {
    public static void main (String[] args) {
        Context ctx = new InitialContext();
        // Change these two lines to suit your environment.
        DataSource ds = (DataSource)ctx.lookup("jdbc/ExampleDS");
        Connection conn = ds.getConnection("testuser", "testpwd");
        Statement stmt = null; // Non-transactional statement
        Statement stmtx = null; // Transactional statement
        Properties dbProperties = new Properties();

        // Get a UserTransaction
        UserTransaction txn = new InitialContext().lookup("java:comp/UserTransaction");

        try {
            stmt = conn.createStatement();  // non-tx statement
            
            // Check the database connection.
            try {
                stmt.executeUpdate("DROP TABLE test_table");
                stmt.executeUpdate("DROP TABLE test_table2");
            }
            catch (Exception e) {
                // assume not in database.
            }
            
            try {
                stmt.executeUpdate("CREATE TABLE test_table (a INTEGER,b INTEGER)");
                stmt.executeUpdate("CREATE TABLE test_table2 (a INTEGER,b INTEGER)");
            }
            catch (Exception e) {
            }

            try {
                System.out.println("Starting top-level transaction.");
                
                txn.begin();
                
                stmtx = conn.createStatement(); // will be a tx-statement

                // First, we try to roll back changes
                
                System.out.println("\nAdding entries to table 1.");
                
                stmtx.executeUpdate("INSERT INTO test_table (a, b) VALUES (1,2)");
                
                ResultSet res1 = null;
                
                System.out.println("\nInspecting table 1.");
                
                res1 = stmtx.executeQuery("SELECT * FROM test_table");
                
                while (res1.next()) {
                    System.out.println("Column 1: "+res1.getInt(1));
                    System.out.println("Column 2: "+res1.getInt(2));
                }
                System.out.println("\nAdding entries to table 2.");

                stmtx.executeUpdate("INSERT INTO test_table2 (a, b) VALUES (3,4)");
                res1 = stmtx.executeQuery("SELECT * FROM test_table2");

                System.out.println("\nInspecting table 2.");

                while (res1.next()) {
                    System.out.println("Column 1: "+res1.getInt(1));
                    System.out.println("Column 2: "+res1.getInt(2));
                }

                System.out.print("\nNow attempting to rollback changes.");

                txn.rollback();

                // Next, we try to commit changes
                txn.begin();
                stmtx = conn.createStatement();
                ResultSet res2 = null;

                System.out.println("\nNow checking state of table 1.");

                res2 = stmtx.executeQuery("SELECT * FROM test_table");

                while (res2.next()) {
                    System.out.println("Column 1: "+res2.getInt(1));
                    System.out.println("Column 2: "+res2.getInt(2));
                }

                System.out.println("\nNow checking state of table 2.");

                stmtx = conn.createStatement();

                res2 = stmtx.executeQuery("SELECT * FROM test_table2");

                while (res2.next()) {
                    System.out.println("Column 1: "+res2.getInt(1));
                    System.out.println("Column 2: "+res2.getInt(2));
                }

                txn.commit();
            }
            catch (Exception ex) {
                ex.printStackTrace();
                System.exit(0);
            }
        }
        catch (Exception sysEx) {
            sysEx.printStackTrace();
            System.exit(0);
        }
    }      
}

10.9.4. API Documentation for JBoss Transactions JTA

The API documentation for the Transaction subsystem of JBoss EAP 6 is available at the following location:
If you use JBoss Development Studio to develop your applications, the API documentation is included in the Help menu.

Chapter 11. Hibernate

11.1. About Hibernate Core

Hibernate Core is an object/relational mapping library. It provides the framework for mapping Java classes to database tables, allowing applications to avoid direct interaction with the database.

11.2. Java Persistence API (JPA)

11.2.1. About JPA

The Java Persistence API (JPA) is the standard for using persistence in Java projects. Java EE 6 applications use the Java Persistence 2.0 specification, documented here: http://www.jcp.org/en/jsr/detail?id=317.
Hibernate EntityManager implements the programming interfaces and life-cycle rules defined by the specification. It provides JBoss EAP 6 with a complete Java Persistence solution.
JBoss EAP 6 is 100% compliant with the Java Persistence 2.0 specification. Hibernate also provides additional features to the specification.
To get started with JPA and JBoss EAP 6, refer to the bean-validation, greeter, and kitchensink quickstarts: Section 1.4.2.1, “Access the Quickstarts”.

11.2.2. Hibernate EntityManager

Hibernate EntityManager implements the programming interfaces and life-cycle rules defined by the JPA 2.0 specification. It provides JBoss EAP 6 with a complete Java Persistence solution.
For more information about Java Persistence or Hibernate, refer to the Section 11.2.1, “About JPA” and Section 11.1, “About Hibernate Core”.

11.2.3. Getting Started

11.2.3.1. Create a JPA project in JBoss Developer Studio

Summary
This example covers the steps required to create a JPA project in JBoss Developer Studio.

Procedure 11.1. Create a JPA project in JBoss Developer Studio

  1. In the JBoss Developer Studio window, click FileNewJPA Project.
  2. In the project di