Red Hat 6 Development Guide JBoss Enterprise Application Platform Development Guide

Section 1.4.1.2, “Download JBoss Developer Studio 5”

Report a bug

1.4 .1.2. Download JBoss Developer Studio 5

1. Go to https://access.redhat.com/ .

2. Select Downloads → JBoss Enterprise Middleware → Downloads.

3. Select JBoss Developer Studio from the dropbox.

4. Select the appropriate version and click Download.

Report a bug

1.4 .1.3. Install JBoss Developer Studio 5

Prerequisites:

Procedure 1.2. Task:

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.

Chapter 1. Get Started Developing Applications

10. Click Next when the installation process is complete.

11. Configure the desktop shortcuts for JBoss Developer Studio, and click Next.

12. Click Done.

Report a bug

1.4 .1.4 . Start JBoss Developer Studio

Prerequisites:

Section 1.4.1.3, “Install JBoss Developer Studio 5”

Procedure 1.3. Task:

1. Open a terminal.

2. Change into the installation directory.

3. Run the following command to start the JBoss Developer Studio:

[localhost]$ ./jbdevstudio

Report a bug

1.4 .1.5. Add the JBoss Enterprise Application Platform 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 Enterprise Application Platform 6 servers.

Procedure 1.4 . Add the server

1. Open the Servers tab. If there is no Servers tab, add it to the panel as follows: a. Click Window → Show View → Other....

b. 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 New

→ Server.

JBoss Enterprise Application Platform 6 Development Guide

Figure 1.2. Add a new server - No servers available

3. Expand JBoss Enterprise Middleware and choose JBoss Enterprise Application

Platform 6.x.Then click Next.

Chapter 1. Get Started Developing Applications

Figure 1.3. Choose server type

4. Click Browse and navigate to your JBoss Enterprise Application Platform 6 install location. Then click Next.

JBoss Enterprise Application Platform 6 Development Guide

Figure 1.4 . 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.

Chapter 1. Get Started Developing Applications

Figure 1.5. Define the new JBoss server behavior

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

JBoss Enterprise Application Platform 6 Development Guide

Figure 1.6. Modify resources for the new JBoss server

Result

The JBoss Enterprise Application Server 6.0 Runtime Server is listed in the Servers tab.

Chapter 1. Get Started Developing Applications

Figure 1.7. Server appears in the server list

Report a bug

1.5. Run Your First Application

1.5.1. Replace the Default Welcome Web Application

JBoss Enterprise Application Platform 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.5. Task

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:writeattribute(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.xm l, which is located in the MET A-INF/ or WEB-INF/ directory. Replace its

<context-root> directive with one that looks like the following.

JBoss Enterprise Application Platform 6 Development Guide

<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/.

Report a bug

1.5.2. Download the Quickstart Code Examples

1.5.2.1. Access the Java EE Quickstart Examples

Summary

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

Prerequisites

Maven 3.0.0 or higher. For more information on installing Maven, refer to http://maven.apache.org/download.html

Section 2.1.1, “About the Maven Repository”

Section 2.2.3, “Install the JBoss Enterprise Application Platform 6 Maven Repository Locally”

Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven Repository Using the

Maven Settings”

Procedure 1.6. Download the Quickstarts

1. Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform .

2. Find "Application Platform 6 Quickstarts" in the list.

3. Click the Download button to download a .zip file containing the examples.

4. Unzip the archive in a directory of your choosing.

Result

The Java EE quickstart examples have been downloaded and unzipped. Refer to the README.md file in the jboss-eap-6.0-quickstarts/ directory for instructions about deploying each quickstart.

Report a bug

1.5.3. Run the Quickstarts

1.5.3.1. Run the Quickstarts in JBoss Developer Studio

Procedure 1.7. Import the quickstarts into JBoss Developer Studio

The quickstarts ship with a parent POM (Project Object Model) file that contains project and configuration information for all of the quickstarts in the distribution. Using this top-level POM file, you can easily import the entire list of quickstarts into JBoss Developer Studio at one time.

1. If you have not done so, Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven

Repository Using the Maven Settings” .

2. Start JBoss Developer Studio.

Chapter 1. Get Started Developing Applications

3. From the menu, select File → Import.

4. In the selection list, choose Maven → Existing Maven Projects, then click Next.

Figure 1.8. Import Existing Maven Projects

5. Browse to the root of the quickstart directory and click OK. The Projects list box will be populated with the list of the pom.xml files from all of the quickstart projects.

JBoss Enterprise Application Platform 6 Development Guide

Figure 1.9. Select Maven Projects

6. Click Next, then click Finish.

Procedure 1.8. 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: a. Click Window → Show View → Other....

b. Select Servers from the Server folder and click Ok.

2. Right click on helloworld in the Project Explorer tab, and select Run As → Run 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

Chapter 1. Get Started Developing Applications

Report a bug

1.5.3.2. Run the Quickstarts Using a Command Line

Procedure 1.9. 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.

Report a bug

1.5.4. Review the Quickstart Tutorials

1.5.4 .1. Explore the helloworld Quickstart

Summary

The helloworld quickstart shows you how to deploy a simple Servlet to JBoss Enterprise Application

Platform 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.10. 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.5.3.1, “Run the Quickstarts in JBoss Developer Studio” , you can skip to the next section.

1. If you have not done so, Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven

Repository Using the Maven Settings” .

2. If you have not done so,

Section 1.4.1.3, “Install JBoss Developer Studio 5”

JBoss Enterprise Application Platform 6 Development Guide

you must Section 1.4.1.5, “Add the JBoss Enterprise Application Platform 6 Server to JBoss

4. From the menu, select File → Import.

5. In the selection list, choose Maven → Existing Maven Projects, then click Next.

4 0

Figure 1.10. Import Existing Maven Projects

6. Browse to the QUICKSTART_HOME/quickstart/helloworld/ directory and click OK. The

Projects list box is populated with the pom .xm l file from the helloworld quickstart project.

Chapter 1. Get Started Developing Applications

Figure 1.11. Select Maven Projects

7. Click Finish.

Procedure 1.11. Build and Deploy the helloworld quickstart

1. If you have not yet configured JBoss Developer Studio for JBoss Enterprise Application Platform 6,

Developer Studio” .

2. Right click on jboss-as-helloworld in the Project Explorer tab, and select Run As →

Run on Server.

4 1

JBoss Enterprise Application Platform 6 Development Guide

Figure 1.12. 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.12. 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 Enterprise Application Platform 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/m ain/webapp/ directory of the example.

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

4 2

Chapter 1. Get Started Developing Applications

Procedure 1.13. 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/m ain/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.4 . 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/m ain/java/org/jboss/as/quickstarts/helloworld/ directory. This service is very simple. It returns a message. No XML or annotation registration is required.

public class HelloService {

10.

11.

String createHelloMessage (String name) {

12.

return "Hello " + name + "!" ;

32.

}

33.

}

34.

4 3

JBoss Enterprise Application Platform 6 Development Guide

Report a bug

1.5.4 .2. Explore the numberguess Quickstart

Summary

This quickstart shows you how to create and deploy a simple application to JBoss Enterprise Application

Platform 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

num berguess 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.14 . 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.5.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.4.1.3, “Install JBoss

Developer Studio 5”

you must do the following: Section 1.4.1.5, “Add the JBoss Enterprise Application Platform 6 Server to JBoss Developer Studio” .

3. From the menu, select File → Import.

4. In the selection list, choose Maven → Existing Maven Projects, then click Next.

4 4

Chapter 1. Get Started Developing Applications

Figure 1.13. Import Existing Maven Projects

5. Browse to the QUICKSTART_HOME/quickstart/numberguess/ directory and click OK. The

Projects list box is populated with the pom .xm l file from the num berguess quickstart project.

6. Click Finish.

Procedure 1.15. Build and Deploy the numberguess quickstart

1. If you have not yet configured JBoss Developer Studio for JBoss Enterprise Application Platform 6,

2. Right click on jboss-as-numberguess in the Project Explorer tab, and select Run As →

Run on Server.

3. Select the JBoss EAP 6.0 Runtime Server server and click Next. This deploys the

num berguess 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-asnumberguess

Procedure 1.16. Examine the Configuration Files

All the configuration files for this example are located in WEB-INF/ directory which can be found in the

src/m ain/webapp/ directory of the quickstart.

1. Examine the faces-config file

4 5

JBoss Enterprise Application Platform 6 Development Guide

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 Enterprise Application Platform 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 Enterprise Application Platform 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.17. 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.

4 6

Chapter 1. Get Started Developing Applications

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.

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.

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.

36.

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>

4 7

JBoss Enterprise Application Platform 6 Development Guide

Table 1.5. JSF Details

Line

20-24

29-32

38-42

43-45

Note

These are the messages which can be sent to the user: "Higher!" and "Lower!"

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.

This input field is bound to a bean property using a value expression.

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.

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.18. Examine the Class Files

All of the numberguess quickstart source files can be found in the

src/m ain/java/org/jboss/as/quickstarts/num berguess/ 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 8.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.

4 8

Chapter 1. Get Started Developing Applications

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}.

4 9

JBoss Enterprise Application Platform 6 Development Guide

035.

@Named

036.

@SessionScoped

037.

public class Game implements Serializable {

038.

039.

private static final long serialVersionUID = 991300443278089016 L;

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.

}

Chapter 1. Get Started Developing Applications

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.

}

JBoss Enterprise Application Platform 6 Development Guide

155.

}

156.

}

157.

}

Report a bug

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 Enterprise Application Platform 6 includes a

Maven repository that contains many of the requirements that Java EE developers typically use to build applications on JBoss Enterprise Application Platform 6. To configure your project to use this repository,

see Section 2.3.1, “Configure the JBoss Enterprise Application Platform 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”

Report a bug

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 .

Report a bug

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

JBoss Enterprise Application Platform 6 Development Guide 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:

<modelVersion> 4.0.0

</modelVersion>

<groupId> com.jboss.app

</groupId>

</project>

Report a bug

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.xm l files exist, the contents are merged. Where there are overlaps, the user's

settings.xm l file takes precedence.

The following is an example of a Maven settings.xml file:

Chapter 2. Maven Guide

<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" >

<id> jboss-eap-maven-repository </id>

<id> jboss-eap </id>

<url> file:///path/to/repo/jboss-eap-6.0-maven-repository </url>

</releases>

<enabled> false </enabled>

</snapshots>

</repository>

</repositories>

<id> jboss-eap-maven-plugin-repository </id>

<url> file:///path/to/repo/jboss-eap-6.0-maven-repository </url>

</releases>

<enabled> false </enabled>

</snapshots>

</pluginRepository>

</pluginRepositories>

</profile>

</profiles>

<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

Report a bug

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.

Report a bug

2.2.2. Install the JBoss Enterprise Application Platform 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.

JBoss Enterprise Application Platform 6 Development Guide

Section 2.2.3, “Install the JBoss Enterprise Application Platform 6 Maven Repository Locally”

Section 2.2.4, “Install the JBoss Enterprise Application Platform 6 Maven Repository for Use with

Apache httpd”

Section 2.2.5, “Install the JBoss Enterprise Application Platform 6 Maven Repository Using Nexus

Maven Repository Manager”

Report a bug

2.2.3. Install the JBoss Enterprise Application Platform 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 Enterprise

Application Platform 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. Task

1. Download the JBoss Enterprise Application Platform 6 Maven Repository ZIP archive

Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform .

2. Find "Application Platform 6 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.

Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven Repository Using the

Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven Repository Using the

Result

This creates a Maven repository directory called jboss-eap-6.0.0.maven-repository.

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.

Report a bug

2.2.4. Install the JBoss Enterprise Application Platform 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 Enterprise

Application Platform 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 Enterprise Application Platform 6 Maven Repository ZIP

Chapter 2. Maven Guide

archive

1. Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform .

2. Find "Application Platform 6 Maven Repository" in the list.

3. Click the Download button to download a .zip file containing the repository.

4. Unzip the files in a directory that is web accessible on the Apache server.

5. Configure Apache to allow read access and directory browsing in the created directory.

information about Maven repository managers, see Section 2.2.6, “About Maven Repository Managers”

Result

This allows a multi-user environment to access the Maven repository on Apache httpd.

Report a bug

2.2.5. Install the JBoss Enterprise Application Platform 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

This example will cover the steps to install the JBoss Enterprise Application Platform 6 Maven

Repository using Sonatype Nexus Maven Repository Manager. For more complete instructions, see

Sonatype Nexus: Manage Artifacts .

Procedure 2.3. Download the JBoss Enterprise Application Platform 6 Maven Repository ZIP archive

1. Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform .

2. Find "Application Platform 6 Maven Repository" in the list.

3. Click the Download button to download a .zip file containing the repository.

4. Unzip the files into a directory of your choosing.

Procedure 2.4 . Add the JBoss Enterprise Application Platform 6 Maven Repository using

Nexus Maven Repository Manager

1. Log into Nexus as an Administrator.

2. Select the Repositories section from the Views → Repositories 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.

JBoss Enterprise Application Platform 6 Development Guide

Note

Note that the order of this list determines the priority for searching Maven artifacts.

10.

Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven Repository Using the

Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven Repository Using the

Result

The repository is configured using Nexus Maven Repository Manager.

Report a bug

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.

Report a bug

2.3. Configure the Maven Repository

2.3.1. Configure the JBoss Enterprise Application Platform Maven Repository

Overview

There are two approaches to direct Maven to use the JBoss Enterprise Application Platform 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.

Chapter 2. Maven Guide

Procedure 2.5. Configure Maven Settings to Use the JBoss Enterprise Application Platform

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

Using Mirrors for Repositories .

This method of configuration applies across all Maven projects, as long as the project POM file does not contain repository configuration.

Section 2.3.3, “Configure the JBoss Enterprise Application Platform Maven Repository Using the

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. See Why Putting Repositories in your POMs is a Bad Idea for a complete explanation of the possible consequences of this approach.

This method of configuration overrides the global and user Maven settings for the configured project.

Project POM” .

Report a bug

2.3.2. Configure the JBoss Enterprise Application Platform Maven Repository

Using the Maven Settings

There are two approaches to direct Maven to use the JBoss Enterprise Application Platform 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 Enterprise Application Platform Maven

Repository across all projects using the Maven global or user settings. This is the recommended approach.

JBoss Enterprise Application Platform 6 Development Guide

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 Maven chapter of the

Development Guide for JBoss Enterprise Application Platform 6. The following are examples for each of the installation options:

File System file:///path/to/repo/jboss-eap-6.0.0-m aven-repository

Apache Web Server http://intranet.acm e.com /jboss-eap-6.0.0-m aven-repository/

Nexus Repository Manager

https://intranet.acm e.com /nexus/content/repositories/jboss-eap-

6.0.0-m aven-repository

You can configure Maven to use the JBoss Enterprise Application Platform 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 Maven chapter of the Development Guide for JBoss Enterprise Application

Platform 6. .

To use the JBoss Enterprise Application Platform 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.

A. Global Settings

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

B. User Settings

If you are configuring user specific settings and you do not yet have a

USER_HOME/.m 2/settings.xm l file, copy the settings.xm l 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.

Chapter 2. Maven Guide

<id> jboss-eap-repository </id>

<id> jboss-eap-repository </id>

<name> JBoss EAP Maven Repository </name>

<url> file:///path/to/repo/jboss-eap-6.0.0-maven-repository </url>

<layout> default </layout>

<updatePolicy> never </updatePolicy>

</releases>

<enabled> false </enabled>

<updatePolicy> never </updatePolicy>

</snapshots>

</repository>

</repositories>

<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>

<updatePolicy> never </updatePolicy>

</releases>

<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 Window → Preferences. 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.

JBoss Enterprise Application Platform 6 Development Guide

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

Chapter 2. Maven Guide

The JBoss Enterprise Application Platform repository has now been configured.

Report a bug

2.3.3. Configure the JBoss Enterprise Application Platform Maven Repository

Using the Project POM

There are two approaches to direct Maven to use the JBoss Enterprise Application Platform 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 Enterprise Application Platform

Maven Repository by adding repository information to the project pom.xml. This configuration method supercedes and overrides the global and user settings configurations.

POMs is a Bad Idea for a complete explanation of the possible consequences of this 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, see: Section 2.2.2, “Install the JBoss

Enterprise Application Platform 6 Maven Repository” . The following are examples for each of the

installation options:

File System file:///path/to/repo/jboss-eap-6.0.0-m aven-repository

Apache Web Server http://intranet.acm e.com /jboss-eap-6.0.0-m aven-repository/

Nexus Repository Manager

https://intranet.acm e.com /nexus/content/repositories/jboss-eap-

6.0.0-m aven-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.

JBoss Enterprise Application Platform 6 Development Guide

<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>

<updatePolicy> never </updatePolicy>

</releases>

<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.

<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>

</snapshots>

</pluginRepository>

</pluginRepositories>

Report a bug

Chapter 3. Class Loading and Modules

3.1. Introduction

3.1.1. Overview of Class Loading and Modules

The following material covers what developers need to know to successfull build and deploy applications on JBoss Enterprise Application Platform 6.

Report a bug

3.1.2. Class Loading

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

Environment.

Report a bug

3.1.3. Modules

A Module is a logical grouping of classes used for class loading and dependency management. JBoss

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.

Dynamic Modules

JBoss Enterprise Application Platform 6 Development Guide

Modules are only loaded when required. This usually only occurs when an application is deployed that has explicit or implicit dependencies.

Report a bug

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 Enterprise Application Platform 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 metadata are found in a deployment. The Java EE 6 APIs supplied with JBoss Enterprise Application Platform 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.1. 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.

Report a bug

3.1.5. Class Loading in Deployments

For the purposes of classloading all deployments are treated as modules by JBoss Enterprise

Application Platform. These are called dynamic modules. Class loading behavior varies according to the deployment type.

WAR Deployment

Chapter 3. Class Loading and Modules

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.

Report a bug

3.1.6. Class Loading Precedence

The JBoss Enterprise Application Platform 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 Enterprise Application

Platform 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

Enterprise Application Platform 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-deploym ent-structure.xm l 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.

JBoss Enterprise Application Platform 6 Development Guide

Report a bug

3.1.7. Dynamic Module Naming

All deployments are loaded as modules by JBoss Enterprise Application Platform 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

deploym ent.inventory.war and deploym ent.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.accounting.ear.reports.war.

Report a bug

3.1.8. jboss-deployment-structure.xml

jboss-deploym ent-structure.xm l is a new optional deployment descriptor for JBoss Enterprise

Application Platform 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

Report a bug

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 Enterprise Application Platform 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 Enterprise Application

Platform. 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.

Chapter 3. Class Loading and Modules

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-deploym ent-structure.xm l 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.

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.

5. Optional: Export a dependency

A dependency can be exported by adding the export attribute to the module entry with the value

JBoss Enterprise Application Platform 6 Development Guide of TRUE. The default value for this attribute is FALSE.

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

<jboss-deployment-structure>

</dependencies>

</deployment>

</jboss-deployment-structure>

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

Report a bug

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,

m aven-ejb-plugin, m aven-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 Enterprise Application Platform 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.

</manifestEntries>

</archive>

</configuration>

2. List Dependencies

Add the list of the module dependencies in the <Dependencies> element. Use the same format

Chapter 3. Class Loading and Modules

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.3. 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 (mavenjar-plugin and maven-ejb-plugin).

<groupId> org.apache.maven.plugins

</groupId>

<artifactId> maven-war-plugin </artifactId>

<Dependencies> org.javassist, org.apache.velocity

</Dependencies>

</manifestEntries>

</archive>

</configuration>

</plugin>

</plugins>

Report a bug

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-deploym ent-structure.xm l and add it to the project. This file is an XML file with the root element of <jboss-deployment-structure>.

JBoss Enterprise Application Platform 6 Development Guide

<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.

</exclusions>

</deployment>

3. Within the exclusions element, add a <module> element for each module to be excluded. Set the

nam e attribute to the name of the module.

Example 3.4 . Excluding two modules

<jboss-deployment-structure>

</exclusions>

</deployment>

</jboss-deployment-structure>

Report a bug

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>

</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

Chapter 3. Class Loading and Modules longer run on the deployment.

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

<jboss-deployment-structure>

<ear-subdeployments-isolated>true</ear-subdeployments-isolated>

<exclude-subsystems>

</exclude-subsystems>

</exclusions>

</dependencies>

<resource-root path="my-library.jar" />

</resources>

</deployment>

<sub-deployment name="myapp.war">

</dependencies>

<local-last value="true" />

</sub-deployment>

<resource-root path="javassist.jar" >

</filter>

</resource-root>

</resources>

</module>

</imports>

</module>

</dependencies>

</module>

</jboss-deployment-structure>

Report a bug

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.

JBoss Enterprise Application Platform 6 Development Guide

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 Enterprise Application Platform 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.

Report a bug

3.6.2. Subdeployment Class Loader Isolation

Each subdeployment in an Enterprise Archive (EAR) is an dynamic module with its own class loader and cannot access the resources of other subdeployments. This is called subdeployment class loader isolation.

JBoss Enterprise Application Platform 6 has strict subdeployment class loader isolation disabled by default. It can be enabled if required.

Report a bug

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:

Chapter 3. Class Loading and Modules

<jboss-deployment-structure>

</jboss-deployment-structure>

2. Add the <ear-subdeployments-isolated> element

Add the <ear-subdeployments-isolated> element to the jboss-deployment-

structure.xm l 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.

Report a bug

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.

JBoss Enterprise Application Platform 6 Development Guide

Table 3.1. Implicit Module Dependencies

Subsyste m

Core

Server

Modules Always added javax.api

sun.jdk

Subsystem

EJB3 subsystem

javaee.api

Modules Conditional added

Conditions

JAX-RS

(Resteasy) subsystem

JCA subsystem

javax.xm l.bind

.api

javax.resource

.api

javaee.api

org.jboss.rest

easy.resteasyatom -provider org.jboss.rest

easy.resteasycdi org.jboss.rest

easy.resteasyjaxrs org.jboss.rest

easy.resteasyjaxb-provider org.jboss.rest

easy.resteasyjacksonprovider org.jboss.rest

easy.resteasyjsapi org.jboss.rest

easy.resteasym ultipartprovider org.jboss.rest

easy.asynchttp-servlet-30

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)

The presence of JAX-RS annotations in the deployment

If the deployment is a resource adaptor (RAR) deployment.

javax.jm s.api

javax.validati

on.api

org.jboss.logg

ing org.jboss.iron

jacam ar.api

org.jboss.iron

Chapter 3. Class Loading and Modules

JPA

(Hibernate

) subsystem

SAR

Subsystem

javax.persiste

nce.api

jacam ar.im pl org.hibernate.

validator javaee.api

org.jboss.as.j

pa org.hibernate

org.javassist

org.jboss.logg

ing org.jboss.m odu les

The presence of an

@ PersistenceUnit or

@ PersistenceContext

annotation, or a <persistence-

unit-ref> or <persistence-

context-ref> in a deployment descriptor.

The deployment is a SAR archive

Security

Subsystem

Web

Subsystem

Web

Services

Subsystem

org.picketbox

org.jboss.ws.ap

i org.jboss.ws.sp

javaee.api

com .sun.jsfim pl org.hibernate.

validator org.jboss.as.we

b org.jboss.logg

ing

The deployment is a WAR archive.

JavaServer Faces(JSF) is only added if used.

Weld (CDI)

Subsystem

javax.persiste

nce.api

javaee.api

org.javassist

org.jboss.inte

rceptor org.jboss.as.we

ld org.jboss.logg

ing org.jboss.weld

.core

org.jboss.weld

.api

org.jboss.weld

.spi

If a beans.xml file is detected in the deployment

JBoss Enterprise Application Platform 6 Development Guide

Report a bug

3.7.2. Included Modules

asm .asm

ch.qos.cal10n

com .google.guava

com .h2database.h2

com .sun.jsf-im pl com .sun.jsf-im pl com .sun.xm l.bind

com .sun.xm l.m essaging.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.inject.api

javax.interceptor.api

javax.jm s.api

javax.jws.api

javax.m ail.api

javax.m anagem ent.j2ee.api

javax.persistence.api

javax.resource.api

javax.rm i.api

javax.security.auth.m essage.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.wsdl4 j.api

javax.xm l.bind.api

javax.xm l.jaxp-provider javax.xm l.registry.api

javax.xm l.rpc.api

javax.xm l.soap.api

javax.xm l.stream .api

javax.xm l.ws.api

jline net.sourceforge.cssparser

net.sourceforge.htm lunit net.sourceforge.nekohtm l nu.xom

org.antlr

org.apache.ant

org.apache.com m ons.beanutils

org.apache.com m ons.cli

org.apache.com m ons.codec

org.apache.com m ons.collections

org.apache.com m ons.io

org.apache.com m ons.lang

org.apache.com m ons.logging

org.apache.com m ons.pool

org.apache.cxf

org.apache.httpcom ponents org.apache.jam es.m im e4 j org.apache.log4 j org.apache.neethi

org.apache.santuario.xm lsec org.apache.velocity

org.apache.ws.scout

org.apache.ws.security

org.apache.ws.xm lschem a org.apache.xalan

org.apache.xerces

org.apache.xm l-resolver org.codehaus.jackson.jackson-core-asl org.codehaus.jackson.jackson-jaxrs org.codehaus.jackson.jackson-m apper-asl org.codehaus.jackson.jackson-xc org.codehaus.woodstox

org.dom 4 j org.hibernate

org.hibernate.envers

org.hibernate.infinispan

org.hibernate.validator

org.hornetq

org.hornetq.ra

org.infinispan

org.infinispan.cachestore.jdbc

Chapter 3. Class Loading and Modules

JBoss Enterprise Application Platform 6 Development Guide

org.infinispan.cachestore.rem ote 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.com m on org.jboss.as.clustering.ejb3.infinispan

org.jboss.as.clustering.im pl 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.cm p org.jboss.as.connector

org.jboss.as.console

org.jboss.as.controller

org.jboss.as.controller-client org.jboss.as.deploym ent-repository org.jboss.as.deploym ent-scanner org.jboss.as.dom ain-add-user org.jboss.as.dom ain-http-error-context org.jboss.as.dom ain-http-interface org.jboss.as.dom ain-m anagem ent org.jboss.as.ee

org.jboss.as.ee.deploym ent org.jboss.as.ejb3

org.jboss.as.em bedded org.jboss.as.host-controller org.jboss.as.jacorb

org.jboss.as.jaxr

org.jboss.as.jaxrs

org.jboss.as.jdr

org.jboss.as.jm x org.jboss.as.jpa

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.m ail org.jboss.as.m anagem ent-client-content org.jboss.as.m essaging org.jboss.as.m odcluster org.jboss.as.nam ing org.jboss.as.network

org.jboss.as.osgi

org.jboss.as.platform -m bean org.jboss.as.pojo

org.jboss.as.process-controller org.jboss.as.protocol

org.jboss.as.rem oting 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.com m on-core org.jboss.dm r 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.ironjacam ar.api

org.jboss.ironjacam ar.im pl org.jboss.ironjacam ar.jdbcadapters

org.jboss.jandex

org.jboss.jaxbintros

org.jboss.jboss-transaction-spi org.jboss.jsfunit.core

Chapter 3. Class Loading and Modules

JBoss Enterprise Application Platform 6 Development Guide

org.jboss.jts

org.jboss.jts.integration

org.jboss.logging

org.jboss.logm anager org.jboss.logm anager.log4 j org.jboss.m arshalling org.jboss.m arshalling.river

org.jboss.m etadata org.jboss.m odules org.jboss.m sc org.jboss.netty

org.jboss.osgi.deploym ent org.jboss.osgi.fram ework org.jboss.osgi.resolver

org.jboss.osgi.spi

org.jboss.osgi.vfs

org.jboss.rem oting3 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-m ultipart-provider org.jboss.sasl

org.jboss.security.negotiation

org.jboss.security.xacm l org.jboss.shrinkwrap.core

org.jboss.staxm apper 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.com m on 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

Chapter 3. Class Loading and Modules

org.jboss.ws.native.jbossws-native-services org.jboss.ws.saaj-im pl org.jboss.ws.spi

org.jboss.ws.tools.com m on org.jboss.ws.tools.wsconsum e org.jboss.ws.tools.wsprovide

org.jboss.xb

org.jboss.xnio

org.jboss.xnio.nio

org.jboss.xts

org.jdom

org.jgroups

org.joda.tim e org.junit

org.om g.api

org.osgi.core

org.picketbox

org.picketlink

org.python.jython.standalone

org.scannotation.scannotation

org.slf4 j org.slf4 j.ext

org.slf4 j.im pl org.slf4 j.jcl-over-slf4 j org.w3c.css.sac

sun.jdk

Report a bug

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.

Report a bug

JBoss Enterprise Application Platform 6 Development Guide

Chapter 4. Logging for Developers

4.1. Introduction

4.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.

Report a bug

4.1.2. Application Logging Frameworks Supported By JBoss LogManager

JBoss LogManager supports the following logging frameworks:

JBoss Logging - included with JBoss Enterprise Application Platform 6

Apache Commons Logging - http://commons.apache.org/logging/

Simple Logging Facade for Java (SLF4J) - http://www.slf4j.org/

Apache log4j - http://logging.apache.org/log4j/1.2/

Java SE Logging (java.util.logging) http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html

Report a bug

4.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 Enterprise Application Platform 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 FAT AL.

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 FAT AL.

Report a bug

4.1.4. Supported Log Levels

Chapter 4. Logging for Developers

Table 4 .1. Supported Log Levels

Log Level Value

FINEST

FINER

TRACE

300

400

DEBUG

FINE

CONFIG

INFO

WARN

WARNING

ERROR

FATAL

500

700

800

900

1000

1100

Description

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.

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.

Use for messages that indicate the overall progress of the application. Often used for application startup, shutdown and other major lifecycle events.

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.

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.

Use to indicate events that could cause critical service failure and application shutdown and possibly cause JBoss Enterprise Application Platform 6 to shutdown.

Report a bug

4.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 4 .2. Default Log Files for a standalone server

Log File

EAP_HOME/standalone/log/boot.log

EAP_HOME/standalone/log/server.log

Description

The server boot log. Contains log messages related to the startup of the server.

The Server Log. Contains all log messages once the server has launched.

JBoss Enterprise Application Platform 6 Development Guide

Table 4 .3. Default Log Files for a managed domain

Log File

EAP_HOME/dom ain/log/hostcontroller/boot.log

EAP_HOME/dom ain/log/processcontroller/boot.log

EAP_HOME/dom ain/servers/SERVERNAME/lo g/boot.log

EAP_HOME/dom ain/servers/SERVERNAME/lo g/server.log

Description

Host Controller boot log.Contains log messages related to the startup of the host controller.

Process controller boot log. Contains log messages related to the startup of the process controller.

Server Boot log for the named server. Contains log messages related to the startup of the specified server.

The server log for the named server. Contains all log messages for that server once it has launched.

Report a bug

4.2. Logging with the JBoss Logging Framework

4.2.1. About JBoss Logging

JBoss Logging is the application logging framework that is included in JBoss Enterprise Application

Platform 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.

Report a bug

4.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.

Report a bug

4.2.3. Add Logging to an Application with JBoss Logging

To log messages from your application you create a Logger object

(org.jboss.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 Enterprise Application

Platform 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

Chapter 4. Logging for Developers 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 Enterprise Application Platform 6 is checked.

When building using Maven this can be done by adding the following dependency configuration to your project's pom.xml file.

<groupId> org.jboss.logging

</groupId>

<artifactId> jboss-logging </artifactId>

<version> 3.0.0.CR1

</version>

<scope> provided </scope>

</dependency>

You do not need to include the JARs in your built application because JBoss Enterprise Application

Platform 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.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 m essage) info(Object m essage) error(Object m essage) trace(Object m essage) fatal(Object m essage)

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 JBoss Logging Javadoc at http://docs.jboss.org/jbosslogging/latest/ .

JBoss Enterprise Application Platform 6 Development Guide

Example 4 .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.jboss-logging.Logger; public class LocalSystemConfig

{ private static final Logger LOGGER =

Logger.

getLogger (LocalSystemConfig.

class ); public Properties openCustomProperties (String configname)

{

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;

}

Report a bug

Chapter 5. Internationalization and Localization

5.1. Introduction

5.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.

Report a bug

5.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.

Report a bug

5.2. JBoss Logging Tools

5.2.1. Overview

5.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.

Report a bug

5.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.

JBoss Enterprise Application Platform 6 Development Guide

Report a bug

5.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.

Report a bug

5.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.

Report a bug

5.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.

Report a bug

5.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.

Report a bug

5.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.

Report a bug

5.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.

Report a bug

5.2.1.9. JBoss Logging Tools Project Codes

Project codes are strings of characters that identify groups of messages. They are displayed at the

Chapter 5. Internationalization and Localization beginning of each log message, prepended to the message Id. Project codes are defined with the

projectCode attribute of the @ MessageLogger annotation.

Report a bug

5.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.

Report a bug

5.2.2. Creating Internationalized Loggers, Messages and Exceptions

5.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 5.2.6.1, “JBoss Logging Tools

Maven Configuration” .

2. The project must have the required maven configuration for JBoss Logging Tools.

Procedure 5.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 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:

JBoss Enterprise Application Platform 6 Development Guide

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 noninternationalized messages.

AccountsLogger.

LOGGER .

error ( "Invalid query syntax." );

RESULT: the project now supports one or more internationalized loggers that can now be localized.

Report a bug

5.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 Enterprise Application Platform 6 repository.

Refer to Section 2.3.2, “Configure the JBoss Enterprise Application Platform Maven Repository

Using the Maven Settings” .

2. The required Maven configuration for JBoss Logging Tools has been added. Refer to

Section 5.2.6.1, “JBoss Logging Tools Maven Configuration”

Procedure 5.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.

Chapter 5. Internationalization and Localization

@MessageBundle 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.

Report a bug

5.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-qs 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 5.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 5.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 public interface ExceptionBundle

{

ExceptionBundle EXCEPTIONS = Messages.

getBundle (ExceptionBundle.

class );

}

JBoss Enterprise Application Platform 6 Development Guide

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.

Report a bug

5.2.3. Localizing Internationalized Loggers, Messages and Exceptions

5.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-qs 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.

Procedure 5.4 . Generate New Translation Properties Files with Maven

Chapter 5. Internationalization and Localization

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.

<groupId> org.apache.maven.plugins

</groupId>

<artifactId> maven-compiler-plugin </artifactId>

<version> 2.3.2

</version>

<source> 1.6

</source>

<target> 1.6

</target>

-AgeneratedTranslationFilesPath=${project.basedir}/target/generatedtranslation-files

</compilerArgument>

</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.

Report a bug

5.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 5.5. Translate an internationalized logger, exception or message

1. Generate the template properties files

JBoss Enterprise Application Platform 6 Development Guide

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/.

Report a bug

5.2.4. Customizing Internationalized Log Messages

5.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 5.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 5.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

{

}

Chapter 5. Internationalization and Localization

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.

Report a bug

5.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 5.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, FAT AL, INFO, T RACE, 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.

Report a bug

5.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 5.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.

JBoss Enterprise Application Platform 6 Development Guide

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 third 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 5.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 5.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);

Report a bug

5.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 5.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.

Chapter 5. Internationalization and Localization 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)

Report a bug

5.2.5. Customizing Internationalized Exceptions

5.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 5.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 5.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.

JBoss Enterprise Application Platform 6 Development Guide

@ 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 5.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)

Report a bug

5.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.

100

Chapter 5. Internationalization and Localization

Procedure 5.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 explicit indexes, insert the characters %{#} in the message where #is the number of the parameter you want to appear.

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 5.4 . Using ordinary indexes

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

IOException configFileAccessError (File config);

Example 5.5. Using explicit indexes

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

IOException configFileAccessError (File config);

Report a bug

5.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 5.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.

101

JBoss Enterprise Application Platform 6 Development Guide

@ 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" );

}

102

Chapter 5. Internationalization and Localization

Example 5.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

Report a bug

5.2.6. Reference

5.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 jboss-logging-tool-qs 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 Enterprise Application Platform 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 Enterprise Application Platform 6 so the scope element of each can be set to provided as shown.

103

JBoss Enterprise Application Platform 6 Development Guide

<groupId> org.jboss.logging

</groupId>

<artifactId> jboss-logging-processor </artifactId>

<version> 1.0.0.Final

</version>

<scope> provided </scope>

</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.

<groupId> org.apache.maven.plugins

</groupId>

<artifactId> maven-compiler-plugin </artifactId>

<version> 2.3.2

</version>

<source> 1.6

</source>

<target> 1.6

</target>

</configuration>

</plugin>

Report a bug

5.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

InterfaceNam e is the name of the interface that the translations apply to.

locale, COUNT RY, and VARIANT identify the regional settings that the translation applies to.

locale and COUNT RY 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.

104

Chapter 5. Internationalization and Localization

Example 5.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é.

Report a bug

5.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 5.1. JBoss Logging Tools Annotations

Annotation

@ MessageBun dle

@ MessageLog ger

@ Message

Target

Interface

Method

@ LogMessage Method

@ Cause

@ Param

Parameter

Description

Defines the interface as a Message Bundle.

Defines the interface as a Message Logger.

Attributes projectCod e projectCod e

value, id

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.

Defines a method in a Message Logger as being a method that is a logging method.

Defines a parameter as being one that passes an Exception as the cause of either a Log message or another Exception.

Defines a parameter as being one that is passed to the constructor of the Exception.

level (default

INFO)

Report a bug

105

JBoss Enterprise Application Platform 6 Development Guide

Chapter 6. Enterprise JavaBeans

6.1. Introduction

6.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 Enterprise Application Platform 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 .

Report a bug

6.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)

Report a bug

6.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

106

Chapter 6. Enterprise JavaBeans

2. allowing EJBs to be deployed in the same WAR file as a web-application.

Report a bug

6.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

Report a bug

6.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.

Report a bug

6.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.

107

JBoss Enterprise Application Platform 6 Development Guide

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.

Report a bug

6.1.7. Session Bean Business Interfaces

6.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.

Report a bug

6.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.

Report a bug

6.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.

Report a bug

6.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.

Report a bug

6.2. Creating Enterprise Bean Projects

6.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.

108

Chapter 6. Enterprise JavaBeans

Task Prerequisites:

A server and server runtime for JBoss Enterprise Application Platform 6 has been set up.

Procedure 6.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.

Figure 6.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.

109

JBoss Enterprise Application Platform 6 Development Guide

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

Enterprise Application Platform 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.

Figure 6.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".

110

Chapter 6. Enterprise JavaBeans

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.

Figure 6.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.

Report a bug

6.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 6.2. Create an EJB Archive project in Maven

111

JBoss Enterprise Application Platform 6 Development Guide

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=ejbjavaee6

[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.

112

Chapter 6. Enterprise JavaBeans

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.

Report a bug

6.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.

Task Prerequisites:

A server and server runtime for JBoss Enterprise Application Platform 6 has been set up. Refer to

Section 1.4.1.5, “Add the JBoss Enterprise Application Platform 6 Server to JBoss Developer Studio”

Procedure 6.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.

Figure 6.4 . New EAR Application Project Wizard

113

JBoss Enterprise Application Platform 6 Development Guide

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

Enterprise Application Platform 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: a. 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.

b. 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 6.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.

114

Chapter 6. Enterprise JavaBeans

Figure 6.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.

Report a bug

6.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 6.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.

115

JBoss Enterprise Application Platform 6 Development Guide

Figure 6.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.

Report a bug

6.3. Session Beans

6.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.

Report a bug

6.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.

Report a bug

6.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.

Report a bug

116

Chapter 6. Enterprise JavaBeans

6.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.

Report a bug

6.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 6.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).

117

JBoss Enterprise Application Platform 6 Development Guide

Figure 6.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

118

Chapter 6. Enterprise JavaBeans 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.

Figure 6.8. New Session Bean in JBoss Developer Studio

Report a bug

6.4. Message-Driven Beans

6.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.

Report a bug

119

JBoss Enterprise Application Platform 6 Development Guide

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 Systems 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 Enterprise Application Platform 6. A RAR file may also be included in an Enterprise Archive (EAR) deployment.

Report a bug

6.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 Enterprise Application

Platform configuration to which this bean will be deployed.

Procedure 6.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 File → New → Other. Select EJB/Message-Driven Bean (EJB 3.x) and click the

Next button.

120

Chapter 6. Enterprise JavaBeans

Figure 6.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 nam e. 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

121

JBoss Enterprise Application Platform 6 Development Guide

The default values here are suitable for a JMS-based Message-Driven bean using Containermanaged 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.

Report a bug

6.5. Invoking Session Beans

6.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 remote-ejb quick start contains working Maven projects that demonstrate this functionality. The quick start 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 Enterprise Application Platform 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 6.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/resources/ directory of your project with the following content.

122

Chapter 6. Enterprise JavaBeans

# Set this to true for SSL remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false remote.connections=default

# Uncomment this for SSL

# remote.connection.default.connect.options.org.xnio.Options.SSL_STARTTLS=true remote.connection.default.host=localhost remote.connection.default.port = 4447 remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONY

MOUS=false

# Add other SASL options if required

# remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONY

MOUS=false

# remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOPLAIN

TEXT=false

# remote.connection.default.connect.options.org.xnio.Options.SASL_DISALLOWED_MEC

HANISMS=JBOSS-LOCAL-USER

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.

<groupId>org.

jboss .

as .

quickstarts </groupId>

<artifactId>jboss-as-ejb-remote-server-side</artifactId>

<type>ejb-client</type>

<version> 7.1

CR1-SNAPSHOT</version>

</dependency>

Now that the project has been configured correctly, you can add the code to access and invoke the session beans.

Procedure 6.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 remote-ejb 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

123

JBoss Enterprise Application Platform 6 Development Guide interface that contains the methods you want to invoke.

final RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.

lookup (

"ejb:/jboss-as-ejb-remote-app/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.

Report a bug

6.6. Clustered Enterprise JavaBeans

6.6.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 7.4, “Implement an HA Singleton”

Note

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

Report a bug

6.7. Reference

6.7.1. EJB JNDI Naming Reference

The JNDI lookup name for a session bean has the syntax of:

ejb:<appName>/<moduleName>/<distinctName>/<beanName>!<viewClassName>?stateful

<appNam e>

124

Chapter 6. Enterprise JavaBeans

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.

<m oduleNam e>

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.

<distinctNam e>

JBoss Enterprise Application Platform 6 allows each deployment to specify an optional distinct name. If the deployment does not have a distinct name then leave this blank.

<beanNam e>

The bean name is the classname of the session bean to be invoked.

<viewClassNam e>

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.

Report a bug

6.7.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.

125

JBoss Enterprise Application Platform 6 Development Guide

@ EJB.beanNam e() corresponds to <ejb-link>. If the beanNam e() 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.

Report a bug

6.7.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 Enterprise Application Platform 6 Maven repository.

Table 6.1. Maven dependencies for Remote EJB Clients

GroupID

org.jboss.spec

org.jboss.as

org.jboss.spec.javax.transaction

org.jboss.spec.javax.ejb

org.jboss

org.jboss.xnio

org.jboss.remoting3

org.jboss.sasl

org.jboss.marshalling

ArtifactID

jboss-javaee-6.0

jboss-as-ejb-client-bom jboss-transaction-api_1.1_spec

jboss-ejb-api_3.1_spec

jboss-ejb-client xnio-api xnio-nio jboss-remoting jboss-sasl jboss-marshalling-river

Version

3.0.0.Final-redhat-

7.1.1.Final-redhat-

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

<dependencyManagem ent> section of your pom .xm l with the scope of im port.

<groupId> org.jboss.spec

</groupId>

<artifactId> jboss-javaee-6.0

</artifactId>

<version> 3.0.0.Final-redhat-1 </version>

<scope> import </scope>

</dependency>

<groupId> org.jboss.as

</groupId>

<artifactId> jboss-as-ejb-client-bom </artifactId>

<version> 7.1.1.Final-redhat-1 </version>

<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.

126

Chapter 6. Enterprise JavaBeans

Report a bug

6.7.4. jboss-ejb3.xml Deployment Descriptor Reference

jboss-ejb3.xm l 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.xm l, with the jboss-ejb3.xm l 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-nam e.

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.

127

JBoss Enterprise Application Platform 6 Development Guide

<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>

128

Chapter 6. Enterprise JavaBeans

Example 6.1. Example jboss-ejb3.xml file

<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/ejbjar_3_1.xsd"

version= "3.1"

impl-version= "2.0" >

<enterprise-beans>

<message-driven>

<ejb-name> ReplyingMDB </ejb-name>

<ejbclass> org.jboss.as.test.integration.ejb.mdb.messagedestination.ReplyingMDB

</ejbclass>

<activation-config>

<activation-config-property>

<activation-config-property-name> destination </activationconfig-property-name>

<activation-config-propertyvalue> 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>

Report a bug

129

JBoss Enterprise Application Platform 6 Development Guide

Chapter 7. Clustering in Web Applications

7.1. Session Replication

7.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.

Report a bug

7.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.xm l 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.

Report a bug

7.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 7.1. Configure the Web Session Cache

1. Change the default cache mode to DIST.

/profile=ha/subsystem=infinispan/cache-container=web/:writeattribute(name=default-cache,value=dist)

2. Set the number of owners for a distributed cache.

130

Chapter 7. Clustering in Web Applications

The following command sets 5 owners. The default is 2.

/profile=ha/subsystem=infinispan/cache-container=web/distributedcache=dist/:write-attribute(name=owners,value=5)

3. Change the default cache mode back to REPL.

/profile=ha/subsystem=infinispan/cache-container=web/:writeattribute(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 7.1.4, “Enable Session Replication in Your Application”

Report a bug

7.1.4. Enable Session Replication in Your Application

Overview

To take advantage of the JBoss Enterprise Application Platform's High Availability (HA) features, 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 7.2. Task

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.xm l discriptor file. Here is an example.

Example 7.1. Minimum Configuration for a Distributable Application

<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/webapp_2_4.xsd"

version= "2.4" >

</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.

131

JBoss Enterprise Application Platform 6 Development Guide

Example 7.2. Default <replication-config>Values

<jboss-web>

<replication-config>

<cache-name> custom-session-cache </cache-name>

<replication-trigger> SET </replication-trigger>

<replication-granularity> ATTRIBUTE </replication-granularity>

<replication-field-batch-mode> true </replication-field-batch-mode>

<use-jk> false </use-jk>

<max-unreplicated-interval> 30 </max-unreplicated-interval>

<snapshot-mode> INSTANT </snapshot-mode>

<snapshot-interval> 1000 </snapshot-interval>

<session-notificationpolicy> com.example.CustomSessionNotificationPolicy

</session-notificationpolicy>

</replication-config>

</jboss-web>

132

Chapter 7. Clustering in Web Applications

Table 7.1. Common Options for session Replication

Option

<replication-trigger>

Description

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.

<replicationgranularity>

Regardless of the setting, you can always trigger session replication by calling setAttribute().

Determines the granularity of data that is replicated. It defaults to

SESSION, but can be set to AT T RIBUT E instead, to increase performance on sessions where most attributes remain unchanged.

The following options rarely need to be changed.

133

JBoss Enterprise Application Platform 6 Development Guide

Table 7.2. Less Commonly Changed Options for Session Replication

Option

<useJK>

<m ax-unreplicatedinterval>

<snapshot-m ode>

<snapshot-interval>

<session-notificationpolicy>

Description

Whether to assume that a load balancer such as mod_cluster,

m od_jk, or m od_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.

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.getLastAccessedT im e()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.

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.

The interval, in milliseconds, at which modified sessions should be replicated when using INTERVALfor the value of <snapshot-

m ode>.

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.

Report a bug

7.2. HttpSession Passivation and Activation

7.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.

134

Chapter 7. Clustering in Web Applications

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.

Report a bug

7.2.2. Configure HttpSession Passivation in Your Application

Overview

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

MET A_INF/jboss-web.xm l file.

Example 7.3. Example jboss-web.xml File

<jboss-web>

<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

<m ax-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.

135

JBoss Enterprise Application Platform 6 Development Guide

<passivation-config> Child Elements

<use-session-passivation>

Whether or not to use session passivation. The default value is false.

<passivation-m in-idle-tim e>

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-m ax-idle-tim e> has elapsed. Neither a value of -1 nor a high value are recommended if <max-active-sessions> is set.

<passivation-m ax-idle-tim e>

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 7.1.2, “About the Web Session Cache” and Section 7.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 100 sessions in memory.

Report a bug

7.3. Cookie Domain

7.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 7.3.2, “Configure the Cookie Domain”

Report a bug

7.3.2. Configure the Cookie Domain

To enable your SSO valve to share a SSO context, configure the cookie domain in the valve

136

Chapter 7. Clustering in Web Applications 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 7.4 . Example Cookie Domain Configuration

<Valve className= "org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"

cookieDomain= "xyz.com" />

Report a bug

7.4. Implement an HA Singleton

Summary

In JBoss Enterprise Application Platform 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 Enterprise Application Platform 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 7.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.

a. Create a singleton service.

137

JBoss Enterprise Application Platform 6 Development Guide 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:[email protected]" > 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 () +

"'" );

}

138

Chapter 7. Clustering in Web Applications

}

} b. Create a singleton EJB to start the service as a SingletonService at server start.

139

JBoss Enterprise Application Platform 6 Development Guide 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:[email protected]" > 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

14 0

Chapter 7. Clustering in Web Applications 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 (Environ mentService.

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 ();

}

14 1

JBoss Enterprise Application Platform 6 Development Guide

}

} c. Create a Stateless Session Bean to access 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:[email protected]" > 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!" );

}

} d. Create the 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:[email protected]" > Wolf-Dieter Fink </a>

@Remote public interface ServiceAccess { public abstract String getNodeNameOfService ();

}

2. Start each JBoss Enterprise Application Platform 6 instance with clustering enabled

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

a. Enable clustering for servers running in a managed domain

To enable clustering for servers started using the domain controller, update your

14 2

Chapter 7. Clustering in Web Applications

dom ain.xm l and designate a server group to use the ha profile and ha-sockets socket binding group. For example:

<server-groups>

<server-group name= "main-server-group" profile= "ha" >

</jvm>

<socket-binding-group ref= "ha-sockets" />

</server-group>

</server-groups>

Modify the host.xml file as follows:

<socket-bindings port-offset= "100" />

</server>

Then start the server as follows

A. For Linux, type: EAP_HOME/bin/domain.sh

B. For Microsoft Windows, type: EAP_HOME\bin\domain.bat b. Enable clustering for standalone servers

To enable clustering for standalone servers, start the server using the node name and the

standalone-ha.xm l configuration file as follows:

A. For Linux, type: EAP_HOME/bin/standalone.sh --server-config=standalone-

ha.xm l -Djboss.node.nam e=UNIQUE_NODE_NAME

B. For Microsoft Windows, type: EAP_HOME\bin\standalone.bat --server-

config=standalone-ha.xm l -Djboss.node.nam e=UNIQUE_NODE_NAME

Note

To avoid port conflicts when running multiple servers on one machine, configure the

standalone-ha.xm l 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:

m vn clean install jboss-as:deploy

To deploy to additional servers, pass the server name and port number on the command line:

m vn clean package jboss-as:deploy -Ddeploy.hostnam e=localhost -

Ddeploy.port=10099

Report a bug

14 3

JBoss Enterprise Application Platform 6 Development Guide

Chapter 8. CDI

8.1. Overview of CDI

8.1.1. Overview of CDI

Section 8.1.2, “About Contexts and Dependency Injection (CDI)”

Section 8.1.5, “Relationship Between Weld, Seam 2, and JavaServer Faces”

Section 8.1.3, “Benefits of CDI”

Report a bug

8.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 Enterprise Application Platform includes Weld, which is the reference implementation of JSR-299.

For more information, about type-safe dependency injection, see Section 8.1.4, “About Type-safe

Dependency Injection” .

Report a bug

8.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.

Report a bug

8.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.

For more information about CDI, refer to

Section 8.1.2, “About Contexts and Dependency Injection (CDI)”

Report a bug

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

14 4

Chapter 8. CDI

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 Enterprise Application Platform.

Report a bug

8.2. Use CDI

8.2.1. First Steps

8.2.1.1. Enable CDI

Task Summary

Contexts and Dependency Injection (CDI) is one of the core technologies in the JBoss Enterprise

Application Platform, and is enabled by default. If for some reason it is disabled and you need to enable it, follow this procedure.

Procedure 8.1. Task:

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.xm l 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.xm l, search them for the string

<extension m odule="org.jboss.as.weld"/>. If it exists, it is located inside the

<extensions> section.

2. Before editing any files, stop the JBoss Enterprise Application Platform.

The JBoss Enterprise Application Platform 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:

4. Restart the JBoss Enterprise Application Platform.

Start the JBoss Enterprise Application Platform with your updated configuration.

Result:

The JBoss Enterprise Application Platform starts with the CDI subsystem enabled.

Report a bug

8.2.2. Use CDI to Develop an Application

8.2.2.1. Use CDI to Develop an Application

14 5

JBoss Enterprise Application Platform 6 Development Guide

Introduction

Contexts and Dependency Injection (CDI) gives you tremendous flexibility in developing applications, reusing code, adapting your code at deployment or run-time, and unit testing. The JBoss Enterprise

Application Platform includes Weld, the reference implementation of CDI. These tasks show you how to use CDI in your enterprise applications.

Section 8.2.1.1, “Enable CDI”

Section 8.2.2.2, “Use CDI with Existing Code”

Section 8.2.2.3, “Exclude Beans From the Scanning Process”

Section 8.2.2.4, “Use an Injection to Extend an Implementation”

Section 8.2.3.3, “Use a Qualifier to Resolve an Ambiguous Injection”

Section 8.2.7.4, “Override an Injection with an Alternative”

Section 8.2.7.2, “Use Named Beans”

Section 8.2.6.1, “Manage the Lifecycle of a Bean”

Section 8.2.6.2, “Use a Producer Method”

Section 8.2.10.2, “Use Interceptors with CDI”

Section 8.2.8.2, “Use Stereotypes”

Section 8.2.9.2, “Fire and Observe Events”

Report a bug

8.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 a file called beans.xml in the META-INF/ or WEB-INF/ directory of your archive.

The file can be empty.

Procedure 8.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.

Report a bug

8.2.2.3. Exclude Beans From the Scanning Process

Task Summary

One of the features of Weld, the JBoss Enterprise Application Platform's 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.

14 6

Example 8.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.

Chapter 8. CDI

<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>

<weld:exclude name= "com.acme.swing.**" />

<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

Report a bug

8.2.2.4 . Use an Injection to Extend an Implementation

14 7

JBoss Enterprise Application Platform 6 Development Guide

Task 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 8.2. Inject a Translator Bean Into the Welcome Class

The following pseudo-code injects a hypothetical Translator object into the Welcome class. The

T ranslator 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 + "!" );

}

...

}

Report a bug

8.2.3. Ambiguous or Unsatisfied Dependencies

8.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.

To fix an ambiguous dependency, see Section 8.2.3.3, “Use a Qualifier to Resolve an Ambiguous

Injection” .

Report a bug

8.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

14 8

Chapter 8. CDI you mean to inject. Qualifiers have a retention and a target, which are defined as in the example below.

Example 8.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 8.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) { ... }

}

Report a bug

8.2.3.3. Use a Qualifier to Resolve an Ambiguous Injection

Task Summary

This task shows an ambiguous injection and removes the ambiguity with a qualifier. Read more about

ambiguous injections at Section 8.2.3.1, “About Ambiguous or Unsatisfied Dependencies”

Example 8.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 8.3. Task:

14 9

JBoss Enterprise Application Platform 6 Development Guide

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.

Report a bug

8.2.4. Managed Beans

8.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 8.1.2, “About Contexts and Dependency Injection (CDI)” .

Report a bug

8.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

150

Chapter 8. CDI 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.xm l.

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.

Report a bug

8.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 8.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 8.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.

151

JBoss Enterprise Application Platform 6 Development Guide

Example 8.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 8.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.

Report a bug

8.2.5. Contexts, Scopes, and Dependencies

8.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

152

Chapter 8. CDI lifecycle. Several pre-defined scopes exist, and you can create your own scopes. Examples of predefined scopes are @RequestScoped, @SessionScoped, and @ConversationScope.

Report a bug

8.2.5.2. Available Contexts

Table 8.1. Available contexts

Context

@Dependent

@ApplicationScoped

@RequestScoped

@SessionScoped

@ConversationScoped

Custom scopes

Description

The bean is bound to the lifecycle of the bean holding the reference.

Bound to the lifecycle of the application.

Bound to the lifecycle of the request.

Bound to the lifecycle of the session.

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.

If the above contexts do not meet your needs, you can define custom scopes.

Report a bug

8.2.6. Bean Lifecycle

8.2.6.1. Manage the Lifecycle of a Bean

Task 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 8.2.5.1, “Contexts and Scopes”

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.

153

JBoss Enterprise Application Platform 6 Development Guide

<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.

Section 8.2.13.1, “About Bean Proxies”

Section 8.2.13.2, “Use a Proxy in an Injection”

Report a bug

8.2.6.2. Use a Producer Method

Task Summary:

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

Example 8.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 8.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;

154

Chapter 8. CDI

Example 8.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 8.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.

Report a bug

8.2.7. Named Beans and Alternative Beans

8.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.

Report a bug

8.2.7.2. Use Named Beans

155

JBoss Enterprise Application Platform 6 Development Guide

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.

Report a bug

8.2.7.3. About Alternative Beans

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

Example 8.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.xm l file.

Report a bug

8.2.7.4 . Override an Injection with an Alternative

Task Summary

156

Chapter 8. CDI

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 8.4 . Task:

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.xm l or WEB-INF/beans.xm lfile.

<beans>

<class> com.acme.MockTranslatingWelcome

</class>

</alternatives>

</beans>

Result:

The alternative implementation is now used instead of the original one.

Report a bug

8.2.8. Stereotypes

8.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

157

JBoss Enterprise Application Platform 6 Development Guide 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 8.2.7.1, “About Named Beans”

Report a bug

8.2.8.2. Use Stereotypes

Task 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 8.2.8.1, “About Stereotypes”

Example 8.14 . Annotation clutter

@Secure

@Transactional

@RequestScoped

@Named public class AccountManager { public boolean transfer (Account a, Account b) {

...

}

Procedure 8.5. Task

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.

Report a bug

8.2.9. Observer Methods

158

Chapter 8. CDI

8.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.

Report a bug

8.2.9.2. Fire and Observe Events

Example 8.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 8.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 8.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 8.17. Observe an event

To observe an event, use the @Observes annotation.

public class AccountObserver { void checkTran (@Observes Withdrawal w) {

...

}

159

JBoss Enterprise Application Platform 6 Development Guide

Example 8.18. Observe a qualified event

You can use qualifiers to observe only specific types of events. For more information about qualifiers,

see Section 8.2.3.2, “About Qualifiers”

public class AccountObserver { void checkTran (@Observes @Suspicious Withdrawal w) {

...

}

Report a bug

8.2.10. Interceptors

8.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.

Report a bug

8.2.10.2. Use Interceptors with CDI

160

Chapter 8. CDI

Example 8.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 errorprone.

@ Interceptors ({

SecurityInterceptor.

class ,

TransactionInterceptor.

class ,

LoggingInterceptor.

class

})

@Stateful public class BusinessComponent {

...

}

Procedure 8.6. 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.xm l.

<beans>

<class> com.acme.SecurityInterceptor

</class>

<class> com.acme.TransactionInterceptor

</class>

</interceptors>

</beans>

161

JBoss Enterprise Application Platform 6 Development Guide

The interceptors are applied in the order listed.

Result:

CDI simplifies your interceptor code and makes it easier to apply to your business code.

Report a bug

8.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 8.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);

...

}

Report a bug

8.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

162

Providing a context implementation for a custom scope

Augmenting or overriding the annotation-based metadata with metadata from some other source

Report a bug

Chapter 8. CDI

8.2.13. Bean Proxies

8.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

Report a bug

8.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

Paym entProcessor bean instance and calls the processPaym ent() method on it.

163

JBoss Enterprise Application Platform 6 Development Guide

Example 8.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 8.2.13.1, “About Bean Proxies”

Report a bug

164

Chapter 9. Java Transaction API (JTA)

9.1. Overview

9.1.1. Overview of Java Transactions API (JTA)

Introduction

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

Section 9.2.5, “About Java Transactions API (JTA)”

Section 9.5.2, “Lifecycle of a JTA Transaction”

Section 9.9.3, “JTA Transaction Example”

Report a bug

9.2. Transaction Concepts

9.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).

Report a bug

9.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

165

JBoss Enterprise Application Platform 6 Development Guide

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.

Report a bug

9.2.3. About the Transaction Coordinator or Transaction Manager

The terms Transaction Coordinator and Transaction Manager are mostly interchangeable in terms of transactions with the JBoss Enterprise Application Platform. The term Transaction Coordinator is usually used in the context of distributed transactions.

In JTA transactions, The Transaction Manager runs within the JBoss Enterprise Application Platform 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.

Section 9.2.4, “About Transaction Participants”

Section 9.2.2, “About ACID Properties for Transactions”

Section 9.2.1, “About Transactions”

Report a bug

9.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 agrees to only commit its state if every other participant can also do so. Otherwise, they each roll back.

Section 9.2.3, “About the Transaction Coordinator or Transaction Manager”

Report a bug

9.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 managed by the EJB container. Annotations are provided for creating and controlling transactions within your code.

Report a bug

9.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),

166

Chapter 9. Java Transaction API (JTA) 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 Enterprise Application Platform 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 Enterprise Application Platform 6. Supported configurations distribute transactions across multiple JBoss Enterprise Application Platform containers only.

Section 9.2.11, “About Distributed Transactions”

Section 9.2.3, “About the Transaction Coordinator or Transaction Manager”

Report a bug

9.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.

Report a bug

9.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 Enterprise Application Platform 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.

Report a bug

9.2.9. About the 2-Phase Commit Protocol

The Two-phase commit protocol (2PC) refers to the typical pattern of a database 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.

167

JBoss Enterprise Application Platform 6 Development Guide

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.

Report a bug

9.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.

Report a bug

9.2.11. About Distributed Transactions

A distributed transaction, or distributed Java Transaction API (JTA) transaction is a transaction with participants on multiple JBoss Enterprise Application Platform 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. The JBoss

Enterprise Application Platform supports distributed JTA transactions.

Report a bug

9.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

Enterprise Application Platform.

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

168

Chapter 9. Java Transaction API (JTA)

Refer to the JBoss Enterprise Application Platform 6 Javadocs bundle on the Red Hat Customer Portal for specific details about the methods and properties included in the ORB Portability API.

Report a bug

9.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.

Report a bug

9.2.14. About Garbage Collection

Garbage collection is a form of automatic memory management provided by the Java Virtual Machine

(JVM). Periodically, the garbage collector runs, and reclaims memory which was claimed by objects which are no longer in use by applications.

An object becomes eligible for garbage collection when there are no more references to it. In effect, this means that no threads refer to it anymore.

Garbage collection happens outside of user control. The JVM decides to run garbage collection based on the amount of available heap size. The heap size is tunable for performance. Refer to the documentation of your JVM for more information.

Report a bug

9.3. Transaction Optimizations

9.3.1. Overview of Transaction Optimizations

Introduction

The Transactions subsystem of the JBoss Enterprise Application Platform includes several optimizations which you can take advantage of in your applications.

Section 9.3.3, “About the Presumed-Abort Optimization”

Section 9.3.4, “About the Read-Only Optimization”

169

JBoss Enterprise Application Platform 6 Development Guide

Section 9.3.2, “About the LRCO Optimization for Single-phase Commit (1PC)”

Report a bug

9.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.

participants to commit, the transaction is rolled back. See Section 9.4.3, “About Transaction

Report a bug

9.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.

Report a bug

9.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.

Report a bug

9.4. Transaction Outcomes

9.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

Roll-Back” for more information.

170

Chapter 9. Java Transaction API (JTA)

Commit

If every transaction participant can commit, the transaction coordinator directs them to do so.

See Section 9.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 9.4.4, “About Heuristic Outcomes”

for more information.

Report a bug

9.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.

Report a bug

9.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.

Report a bug

9.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.

171

JBoss Enterprise Application Platform 6 Development Guide

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.

you have enlisted more than one resource. Section 9.2.9, “About the 2-Phase Commit Protocol”

Report a bug

9.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

Report a bug

9.5. Overview of JTA Transactions

9.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 managed by the EJB container. Annotations are provided for creating and controlling transactions within your code.

Report a bug

9.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

172

Chapter 9. Java Transaction API (JTA)

UserT ransaction.rollback(). This is when the two-phase commit protocol (2PC) happens if

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.

Section 9.2.1, “About Transactions”

Section 9.2.3, “About the Transaction Coordinator or Transaction Manager”

Section 9.2.4, “About Transaction Participants”

Section 9.2.7, “About XA Datasources and XA Transactions”

Report a bug

9.6. Transaction Subsystem Configuration

9.6.1. Transactions Configuration Overview

Introduction

The following procedures show you how to configure the transactions subsystem of the JBoss

Enterprise Application Platform.

Section 9.6.2.1, “Configure Your Datasource to Use JTA Transactions”

Section 9.6.2.2, “Configure an XA Datasource”

Section 9.7.8.2, “Configure the Transaction Manager”

Section 9.6.3.2, “Configure Logging for the Transaction Subsystem”

Report a bug

9.6.2. Transactional Datasource Configuration

9.6.2.1. Configure Your Datasource to Use JTA Transactions

Task Summary

This task shows you how to enable Java Transactions API (JTA) on your datasource.

Task Prerequisites

You must meet the following conditions before continuing with this task:

Your database or other resource must support JTA. If in doubt, consult the documentation for your database or other resource.

Create a datasource. Refer to Section 9.6.2.4, “Create a Non-XA Datasource with the Management

Interfaces” .

Stop the JBoss Enterprise Application Platform.

Have access to edit the configuration files directly, in a text editor.

Procedure 9.1. Task:

173

JBoss Enterprise Application Platform 6 Development Guide

1. Open the configuration file in a text editor.

Depending on whether you run the JBoss Enterprise Application Platform in a managed domain or standalone server, your configuration file will be in a different location.

A. Managed domain

The default configuration file for a managed domain is in

EAP_HOME/dom ain/configuration/dom ain.xm l for Red Hat Enterprise Linux, and

EAP_HOME\domain\configuration\domain.xml for Microsoft Windows Server.

B. Standalone server

The default configuration file for a standalone server is in

EAP_HOME/standalone/configuration/standalone.xm l 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:

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 the JBoss Enterprise Application Platform.

Relaunch the JBoss Enterprise Application Platform 6 server.

Result:

The JBoss Enterprise Application Platform starts, and your datasource is configured to use JTA transactions.

Report a bug

9.6.2.2. Configure an XA Datasource

Task Prerequisites:

In order to add an XA Datasource, you need to log into the Management Console. See Section 9.6.2.3,

“Log in to the Management Console” for more information.

1. Add a new datasource.

Add a new datasource to the JBoss Enterprise Application Platform. Follow the instructions in

Section 9.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 9.6.2.5, “Datasource Parameters”

Result:

Your XA Datasource is configured and ready to use.

Report a bug

174

Chapter 9. Java Transaction API (JTA)

9.6.2.3. Log in to the Management Console

Prerequisites

JBoss Enterprise Application Platform 6 must be running.

Procedure 9.2. Task

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.

Figure 9.1. Log in screen for the Management Console

Result

Once logged in, one of the Management Console landing pages appears:

Managed domain

http://localhost:9990/console/App.html#server-instances

Standalone server

http://localhost:9990/console/App.html#server-overview

Report a bug

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

Task 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 Enterprise Application Platform 6 server must be running.

175

JBoss Enterprise Application Platform 6 Development Guide

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 9.3. Task

A. 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 --drivername=DRIVER_NAME --connection-url=CONNECTION_URL

3. Enable the datasource: data-source enable --name=DATASOURCE_NAME

B. Management Console

1. Login to the Management Console.

2. Navigate to the Datasources panel in the Management Console a. A. Standalone Mode

Select the Profile tab from the top-right of the console.

B. Domain Mode a. Select the Profiles tab from the top-right of the console.

b. Select the appropriate profile from the drop-down box in the top left.

c. Expand the Subsystems menu on the left of the console.

b. Select Connector → Datasources from the menu on the left of the console.

176

Figure 9.2. Datasources panel

Chapter 9. Java Transaction API (JTA)

3. Create a new datasource a. Select the Add button at the top of the Datasources panel.

b. Enter the new datasource attributes in the Create Datasource wizard and proceed with the Next button.

c. Enter the JDBC driver details in the Create Datasource wizard and proceed with the Next button.

d. 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.

Report a bug

9.6.2.5. Datasource Parameters

177

JBoss Enterprise Application Platform 6 Development Guide

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

Parameter

jndi-name pool-name enabled use-java-context spy use-ccm new-connection-sql transaction-isolation url-delimiter url-selector-strategy-class-name security validation timeout statement

Description

The unique JNDI name for the datasource.

The name of the management pool for the datasource.

Whether or not the datasource is enabled.

Whether to bind the datasource to global JNDI.

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.

Enable the cached connection manager.

A SQL statement which executes when the connection is added to the connection pool.

One of the following:

TRANSACTION_READ_UNCOMMITTED

TRANSACTION_READ_COMMITTED

TRANSACTION_REPEATABLE_READ

TRANSACTION_SERIALIZABLE

TRANSACTION_NONE

The delimiter for URLs in a connection-url for

High Availability (HA) clustered databases.

A class that implements interface

org.jboss.jca.adapters.jdbc.URLSelec

torStrategy.

Contains child elements which are security

settings. Refer to Table 9.6, “Security parameters” .

Contains child elements which are validation

settings. Refer to Table 9.7, “Validation parameters” .

Contains child elements which are timeout

settings. Refer to Table 9.8, “Timeout parameters” .

Contains child elements which are statement

settings. Refer to Table 9.9, “Statement parameters” .

178

Chapter 9. Java Transaction API (JTA)

Table 9.2. Non-XA datasource parameters

Parameter

jta connection-url driver-class connection-property pool

Description

Enable JTA integration for non-XA datasources.

Does not apply to XA datasources.

The JDBC driver connection URL.

The fully-qualified name of the JDBC driver class.

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.

Contains child elements which are pooling

settings. Refer to Table 9.4, “Pool parameters common to non-XA and XA datasources” .

Table 9.3. XA datasource parameters

Parameter

xa-datasource-property xa-datasource-class driver xa-pool recovery

Description

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).

The fully-qualified name of the implementation class javax.sql.XADataSource.

A unique reference to the classloader module which contains the JDBC driver. The accepted format is

driverName#majorVersion.minorVersion.

Contains child elements which are pooling

settings. Refer to Table 9.4, “Pool parameters common to non-XA and XA datasources” and

Table 9.5, “XA pool parameters”

Contains child elements which are recovery

settings. Refer to Table 9.10, “Recovery parameters” .

179

JBoss Enterprise Application Platform 6 Development Guide

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

Parameter

min-pool-size max-pool-size prefill use-strict-min flush-strategy allow-multiple-users

Description

The minimum number of connections a pool holds.

The maximum number of connections a pool can hold.

Whether to try to prefill the connection pool. An empty element denotes a true value. The default is false.

Whether the pool-size is strict. Defaults to

false.

Whether the pool should be flushed in the case of an error. Valid values are:

FailingConnectionOnly

IdleConnections

EntirePool

The default is FailingConnectionOnly.

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 9.5. XA pool parameters

Parameter

is-same-rm-override interleaving no-tx-separate-pools pad-xid wrap-xa-resource

Description

Whether the

javax.transaction.xa.XAResource.isSa

m eRM(XAResource) class returns true or

false.

Whether to enable interleaving for XA connection factories.

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.

Whether to pad the Xid.

Whether to wrap the XAResource in an

org.jboss.tm .XAResourceWrapper

instance.

180

Table 9.6. Security parameters

Parameter

user-name password security-domain reauth-plugin

Chapter 9. Java Transaction API (JTA)

Description

The username to use to create a new connection.

The password to use to create a new connection.

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.

Defines a reauthentication plugin to use to reauthenticate physical connections.

181

JBoss Enterprise Application Platform 6 Development Guide

Table 9.7. Validation parameters

Parameter

valid-connection-checker check-valid-connection-sql validate-on-match background-validation background-validation-minutes use-fast-fail stale-connection-checker exception-sorter

Description

An implementation of interface

org.jboss.jca.adaptors.jdbc.ValidCon

nectionChecker which provides a

SQLException.isValidConnection(Conne

ction 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.

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.

Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set.

Mutually exclusive to background

validation.

Specifies that connections are validated on a background thread, rather than being validated prior to use. Mutually exclusive to validate-

on-m atch.

The amount of time, in minutes, that background validation runs.

If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to

false.

An instance of

org.jboss.jca.adapters.jdbc.StaleCon

nectionChecker which provides a Boolean

isStaleConnection(SQLException e)

method. If this method returns true, the exception is wrapped in an

org.jboss.jca.adapters.jdbc.StaleCon

nectionException, which is a subclass of

SQLException.

An instance of

org.jboss.jca.adapters.jdbc.Exceptio

nSorter which provides a Boolean

isExceptionFatal(SQLException e)

method. This method validates whether an exception should be broadcast to all instances of

javax.resource.spi.ConnectionEventLi

stener as a connectionErrorOccurred message.

182

Table 9.8. Timeout parameters

Parameter

blocking-timeout-millis idle-timeout-minutes set-tx-query-timeout query-timeout allocation-retry allocation-retry-wait-millis xa-resource-timeout

Table 9.9. Statement parameters

Parameter

track-statements prepared-statement-cache-size share-prepared-statements

Chapter 9. Java Transaction API (JTA)

Description

The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, and 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.

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.

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.

Timeout for queries, in seconds. The default is no timeout.

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.

How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.

If non-zero, this value is passed to method

XAResource.setT ransactionT im eout.

Description

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.

The number of prepared statements per connection, in a Least Recently Used (LRU) cache.

Whether asking for the same statement twice without closing it uses the same underlying prepared statement. The default is false.

183

JBoss Enterprise Application Platform 6 Development Guide

Table 9.10. Recovery parameters

Parameter

recover-credential recover-plugin

Description

A username/password pair or security domain to use for recovery.

An implementation of class

org.jboss.jca.core.spi.recoveryRecov

eryPlugin class, to be used for recovery.

Report a bug

9.6.3. Transaction Logging

9.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 9.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.

184

Chapter 9. Java Transaction API (JTA)

Table 9.11. Transaction State Change

Transaction Begin

Transaction Commit

Transaction Rollback

Transaction Timeout

When a transaction begins the following code is executed: com.arjuna.ats.arjuna.coordinator.Basic

Action::Begin:1342 tsLogger.logger.trace("BasicAction::Be gin() for action-id "+ get_uid());

When a transaction commits the following code is executed: com.arjuna.ats.arjuna.coordinator.Basic

Action::End:1342 tsLogger.logger.trace("BasicAction::En d() for action-id "+ get_uid());

When a transaction commits the following code is executed: com.arjuna.ats.arjuna.coordinator.Basic

Action::Abort:1575 tsLogger.logger.trace("BasicAction::Ab ort() for action-id "+ get_uid());

When a transaction times out the following code is executed: com.arjuna.ats.arjuna.coordinator.Trans

actionReaper::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

Report a bug

9.6.3.2. Configure Logging for the Transaction Subsystem

Task Summary

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

Procedure 9.4 . Configure the Transaction Logger Using the Management Console

185

JBoss Enterprise Application Platform 6 Development Guide

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

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.

Report a bug

9.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 Enterprise Application Platform 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 9.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

186

Chapter 9. Java Transaction API (JTA)

Example 9.2. View All Prepared Transactions

To view all prepared transactions, first refresh the log store (see Example 9.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=logstore/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=logstore/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=logstore/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:delete

Recover a transaction.

Each transaction log supports recovery via the :recover CLI command.

187

JBoss Enterprise Application Platform 6 Development Guide

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 reply the

com m it 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=logstore/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 filebased 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 9.6.2.1, “Configure Your Datasource to

Use JTA Transactions” for information on configuring the Transaction Manager.

View Transaction Statistics

You can view statistics about the Transaction Manager and transaction subsystem either via the webbased Management Console or the command-line Management CLI.

In the web-based Management Console, Transaction statistics are available via Runtime →

Subsystem Metrics → Transactions. 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.

188

Chapter 9. Java Transaction API (JTA)

Table 9.12. Transaction Subsystem Statistics

Statistic

Total

Committed

Aborted

Timed Out

Heuristics

In-Flight Transactions

Description

The total number of transactions processed by the

Transaction Manager on this server.

CLI Command

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberoftransactions,includedefaults=true)

The number of committed transactions processed by the

Transaction Manager on this server.

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberof-committedtransactions,includedefaults=true)

The number of aborted transactions processed by the

Transaction Manager on this server.

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberof-abortedtransactions,includedefaults=true)

The number of timed out transactions processed by the

Transaction Manager on this server.

Not available in the Management

Console. Number of transactions in a heuristic state.

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberof-heuristics,includedefaults=true)

Not available in the Management

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberof-timed-outtransactions,includedefaults=true)

189

JBoss Enterprise Application Platform 6 Development Guide

In-Flight Transactions Not available in the Management

Console. Number of transactions which have begun but not yet terminated.

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberof-inflighttransactions,includedefaults=true)

Failure Origin - Applications The number of failed transactions whose failure origin was an application.

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberof-applicationrollbacks,includedefaults=true)

Failure Origin - Resources The number of failed transactions whose failure origin was a resource.

/host=master/server=ser

ver-

one/subsystem=transacti ons/:readattribute(name=numberof-resourcerollbacks,includedefaults=true)

Report a bug

9.7. Use JTA Transactions

9.7.1. Transactions JTA Task Overview

Introduction

The following procedures are useful when you need to use transactions in your application.

Section 9.7.2, “Control Transactions”

Section 9.7.3, “Begin a Transaction”

Section 9.7.5, “Commit a Transaction”

Section 9.7.6, “Roll Back a Transaction”

Section 9.7.7, “Handle a Heuristic Outcome in a Transaction”

Section 9.7.8.2, “Configure the Transaction Manager”

Section 9.7.9.1, “Handle Transaction Errors”

Report a bug

9.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.

190

Chapter 9. Java Transaction API (JTA)

JTA or JTS APIs.

Section 9.7.3, “Begin a Transaction”

Section 9.7.5, “Commit a Transaction”

Section 9.7.6, “Roll Back a Transaction”

Section 9.7.7, “Handle a Heuristic Outcome in a Transaction”

Report a bug

9.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 beanmanaged transactions, by means of a

@ T ransactionManagem ent(T ransactionManagem entT ype.BEAN) annotation.

A. JNDI new InitialContext().lookup("java:comp/UserTransaction")

B. Injection

@Resource UserTransaction userTransaction;

C. 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:

191

JBoss Enterprise Application Platform 6 Development Guide

The transaction begins. All uses of your datasource until you commit or roll back the transaction are transactional.

Note

For a full example, see Section 9.9.3, “JTA Transaction Example”

Report a bug

9.7.4. Nest Transactions

Task Summary

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 transaction’s. There are two phases, a prepare phase and a

com m it 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

CosT ransactions::SubtransactionAwareResource interface.

JBoss Enterprise Application Platform's 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

ArjunaOT S::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 9.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.

Report a bug

9.7.5. Commit a Transaction

This procedure shows how to commit 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.

Task Prerequisites

Before you can commit a transaction, it must have been begun. Refer to Section 9.7.3, “Begin a

Transaction” for information on beginning transactions.

1. Call UserTransaction.commit().

When you call method UserTransaction.commit(), the Transaction Manager attempts to commit the transaction.

192

Chapter 9. Java Transaction API (JTA)

...

UserTransaction.commit(); catch (Exception ex) {

ex.printStackTrace();

System.exit(0);

}

2. If you are using an EJB, you do not need to manually commit.

If you use an EJB, you do not need to call commit(), because the container handles the transaction lifecycle.

Result:

Your datasource commits and your transaction ends, or an exception is thrown.

Note

For a full example, see Section 9.9.3, “JTA Transaction Example”

Report a bug

9.7.6. Roll Back a Transaction

This procedure shows how to roll back 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.

Task Prerequisites

Before you can roll back a transaction, it must have been begun. For information about beginning a

transaction, see Section 9.7.3, “Begin a Transaction”

1. Call UserTransaction.rollback().

When you call method UserTransaction.rollback(), the Transaction Manager attempts to roll back the transaction.

...

UserTransaction.rollback(); catch (Exception ex) {

ex.printStackTrace();

System.exit(0);

}

2. If you are using an EJB, you do not need to manually roll back.

If you use an EJB, you do not need to call rollback(), because the container handles the transaction lifecycle.

Result:

Your transaction is rolled back by the Transaction Manager.

Note

For a full example, see Section 9.9.3, “JTA Transaction Example”

193

JBoss Enterprise Application Platform 6 Development Guide

Report a bug

9.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 9.4.4, “About Heuristic Outcomes”

for more information about heuristic transaction outcomes.

Procedure 9.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 the JBoss Enterprise Application Platform, or the JBoss Enterprise Application Platform 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

The JBoss Enterprise Application Platform 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 the JBoss Enterprise Application Platform itself, contact Red Hat Global Support Services.

4. In a test environment, delete the logs and restart the JBoss Enterprise Application

Platform.

In a test environment, or if you do not care about the integrity of the data, deleting the transaction logs and restarting the JBoss Enterprise Application Platform 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: a. Identify which resource managers were involved.

b. Examine the state in the transaction manager and the resource managers.

194

Chapter 9. Java Transaction API (JTA) c. 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.

Report a bug

9.7.8. Transaction Timeouts

9.7.8.1. About Transaction Timeouts

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.

Report a bug

9.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 Enterprise Application Platform 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

195

JBoss Enterprise Application Platform 6 Development Guide 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.

196

Chapter 9. Java Transaction API (JTA)

Table 9.13. TM Configuration Options

Option

Enable Statistics

Enable TSM Status

Default Timeout

Path

Relative To

Object Store Path

Object Store Path Relative To

Description

Whether to enable transaction statistics. These statistics can be viewed in the Management

Console in the Subsystem

Metrics section of the

Runtim e tab.

Whether to enable the transaction status manager

(TSM) service, which is used for out-of-process recovery.

The default transaction timeout.

This defaults to 300 seconds.

You can override this programmatically, on a pertransaction basis.

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.

References a global path configuration in the domain model. The default value is the data directory for JBoss

Enterprise Application Platform

6, which is the value of the property

jboss.server.data.dir, and defaults to

EAP_HOME/dom ain/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.

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.

References a global path configuration in the domain model. The default value is the data directory for JBoss

Enterprise Application Platform

CLI Command

/profile=default/subsyst em =transactions/:writeattribute(nam e=enablestatistics,value=true)

/profile=default/subsyst em =transactions/:writeattribute(nam e=enabletsm -status,value=false)

/profile=default/subsyst em =transactions/:writeattribute(nam e=defaulttim eout,value=300)

/profile=default/subsyst em =transactions/:writeattribute(nam e=path,val ue=var)

/profile=default/subsyst em =transactions/:writeattribute(nam e=relative

to,value=jboss.server.da

ta.dir)

/profile=default/subsyst em =transactions/:writeattribute(nam e=objectstore-path,value=txobject-store)

/profile=default/subsyst em =transactions/:writeattribute(nam e=objectstore-relative-

197

JBoss Enterprise Application Platform 6 Development Guide

Socket Binding

Status Socket Binding

Recovery Listener

Enterprise Application Platform

6, which is the value of the property

jboss.server.data.dir, and defaults to

EAP_HOME/dom ain/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.

Specifies the name of the socket binding used by the Transaction

Manager for recovery and generating transaction identifiers, when the socketbased mechanism is used.

Refer to process-id-

socket-m ax-ports for more information on unique identifier generation. Socket bindings are specified per server group in the

Server tab of the Management

Console.

Specifies the socket binding to use for the Transaction Status manager.

Whether or not the Transaction

Recovery process should listen on a network socket. Defaults to

false.

to,value=jboss.server.da

ta.dir)

/profile=default/subsyst em =transactions/:writeattribute(nam e=socketbinding,value=txnrecovery-environm ent)

/profile=default/subsyst em =transactions/:writeattribute(nam e=statussocketbinding,value=txnstatus-m anager)

/profile=default/subsyst em =transactions/:writeattribute(nam e=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.

198

Chapter 9. Java Transaction API (JTA)

Table 9.14 . Advanced TM Configuration Options

Option

jts node-identifier process-id-socket-max-ports process-id-uuid use-hornetq-store log-store

Description

Whether to use Java

Transaction Service (JTS) transactions. Defaults to false, which uses JTA transactions only.

The node identifier for the JTS service. This should be unique per JTS service, because the

Transaction Manager uses this for recovery.

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-

m ax-ports represents the maximum number of sockets the

TM will try before failing. The default value is 10.

CLI Command

/profile=default/subsyst em =transactions/:writeattribute(nam e=jts,value

=false)

/profile=default/subsyst em =transactions/:writeattribute(nam e=nodeidentifier,value=1)

/profile=default/subsyst em =transactions/:writeattribute(nam e=processid-socket-m axports,value=10)

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-m ax-ports for more information.

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. If you enable this, also change the

log-store value to hornetq.

Set to default if you use the file-system-based object store,

/profile=default/subsyst em =transactions/:writeattribute(nam e=processid-uuid,value=true)

/profile=default/subsyst em =transactions/:writeattribute(nam e=usehornetqstore,value=false)

/profile=default/subsyst em =transactions/log-

199

JBoss Enterprise Application Platform 6 Development Guide or hornetq if you use the

HornetQ journaling storage mechanism. If you set this to

hornetq, also set use-

hornetq-store to true.

store=log-store/:writeattribute(nam e=type,valu e=default)

Report a bug

9.7.9. JTA Transaction Error Handling

9.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 9.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 9.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

T ransactionManager 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.

Report a bug

200

Chapter 9. Java Transaction API (JTA)

9.8. ORB Configuration

9.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 Enterprise Application Platform 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.

Report a bug

9.8.2. Configure the ORB for JTS Transactions

In a default installation of JBoss Enterprise Application Platform, 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.xm l configurations.

Procedure 9.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

201

JBoss Enterprise Application Platform 6 Development Guide

/profile=full portion of the commands.

Example 9.3. Enable the Security Interceptors

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

Example 9.4 . Enable the ORB for JTS

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

Report a bug

9.9. Transaction References

9.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

Report a bug

9.9.2. JTA Clustering Limitations

JTA transactions cannot be clustered across multiple instances of the JBoss Enterprise Application

Platform. For this behavior, use JTS transactions.

To use JTS transactions, you need to configure the ORB: Section 9.8.2, “Configure the ORB for JTS

Transactions” .

Report a bug

9.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.

202

Example 9.5. JTA Transaction example

Chapter 9. Java Transaction API (JTA)

203

JBoss Enterprise Application Platform 6 Development Guide

204

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 ( " \n Adding entries to table 1." );

stmtx.

executeUpdate ( "INSERT INTO test_table (a, b) VALUES

(1,2)" );

ResultSet res1 = null ;

System.

out .

println ( " \n Inspecting 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 ( " \n Adding entries to table 2." );

stmtx.

executeUpdate ( "INSERT INTO test_table2 (a, b) VALUES

(3,4)" );

res1 = stmtx.

executeQuery ( "SELECT * FROM test_table2" );

Chapter 9. Java Transaction API (JTA)

System.

out .

println ( " \n Inspecting table 2." ); while (res1.

next ()) {

System.

out .

println ( "Column 1: " +res1.

getInt ( 1 ));

System.

out .

println ( "Column 2: " +res1.

getInt ( 2 ));

}

System.

out .

print ( " \n Now attempting to rollback changes." );

txn.

rollback ();

// Next, we try to commit changes

txn.

begin ();

stmtx = conn.

createStatement ();

ResultSet res2 = null ;

System.

out .

println ( " \n Now 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 ( " \n Now 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 );

}

Report a bug

9.9.4. API Documentation for JBoss Transactions JTA

The API documentation for the Transaction subsystem of the JBoss Enterprise Application Platform is available at the following location:

UserTransaction - http://download.oracle.com/javaee/1.3/api/javax/transaction/UserTransaction.html

If you use JBoss Development Studio to develop your applications, the APIs are included in the Help menu.

205

JBoss Enterprise Application Platform 6 Development Guide

Report a bug

206

Chapter 10. Hibernate

10.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.

For more information, refer to Section 10.2.2, “Hibernate EntityManager” and the Section 10.2.1, “About

JPA” .

Report a bug

10.2. Java Persistence API (JPA)

10.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 the JBoss Enterprise Application Platform with a complete Java Persistence solution.

JBoss Enterprise Application Platform 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 Enterprise Application Platform 6, refer to the bean-validation,

greeter, and kitchensink quickstarts:

Section 1.5.2.1, “Access the Java EE Quickstart Examples”

Report a bug

10.2.2. Hibernate EntityManager

Hibernate EntityManager implements the programming interfaces and life-cycle rules defined by the JPA

2.0 specification . It provides the JBoss Enterprise Application Platform with a complete Java Persistence solution.

For more information about Java Persistence or Hibernate, refer to the Section 10.2.1, “About JPA”

and

Section 10.1, “About Hibernate Core”

Report a bug

10.2.3. Getting Started

10.2.3.1. Create a JPA project in JBoss Developer Studio

Task Summary

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

Procedure 10.1. Task

1. In the JBoss Developer Studio window, click File → New → JPA Project.

2. In the project dialog, type the name of the project.

207

JBoss Enterprise Application Platform 6 Development Guide

3. Select a Target runtime from the dropdown box.

4. a. If no Target runtime is available, click Target Runtime.

b. Find the JBoss Community Folder in the list.

208

c. Select JBoss Enterprise Application Platform 6.x Runtime

Chapter 10. Hibernate d. Click Next.

e. In the Home Directory field, click Browse to set the JBoss EAP source folder as the Home

Directory.

209

JBoss Enterprise Application Platform 6 Development Guide f. Click Finish.

5. Click Next.

6. Leave the source folders on build path window as default, and click Next.

7. In the Platform dropdown, ensure Hibernate (JPA 2.x) is selected.

8. Click Finish.

9. If prompted, choose whether you wish to open the JPA perspective window.

Report a bug

10.2.3.2. Create the Persistence Settings File in JBoss Developer Studio

Prerequisites

configured. An example file is available here: Section 10.2.3.3, “Example Persistence Settings

Task Summary

This topic covers the process for creating the persistence.xml file in a Java project using the JBoss

Developer Studio.

Procedure 10.2. Task

1. Open an EJB 3.x project in the JBoss Developer Studio.

2. Right click the project root directory in the Project Explorer panel.

3. Select New → Other....

210

Chapter 10. Hibernate

4. Select XML File from the XML folder and click Next.

5. Select the ejbModule/META-INF folder as the parent directory.

6. Name the file persistence.xml and click Next.

7. Select Create XML file from an XML schema file and click Next.

8. Select http://java.sun.com/xml/ns/persistence/persistence_2.0.xsd from the

Select XML Catalog entry list and click Next.

9. Click Finish to create the file.

Result:

The persistence.xml has been created in the META-INF/ folder and is ready to be

File”

Report a bug

10.2.3.3. Example Persistence Settings File

211

JBoss Enterprise Application Platform 6 Development Guide

Example 10.1. persistence.xml

<persistence xmlns="http://java.sun.com/xml/ns/persistence"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"

version="2.0">

<persistence-unit name="example" transaction-type="JTA">

<provider>org.hibernate.ejb.HibernatePersistence</provider>

<jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source>

<mapping-file>ormap.xml</mapping-file>

<jar-file>TestApp.jar</jar-file>

<shared-cache-mode>NONE</shared-cache-mode>

<validation-mode>CALLBACK</validation-mode>

</properties>

</persistence-unit>

</persistence>

Report a bug

10.2.3.4 . Create the Hibernate Configuration File in JBoss Developer Studio

Prerequisites

here: Section 10.2.3.5, “Example Hibernate Configuration File”

Task Summary

This topic covers the process for creating the hibernate.cfg.xml file in a Java project using the

JBoss Developer Studio.

Procedure 10.3. Task

1. Open a Java project in the JBoss Developer Studio.

2. Right click the project root directory in the Project Explorer panel.

3. Select New → Other....

4. Select Hibernate Configuration File from the Hibernate folder and click Next.

5. Select the src/ directory and click Next.

6. Configure the following:

Session factory name

Database dialect

Driver class

Connection URL

Username

Password

7. Click Finish to create the file.

Result:

The hibernate.cfg.xml has been created in the src/ folder. An example file is available

212

Chapter 10. Hibernate

Report a bug

10.2.3.5. Example Hibernate Configuration File

Example 10.2. hibernate.cfg.xml

<hibernate-configuration>

<session-factory>

<property name="connection.datasource">ExampleDS</property>

<property name="dialect">org.hibernate.dialect.H2Dialect</property>

<property name="current_session_context_class">thread</property>

<property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>

<property name="hbm2ddl.auto">update</property>

</session-factory>

</hibernate-configuration>

Report a bug

10.2.4. Configuration

10.2.4 .1. Hibernate Configuration Properties

213

JBoss Enterprise Application Platform 6 Development Guide

Table 10.1. Properties

Property Name

hibernate.dialect

hibernate.show_sql

hibernate.format_sql

hibernate.default_schema

hibernate.default_catalog

hibernate.session_factory_name

hibernate.max_fetch_depth

hibernate.default_batch_fetch_size

hibernate.default_entity_mode

hibernate.order_updates

hibernate.generate_statistics

hibernate.use_identifier_rollback

hibernate.use_sql_comments

hibernate.id.new_generator_mappings

Description

The classname of a Hibernate

org.hibernate.dialect.Dialect. Allows

Hibernate to generate SQL optimized for a particular relational database.

In most cases Hibernate will be able to choose the correct

org.hibernate.dialect.Dialect

implementation, based on the JDBC metadata returned by the JDBC driver.

Boolean. Writes all SQL statements to console.

This is an alternative to setting the log category

org.hibernate.SQL to debug.

Boolean. Pretty print the SQL in the log and console.

Qualify unqualified table names with the given schema/tablespace in generated SQL.

Qualifies unqualified table names with the given catalog in generated SQL.

The org.hibernate.SessionFactory will be automatically bound to this name in JNDI after it has been created. For example,

jndi/com posite/nam e.

Sets a maximum "depth" for the outer join fetch tree for single-ended associations (one-to-one, many-to-one). A 0 disables default outer join fetching. The recommended value is between 0 and 3.

Sets a default size for Hibernate batch fetching of associations. The recommended values are 4, 8, and 16.

Sets a default mode for entity representation for all sessions opened from this SessionFactory.

Values include: dynamic-map, dom4j, pojo.

Boolean. Forces Hibernate to order SQL updates by the primary key value of the items being updated. This will result in fewer transaction deadlocks in highly concurrent systems.

Boolean. If enabled, Hibernate will collect statistics useful for performance tuning.

Boolean. If enabled, generated identifier properties will be reset to default values when objects are deleted.

Boolean. If turned on, Hibernate will generate comments inside the SQL, for easier debugging.

Default value is false.

Boolean. This property is relevant when using

@ GeneratedValue. It indicates whether or not the new IdentifierGenerator implementations are used for

214

Chapter 10. Hibernate

javax.persistence.GenerationT ype.AUT

javax.persistence.GenerationT ype.T AB

LE and

javax.persistence.GenerationT ype.SEQ

UENCE. Default value is false to keep backward compatibility.

Important

It is recommended that all new projects that use @GeneratedValue also set

hibernate.id.new_generator_m appings=true. This is because the new generators are more efficient and closer to the JPA 2 specification semantic.

However, they are not backward compatible with existing databases (if a sequence or a table is used for id generation).

Report a bug

10.2.4 .2. Hibernate JDBC and Connection Properties

215

JBoss Enterprise Application Platform 6 Development Guide

Table 10.2. Properties

Property Name

hibernate.jdbc.fetch_size

hibernate.jdbc.batch_size

hibernate.jdbc.batch_versioned_data

hibernate.jdbc.factory_class

hibernate.jdbc.use_scrollable_resultset

hibernate.jdbc.use_streams_for_binary

hibernate.jdbc.use_get_generated_keys

hibernate.connection.provider_class

hibernate.connection.isolation

hibernate.connection.autocommit

hibernate.connection.release_mode

Description

A non-zero value that determines the JDBC fetch size (calls Statement.setFetchSize()).

A non-zero value enables use of JDBC2 batch updates by Hibernate. The recommended values are between 5 and 30.

Boolean. Set this property to true if the JDBC driver returns correct row counts from

executeBatch(). Hibernate will then use batched DML for automatically versioned data.

Default value is to false.

Select a custom

org.hibernate.jdbc.Batcher. Most applications will not need this configuration property.

Boolean. Enables use of JDBC2 scrollable resultsets by Hibernate. This property is only necessary when using user-supplied JDBC connections. Hibernate uses connection metadata otherwise.

Boolean. This is a system-level property. Use streams when writing/reading binary or

serializable types to/from JDBC.

Boolean. Enables use of JDBC3

PreparedStatem ent.getGeneratedKeys()

to retrieve natively generated keys after insert.

Requires JDBC3+ driver and JRE1.4+. Set to false if JDBC driver has problems with the

Hibernate identifier generators. By default, it tries to determine the driver capabilities using connection metadata.

The classname of a custom

org.hibernate.connection.Connection

Provider which provides JDBC connections to

Hibernate.

Sets the JDBC transaction isolation level. Check

java.sql.Connection for meaningful values, but note that most databases do not support all isolation levels and some define additional, nonstandard isolations. Standard values are 1, 2,

4 , 8.

Boolean. This property is not recommended for use. Enables autocommit for JDBC pooled connections.

Specifies when Hibernate should release JDBC connections. By default, a JDBC connection is held until the session is explicitly closed or disconnected. The default value auto will choose

after_statem ent for the JTA and CMT transaction strategies, and

after_transaction for the JDBC transaction strategy.

216

hibernate.connection.<propertyName> hibernate.jndi.<propertyName>

Chapter 10. Hibernate

Available values are auto (default) | on_close |

after_transaction | after_statem ent.

This setting only affects Sessions returned from

SessionFactory.openSession. For

Sessions obtained through

SessionFactory.getCurrentSession, the

CurrentSessionContext implementation configured for use controls the connection release mode for those Sessions.

Pass the JDBC property <propertyName> to

DriverManager.getConnection().

Pass the property <propertyName> to the JNDI

InitialContextFactory.

Report a bug

10.2.4 .3. Hibernate Cache Properties

Table 10.3. Properties

Property Name Description hibernate.cache.provider_class

hibernate.cache.use_m inim al_puts hibernate.cache.use_query_cache

The classname of a custom CacheProvider.

Boolean. Optimizes second-level cache operation to minimize writes, at the cost of more frequent reads. This setting is most useful for clustered caches and, in Hibernate3, is enabled by default for clustered cache implementations.

Boolean. Enables the query cache. Individual queries still have to be set cacheable.

hibernate.cache.use_second_level_cac

he hibernate.cache.region_prefix

Boolean. Used to completely disable the second level cache, which is enabled by default for classes that specify a <cache> mapping.

hibernate.cache.query_cache_factory

The classname of a custom QueryCache interface. The default value is the built-in

StandardQueryCache.

A prefix to use for second-level cache region names.

hibernate.cache.use_structured_entri

es hibernate.cache.default_cache_concur

rency_strategy

Boolean. Forces Hibernate to store data in the second-level cache in a more human-friendly format.

Setting used to give the name of the default

org.hibernate.annotations.CacheConcu

rrencyStrategy to use when either

@ Cacheable or @ Cache is used.

@ Cache(strategy="..") is used to override this default.

Report a bug

10.2.4 .4 . Hibernate Transaction Properties

217

JBoss Enterprise Application Platform 6 Development Guide

Table 10.4 . Properties

Property Name hibernate.transaction.factory_class

jta.UserT ransaction hibernate.transaction.m anager_lookup

_class hibernate.transaction.flush_before_c

om pletion hibernate.transaction.auto_close_ses

sion

Description

The classname of a TransactionFactory to use with Hibernate Transaction API. Defaults to JDBCTransactionFactory).

A JNDI name used by

JT AT ransactionFactory to obtain the JTA

UserT ransaction from the application server.

The classname of a

T ransactionManagerLookup. It is required when JVM-level caching is enabled or when using hilo generator in a JTA environment.

Boolean. If enabled, the session will be automatically flushed during the before completion phase of the transaction. Built-in and automatic session context management is preferred.

Boolean. If enabled, the session will be automatically closed during the after completion phase of the transaction. Built-in and automatic session context management is preferred.

Report a bug

10.2.4 .5. Miscellaneous Hibernate Properties

218

Chapter 10. Hibernate

Table 10.5. Properties

Property Name hibernate.current_session_context_cl

ass hibernate.query.factory_class

hibernate.query.substitutions

hibernate.hbm 2ddl.auto

hibernate.hbm 2ddl.im port_files

Description

Supply a custom strategy for the scoping of the

"current" Session. Values include jta | thread

| managed | custom.Class.

Chooses the HQL parser implementation:

org.hibernate.hql.internal.ast.AST Qu

eryT ranslatorFactory or

org.hibernate.hql.internal.classic.C

lassicQueryT ranslatorFactory.

Used to map from tokens in Hibernate queries to

SQL tokens (tokens might be function or literal names). For example,

hqlLiteral=SQL_LIT ERAL,

hqlFunction=SQLFUNC.

Automatically validates or exports schema DDL to the database when the SessionFactory is created. With create-drop, the database schema will be dropped when the

SessionFactory is closed explicitly. Property value options are validate | update | create

| create-drop

Comma-separated names of the optional files containing SQL DML statements executed during the SessionFactory creation. This is useful for testing or demonstrating. For example, by adding

INSERT statements, the database can be populated with a minimal set of data when it is deployed. An example value is

/hum ans.sql,/dogs.sql.

File order matters, as the statements of a given file are executed before the statements of the following files. These statements are only executed if the schema is created (i.e. if

hibernate.hbm 2ddl.auto is set to create or create-drop).

hibernate.hbm 2ddl.im port_files_sql_e xtractor hibernate.bytecode.use_reflection_op

tim izer

The classname of a custom

Im portSqlCom m andExtractor. Defaults to the built-in

SingleLineSqlCom m andExtractor. This is useful for implementing a dedicated parser that extracts a single SQL statement from each import file. Hibernate also provides

MultipleLinesSqlCom m andExtractor, which supports instructions/comments and quoted strings spread over multiple lines

(mandatory semicolon at the end of each statement).

Boolean. This is a system-level property, which cannot be set in the hibernate.cfg.xml file.

Enables the use of bytecode manipulation instead of runtime reflection. Reflection can sometimes be

219

JBoss Enterprise Application Platform 6 Development Guide

hibernate.bytecode.provider

useful when troubleshooting. Hibernate always requires either CGLIB or javassist even if the optimizer is turned off.

Both javassist or cglib can be used as byte manipulation engines. The default is javassist.

Property value is either javassist or cglib

Report a bug

10.2.4 .6. Hibernate SQL Dialects

Important

The hibernate.dialect property should be set to the correct

org.hibernate.dialect.Dialect subclass for the application database. If a dialect is specified, Hibernate will use sensible defaults for some of the other properties. This means that they do not have to be specified manually.

220

Chapter 10. Hibernate

Table 10.6. SQL Dialects (hibernate.dialect)

RDBMS

DB2

DB2 AS/400

DB2 OS390

PostgreSQL

MySQL5

MySQL5 with InnoDB

MySQL with MyISAM

Oracle (any version)

Oracle 9i

Oracle 10g

Oracle 11g

Sybase

Sybase Anywhere

Microsoft SQL Server 2000

Microsoft SQL Server 2005

Microsoft SQL Server 2008

SAP DB

Informix

HypersonicSQL

H2 Database

Ingres

Progress

Mckoi SQL

Interbase

Pointbase

FrontBase

Firebird

Dialect org.hibernate.dialect.DB2Dialect

org.hibernate.dialect.DB24 00Dialect org.hibernate.dialect.DB2390Dialect

org.hibernate.dialect.PostgreSQLDial

ect org.hibernate.dialect.MySQL5Dialect

org.hibernate.dialect.MySQL5InnoDBDi

alect org.hibernate.dialect.MySQLMyISAMDia

lect org.hibernate.dialect.OracleDialect

org.hibernate.dialect.Oracle9iDiale

ct org.hibernate.dialect.Oracle10gDial

ect org.hibernate.dialect.Oracle10gDial

ect org.hibernate.dialect.SybaseASE15Dia

lect org.hibernate.dialect.SybaseAnywhere

Dialect org.hibernate.dialect.SQLServerDiale

ct org.hibernate.dialect.SQLServer2005D

ialect org.hibernate.dialect.SQLServer2008D

ialect org.hibernate.dialect.SAPDBDialect

org.hibernate.dialect.Inform ixDiale ct org.hibernate.dialect.HSQLDialect

org.hibernate.dialect.H2Dialect

org.hibernate.dialect.IngresDialect

org.hibernate.dialect.ProgressDialec

t org.hibernate.dialect.MckoiDialect

org.hibernate.dialect.InterbaseDiale

ct org.hibernate.dialect.PointbaseDiale

ct org.hibernate.dialect.FrontbaseDiale

ct org.hibernate.dialect.FirebirdDiale

221

JBoss Enterprise Application Platform 6 Development Guide

Report a bug

10.2.5. Second-Level Caches

10.2.5.1. About Second-Level Caches

A second-level cache is a local data store that holds information persisted outside the application session. The cache is managed by the persistence provider, improving run-time by keeping the data separate from the application.

JBoss Enterprise Application Platform 6 supports caching for the following purposes:

Web Session Clustering

Stateful Session Bean Clustering

SSO Clustering

Hibernate Second Level Cache

Each cache container defines a "repl" and a "dist" cache. These caches should not be used directly by user applications.

Report a bug

10.2.5.2. Configure a Second Level Cache for Hibernate

Task Summary

This topic covers the configuration requirements for enabling Infinispan to act as the second level cache for Hibernate.

Procedure 10.4 . Task

1. Create the hibernate.cfg.xml file

Create the hibernate.cfg.xml in the deployment's classpath. For specifics, refer to

Section 10.2.3.4, “Create the Hibernate Configuration File in JBoss Developer Studio”

2. Add these lines of XML to the hibernate.cfg.xml file in your application. The XML needs to be inside the <session-factory> tags:

3. Add one of the following to the <session-factory> section of the hibernate.cfg.xml file:

A. If the Infinispan CacheManager is bound to JNDI:

org.hibernate.cache.infinispan.JndiInfinispanRegionFactory

</property>

java:CacheManager

</property>

B. If the Infinispan CacheManager is standalone:

org.hibernate.cache.infinispan.InfinispanRegionFactory

</property>

Result

222

Infinispan is configured as the Second Level Cache for Hibernate.

Report a bug

10.3. Hibernate Annotations

10.3.1. Hibernate Annotations

Chapter 10. Hibernate

223

JBoss Enterprise Application Platform 6 Development Guide

Table 10.7. Hibernate Defined Annotations

Annotation

AccessType

Any

AnyMetaDef

AnyMedaDefs

BatchSize

Cache

Cascade

Check

Columns

ColumnTransformer

ColumnTransformers

DiscriminatorFormula

DiscriminatorOptions

Entity

Fetch

FetchProfile

FetchProfiles

Filter

FilterDef

FilterDefs

FilterJoinTable

FilterJoinTables

Filters

Formula

Generated

GenericGenerator

Description

Property Access type.

Defines a ToOne association pointing to several entity types. Matching the according entity type is done through a metadata discriminator column.

This kind of mapping should be only marginal.

Defines @Any and @manyToAny metadata.

Defines @Any and @ManyToAny set of metadata. Can be defined at the entity level or the package level.

Batch size for SQL loading.

Add caching strategy to a root entity or a collection.

Apply a cascade strategy on an association.

Arbitrary SQL check constraints which can be defined at the class, property or collection level.

Support an array of columns. Useful for component user type mappings.

Custom SQL expression used to read the value from and write a value to a column. Use for direct object loading/saving as well as queries. The write expression must contain exactly one '?' placeholder for the value.

Plural annotation for @ColumnTransformer.

Useful when more than one column is using this behavior.

Discriminator formula to be placed at the root entity.

Optional annotation to express Hibernate specific discriminator properties.

Extends Entity with Hibernate features.

Defines the fetching strategy used for the given association.

Defines the fetching strategy profile.

Plural annotation for @FetchProfile.

Adds filters to an entity or a target entity of a collection.

Filter definition.

Array of filter definitions.

Adds filters to a join table collection.

Adds multiple @FilterJoinTable to a collection.

Adds multiple @Filters.

To be used as a replacement for @Column in most places. The formula has to be a valid SQL fragment.

This annotated property is generated by the database.

Generator annotation describing any kind of

Hibernate generator in a detyped manner.

224

GenericGenerators

Immutable

Index

JoinFormula

LazyCollection

LazyToOne

Loader

ManyToAny

MapKeyType

MetaValue

NamedNativeQueries

NamedNativeQuery

NamedQueries

NamedQuery

NaturalId

NotFound

OnDelete

OptimisticLock

OptimisticLocking

OrderBy

ParamDef

Chapter 10. Hibernate

Array of generic generator definitions.

Mark an Entity or a Collection as immutable. No annotation means the element is mutable.

An immutable entity may not be updated by the application. Updates to an immutable entity will be ignored, but no exception is thrown.

@Immutable placed on a collection makes the collection immutable, meaning additions and deletions to and from the collection are not allowed. A HibernateException is thrown in this case.

Defines a database index.

To be used as a replacement for @JoinColumn in most places. The formula has to be a valid SQL fragment.

Defines the lazy status of a collection.

Defines the lazy status of a ToOne association

(i.e. OneToOne or ManyToOne).

Overwrites Hibernate default FIND method.

Defines a ToMany association pointing to different entity types. Matching the according entity type is done through a metadata discriminator column. This kind of mapping should be only marginal.

Defines the type of key of a persistent map.

Represents a discriminator value associated to a given entity type.

Extends NamedNativeQueries to hold Hibernate

NamedNativeQuery objects.

Extends NamedNativeQuery with Hibernate features.

Extends NamedQueries to hold Hibernate

NamedQuery objects.

Extends NamedQuery with Hibernate features.

Specifies that a property is part of the natural id of the entity.

Action to do when an element is not found on an association.

Strategy to use on collections, arrays and on joined subclasses delete. OnDelete of secondary tables is currently not supported.

Whether or not a change of the annotated property will trigger an entity version increment. If the annotation is not present, the property is involved in the optimistic lock strategy (default).

Used to define the style of optimistic locking to be applied to an entity. In a hierarchy, only valid on the root entity.

Order a collection using SQL ordering (not HQL ordering).

A parameter definition.

225

Report a bug

10.4. Hibernate Query Language

10.4.1. About Hibernate Query Language

The Hibernate Query Language (HQL) and Java Persistence Query Language (JPQL) are both object model focused query languages similar in nature to SQL. HQL is a superset of JPQL. A HQL query is not

226

Chapter 10. Hibernate always a valid JPQL query, but a JPQL query is always a valid HQL query.

Both HQL and JPQL are non-type-safe ways to perform query operations. Criteria queries offer a typesafe approach to querying.

Report a bug

10.4.2. HQL Statements

HQL allows SELECT, UPDATE, DELETE, and INSERT statements. The HQL INSERT statement has no equivalent in JPQL.

Important

Care should be taken as to when an UPDATE or DELETE statement is executed.

Table 10.8. HQL Statements

Statement

SELECT

UDPAT E

DELET E

Description

The BNF for SELECT statements in HQL is: select_statement :: =

[select_clause]

from_clause

[where_clause]

[groupby_clause]

[having_clause]

[orderby_clause]

The simplest possible HQL SELECT statement is of the form: from com.acme.Cat

The BNF for UPDATE statement in HQL is the same as it is in JPQL

The BNF for DELETE statements in HQL is the same as it is in JPQL

Report a bug

10.4.3. About the INSERT Statement

HQL adds the ability to define INSERT statements. There is no JPQL equivalent to this. The BNF for an

HQL INSERT statement is: insert_statement ::= insert_clause select_statement insert_clause ::= INSERT INTO entity_name (attribute_list) attribute_list ::= state_field[, state_field ]*

The attribute_list is analogous to the column specification in the SQL INSERT statement.

For entities involved in mapped inheritance, only attributes directly defined on the named entity can be used in the attribute_list. Superclass properties are not allowed and subclass properties do not

227

JBoss Enterprise Application Platform 6 Development Guide make sense. In other words, INSERT statements are inherently non-polymorphic.

Warning

select_statem ent can be any valid HQL select query, with the caveat that the return types must match the types expected by the insert. Currently, this is checked during query compilation rather than allowing the check to relegate to the database. This may cause problems between

Hibernate Types which are equivalent as opposed to equal. For example, this might cause lead to issues with mismatches between an attribute mapped as a org.hibernate.type.DateType and an attribute defined as a org.hibernate.type.TimestampType, even though the database might not make a distinction or might be able to handle the conversion.

For the id attribute, the insert statement gives you two options. You can either explicitly specify the id property in the attribute_list, in which case its value is taken from the corresponding select expression, or omit it from the attribute_list in which case a generated value is used. This latter option is only available when using id generators that operate "in the database"; attempting to use this option with any "in memory" type generators will cause an exception during parsing.

For optimistic locking attributes, the insert statement again gives you two options. You can either specify the attribute in the attribute_list in which case its value is taken from the corresponding select expressions, or omit it from the attribute_list in which case the seed value defined by the corresponding org.hibernate.type.VersionType is used.

Example 10.3. Example INSERT Query Statements

String hqlInsert = "insert into DelinquentAccount (id, name) select c.id, c.name from Customer c where ..."; int createdEntities = s.createQuery( hqlInsert ).executeUpdate();

Report a bug

10.4.4. About the FROM Clause

The FROM clause is responsible defining the scope of object model types available to the rest of the query. It also is responsible for defining all the "identification variables" available to the rest of the query.

Report a bug

10.4.5. About the WITH Clause

HQL defines a WITH clause to qualify the join conditions. This is specific to HQL; JPQL does not define this feature.

Example 10.4 . with-clause Join Example

select distinct c from Customer c

left join c.orders o

with o.value > 5000.00

The important distinction is that in the generated SQL the conditions of the with clause are made part of the on clause in the generated SQL as opposed to the other queries in this section where the

HQL/JPQL conditions are made part of the where clause in the generated SQL. The distinction in this

228

Chapter 10. Hibernate specific example is probably not that significant. The with clause is sometimes necessary in more complicated queries.

Explicit joins may reference association or component/embedded attributes. In the case of component/embedded attributes, the join is simply logical and does not correlate to a physical (SQL) join.

Report a bug

10.4.6. About Collection Member References

References to collection-valued associations actually refer to the values of that collection.

Example 10.5. Collection References Example

select c from Customer c

join c.orders o

join o.lineItems l

join l.product p where o.status = 'pending'

and p.status = 'backorder'

// alternate syntax select c from Customer c,

in(c.orders) o,

in(o.lineItems) l

join l.product p where o.status = 'pending'

and p.status = 'backorder'

In the example, the identification variable o actually refers to the object model type Order which is the type of the elements of the Customer#orders association.

The example also shows the alternate syntax for specifying collection association joins using the IN syntax. Both forms are equivalent. Which form an application chooses to use is simply a matter of taste.

Report a bug

10.4.7. About Qualified Path Expressions

It was previously stated that collection-valued associations actually refer to the values of that collection.

Based on the type of collection, there are also available a set of explicit qualification expressions.

229

JBoss Enterprise Application Platform 6 Development Guide

Table 10.9. Qualified Path Expressions

Expression

VALUE

INDEX

KEY

ENT RY

Description

Refers to the collection value. Same as not specifying a qualifier. Useful to explicitly show intent. Valid for any type of collection-valued reference.

According to HQL rules, this is valid for both Maps and Lists which specify a

javax.persistence.OrderColum n

annotation to refer to the Map key or the List position (aka the OrderColumn value). JPQL however, reserves this for use in the List case and adds KEY for the MAP case. Applications interested in JPA provider portability should be aware of this distinction.

Valid only for Maps. Refers to the map's key. If the key is itself an entity, can be further navigated.

Only valid only for Maps. Refers to the Map's logical java.util.Map.Entry tuple (the combination of its key and value). ENTRY is only valid as a terminal path and only valid in the select clause.

230

Chapter 10. Hibernate

Example 10.6. Qualified Collection References Example

// Product.images is a Map<String,String> : key = a name, value = file path

// select all the image file paths (the map value) for Product#123 select i from Product p

join p.images i where p.id = 123

// same as above select value(i) from Product p

join p.images i where p.id = 123

// select all the image names (the map key) for Product#123 select key(i) from Product p

join p.images i where p.id = 123

// select all the image names and file paths (the 'Map.Entry') for Product#123 select entry(i) from Product p

join p.images i where p.id = 123

// total the value of the initial line items for all orders for a customer select sum( li.amount ) from Customer c

join c.orders o

join o.lineItems li where c.id = 123

and index(li) = 1

Report a bug

10.4.8. About Scalar Functions

HQL defines some standard functions that are available regardless of the underlying database in use.

HQL can also understand additional functions defined by the Dialect as well as the application.

Report a bug

10.4.9. HQL Standardized Functions

The following functions are available in HQL regardless of the underlying database in use.

231

JBoss Enterprise Application Platform 6 Development Guide

Table 10.10. HQL Standardized Funtions

Function

BIT _LENGT H

CAST

EXT RACT

SECOND

MINUT E

HOUR

DAY

MONT H

YEAR

ST R

Description

Returns the length of binary data.

Performs a SQL cast. The cast target should name the Hibernate mapping type to use. See the chapter on data types for more information.

Performs a SQL extraction on datetime values. An extraction extracts parts of the datetime (the year, for example). See the abbreviated forms below.

Abbreviated extract form for extracting the second.

Abbreviated extract form for extracting the minute.

Abbreviated extract form for extracting the hour.

Abbreviated extract form for extracting the day.

Abbreviated extract form for extracting the month.

Abbreviated extract form for extracting the year.

Abbreviated form for casting a value as character data.

Application developers can also supply their own set of functions. This would usually represent either custom SQL functions or aliases for snippets of SQL. Such function declarations are made by using the

addSqlFunction method of org.hibernate.cfg.Configuration

Report a bug

10.4.10. About the Concatenation Operation

HQL defines a concatenation operator in addition to supporting the concatenation (CONCAT) function.

This is not defined by JPQL, so portable applications should avoid using it. The concatenation operator is taken from the SQL concatenation operator - ||.

Example 10.7. Concatenation Operation Example

select 'Mr. ' || c.name.first || ' ' || c.name.last

from Customer c where c.gender = Gender.MALE

Report a bug

10.4.11. About Dynamic Instantiation

There is a particular expression type that is only valid in the select clause. Hibernate calls this "dynamic instantiation". JPQL supports some of this feature and calls it a "constructor expression".

Example 10.8. Dynamic Instantiation Example - Constructor

select new Family( mother, mate, offspr ) from DomesticCat as mother

join mother.mate as mate

left join mother.kittens as offspr

232

Chapter 10. Hibernate

So rather than dealing with the Object[] here we are wrapping the values in a type-safe java object that will be returned as the results of the query. The class reference must be fully qualified and it must have a matching constructor.

The class here need not be mapped. If it does represent an entity, the resulting instances are returned in the NEW state (not managed!).

This is the part JPQL supports as well. HQL supports additional "dynamic instantiation" features. First, the query can specify to return a List rather than an Object[] for scalar results:

Example 10.9. Dynamic Instantiation Example - List

select new list(mother, offspr, mate.name) from DomesticCat as mother

inner join mother.mate as mate

left outer join mother.kittens as offspr

The results from this query will be a List<List> as opposed to a List<Object[]>

HQL also supports wrapping the scalar results in a Map.

Example 10.10. Dynamic Instantiation Example - Map

select new map( mother as mother, offspr as offspr, mate as mate ) from DomesticCat as mother

inner join mother.mate as mate

left outer join mother.kittens as offspr select new map( max(c.bodyWeight) as max, min(c.bodyWeight) as min, count(*) as n ) from Cat cxt"/>

The results from this query will be a List<Map<String,Object>> as opposed to a List<Object[]>. The keys of the map are defined by the aliases given to the select expressions.

Report a bug

10.4.12. About HQL Predicates

Predicates form the basis of the where clause, the having clause and searched case expressions. They are expressions which resolve to a truth value, generally TRUE or FALSE, although boolean comparisons involving NULLs generally resolve to UNKNOWN.

HQL Predicates

Nullness Predicate

Check a value for nullness. Can be applied to basic attribute references, entity references and parameters. HQL additionally allows it to be applied to component/embeddable types.

233

JBoss Enterprise Application Platform 6 Development Guide

Example 10.11. Nullness Checking Examples

// select everyone with an associated address select p from Person p where p.address is not null

// select everyone without an associated address select p from Person p where p.address is null

Like Predicate

Performs a like comparison on string values. The syntax is: like_expression ::=

string_expression

[NOT] LIKE pattern_value

[ESCAPE escape_character]

The semantics follow that of the SQL like expression. The pattern_value is the pattern to attempt to match in the string_expression. Just like SQL, pattern_value can use "_" and "%" as wildcards. The meanings are the same. "_" matches any single character. "%" matches any number of characters.

The optional escape_character is used to specify an escape character used to escape the special meaning of "_" and "%" in the pattern_value. This is useful when needing to search on patterns including either "_" or "%".

Example 10.12. Like Predicate Examples

select p from Person p where p.name like '%Schmidt' select p from Person p where p.name not like 'Jingleheimmer%'

// find any with name starting with "sp_" select sp from StoredProcedureMetadata sp where sp.name like 'sp|_%' escape '|'

Between Predicate

Analogous to the SQL BETWEEN expression. Perform a evaluation that a value is within the range of 2 other values. All the operands should have comparable types.

234

Chapter 10. Hibernate

Example 10.13. Between Predicate Examples

select p from Customer c

join c.paymentHistory p where c.id = 123

and index(p) between 0 and 9 select c from Customer c where c.president.dateOfBirth

between {d '1945-01-01'}

and {d '1965-01-01'} select o from Order o where o.total between 500 and 5000 select p from Person p where p.name between 'A' and 'E'

Report a bug

10.4.13. About Relational Comparisons

Comparisons involve one of the comparison operators - =, >, >=, <, <=, <>]>. HQL also defines

<![CDATA[!= as a comparison operator synonymous with <>. The operands should be of the same type.

235

JBoss Enterprise Application Platform 6 Development Guide

Example 10.14 . Relational Comparison Examples

// numeric comparison select c from Customer c where c.chiefExecutive.age < 30

// string comparison select c from Customer c where c.name = 'Acme'

// datetime comparison select c from Customer c where c.inceptionDate < {d '2000-01-01'}

// enum comparison select c from Customer c where c.chiefExecutive.gender = com.acme.Gender.MALE

// boolean comparison select c from Customer c where c.sendEmail = true

// entity type comparison select p from Payment p where type(p) = WireTransferPayment

// entity value comparison select c from Customer c where c.chiefExecutive = c.chiefTechnologist

Comparisons can also involve subquery qualifiers - ALL, ANY, SOME. SOME and ANY are synonymous.

The ALL qualifier resolves to true if the comparison is true for all of the values in the result of the subquery. It resolves to false if the subquery result is empty.

Example 10.15. ALL Subquery Comparison Qualifier Example

// select all players that scored at least 3 points

// in every game.

select p from Player p where 3 > all (

select spg.points

from StatsPerGame spg

where spg.player = p

)

The ANY/SOME qualifier resolves to true if the comparison is true for some of (at least one of) the values in the result of the subquery. It resolves to false if the subquery result is empty.

Report a bug

236

Chapter 10. Hibernate

10.4.14. About the IN Predicate

The IN predicate performs a check that a particular value is in a list of values. Its syntax is: in_expression ::= single_valued_expression

[NOT] IN single_valued_list single_valued_list ::= constructor_expression |

(subquery) |

collection_valued_input_parameter constructor_expression ::= (expression[, expression]*)

The types of the single_valued_expression and the individual values in the

single_valued_list must be consistent. JPQL limits the valid types here to string, numeric, date, time, timestamp, and enum types. In JPQL, single_valued_expression can only refer to:

"state fields", which is its term for simple attributes. Specifically this excludes association and component/embedded attributes.

entity type expressions.

In HQL, single_valued_expression can refer to a far more broad set of expression types. Singlevalued association are allowed. So are component/embedded attributes, although that feature depends on the level of support for tuple or "row value constructor syntax" in the underlying database.

Additionally, HQL does not limit the value type in any way, though application developers should be aware that different types may incur limited support based on the underlying database vendor. This is largely the reason for the JPQL limitations.

The list of values can come from a number of different sources. In the constructor_expression and

collection_valued_input_param eter, the list of values must not be empty; it must contain at least one value.

237

JBoss Enterprise Application Platform 6 Development Guide

Example 10.16. In Predicate Examples

select p from Payment p where type(p) in (CreditCardPayment, WireTransferPayment) select c from Customer c where c.hqAddress.state in ('TX', 'OK', 'LA', 'NM') select c from Customer c where c.hqAddress.state in ?

select c from Customer c where c.hqAddress.state in (

select dm.state

from DeliveryMetadata dm

where dm.salesTax is not null

)

// Not JPQL compliant!

select c from Customer c where c.name in (

('John','Doe'),

('Jane','Doe')

)

// Not JPQL compliant!

select c from Customer c where c.chiefExecutive in (

select p

from Person p

where ...

)

Report a bug

10.4.15. About HQL Ordering

The results of the query can also be ordered. The ORDER BY clause is used to specify the selected values to be used to order the result. The types of expressions considered valid as part of the order-by clause include: state fields component/embeddable attributes scalar expressions such as arithmetic operations, functions, etc.

identification variable declared in the select clause for any of the previous expression types

HQL does not mandate that all values referenced in the order-by clause must be named in the select clause, but it is required by JPQL. Applications desiring database portability should be aware that not all databases support referencing values in the order-by clause that are not referenced in the select clause.

Individual expressions in the order-by can be qualified with either ASC (ascending) or DESC

(descending) to indicated the desired ordering direction.

238

Chapter 10. Hibernate

Example 10.17. Order-by Examples

// legal because p.name is implicitly part of p select p from Person p order by p.name

select c.id, sum( o.total ) as t from Order o

inner join o.customer c group by c.id

order by t

Report a bug

10.5. Hibernate Services

10.5.1. About Hibernate Services

Services are classes that provide Hibernate with pluggable implementations of various types of functionality. Specifically they are implementations of certain service contract interfaces. The interface is known as the service role; the implementation class is know as the service implementation. Generally speaking, users can plug in alternate implementations of all standard service roles (overriding); they can also define additional services beyond the base set of service roles (extending).

Report a bug

10.5.2. About Service Contracts

The basic requirement for a service is to implement the marker interface

org.hibernate.service.Service. Hibernate uses this internally for some basic type safety.

Optionally, the service can also implement the org.hibernate.service.spi.Startable and

org.hibernate.service.spi.Stoppable interfaces to receive notifications of being started and stopped. Another optional service contract is org.hibernate.service.spi.Manageable which marks the service as manageable in JMX provided the JMX integration is enabled.

Report a bug

10.5.3. Types of Service Dependencies

Services are allowed to declare dependencies on other services using either of 2 approaches:

@org.hibernate.service.spi.InjectService

Any method on the service implementation class accepting a single parameter and annotated with @InjectService is considered requesting injection of another service.

By default the type of the method parameter is expected to be the service role to be injected. If the parameter type is different than the service role, the serviceRole attribute of the

InjectService should be used to explicitly name the role.

By default injected services are considered required, that is the start up will fail if a named dependent service is missing. If the service to be injected is optional, the required attribute of the InjectService should be declared as false (default is true).

239

JBoss Enterprise Application Platform 6 Development Guide

org.hibernate.service.spi.ServiceRegistryAwareService

The second approach is a pull approach where the service implements the optional service interface org.hibernate.service.spi.ServiceRegistryAwareService which declares a single injectServices method.

During startup, Hibernate will inject the org.hibernate.service.ServiceRegistry itself into services which implement this interface. The service can then use the ServiceRegistry reference to locate any additional services it needs.

Report a bug

10.5.4. The ServiceRegistry

10.5.4 .1. About the ServiceRegistry

The central service API, aside from the services themselves, is the

org.hibernate.service.ServiceRegistry interface. The main purpose of a service registry is to hold, manage and provide access to services.

Service registries are hierarchical. Services in one registry can depend on and utilize services in that same registry as well as any parent registries.

Use org.hibernate.service.ServiceRegistryBuilder to build a

org.hibernate.service.ServiceRegistry instance.

Example 10.18. Use ServiceRegistryBuilder to create a ServiceRegistry

ServiceRegistryBuilder registryBuilder = new ServiceRegistryBuilder( bootstrapServiceRegistry );

ServiceRegistry serviceRegistry = registryBuilder.buildServiceRegistry();

Report a bug

10.5.5. Custom Services

10.5.5.1. About Custom Services

Once a org.hibernate.service.ServiceRegistry is built it is considered immutable; the services themselves might accept re-configuration, but immutability here means adding/replacing services. So another role provided by the org.hibernate.service.ServiceRegistryBuilder is to allow tweaking of the services that will be contained in the

org.hibernate.service.ServiceRegistry generated from it.

There are 2 means to tell a org.hibernate.service.ServiceRegistryBuilder about custom services.

Implement a org.hibernate.service.spi.BasicServiceInitiator class to control ondemand construction of the service class and add it to the

org.hibernate.service.ServiceRegistryBuilder via its addInitiator method.

Just instantiate the service class and add it to the

org.hibernate.service.ServiceRegistryBuilder via its addService method.

Either approach the adding a service approach or the adding an initiator approach are valid for extending a registry (adding new service roles) and overriding services (replacing service

24 0

Chapter 10. Hibernate implementations).

Example 10.19. Use ServiceRegistryBuilder to Replace an Existing Service with a Custom

Service

ServiceRegistryBuilder registryBuilder = new ServiceRegistryBuilder( bootstrapServiceRegistry );

serviceRegistryBuilder.addService( JdbcServices.class, new FakeJdbcService()

);

ServiceRegistry serviceRegistry = registryBuilder.buildServiceRegistry();

public class FakeJdbcService implements JdbcServices{

@Override

public ConnectionProvider getConnectionProvider() {

return null;

}

@Override

public Dialect getDialect() {

return null;

}

@Override

public SqlStatementLogger getSqlStatementLogger() {

return null;

}

@Override

public SqlExceptionHelper getSqlExceptionHelper() {

return null;

}

@Override

public ExtractedDatabaseMetaData getExtractedMetaDataSupport() {

return null;

}

@Override

public LobCreator getLobCreator(LobCreationContext lobCreationContext) {

return null;

}

@Override

public ResultSetWrapper getResultSetWrapper() {

return null;

}

@Override

public JdbcEnvironment getJdbcEnvironment() {

return null;

}

Report a bug

10.5.6. The Bootstrap Registry

10.5.6.1. About the Boot-strap Registry

24 1

JBoss Enterprise Application Platform 6 Development Guide

The boot-strap registry holds services that absolutely have to be available for most things to work. The main service here is the ClassLoaderService which is a perfect example. Even resolving configuration files needs access to class loading services (resource look ups). This is the root registry

(no parent) in normal use.

Instances of boot-strap registries are built using the

org.hibernate.service.BootstrapServiceRegistryBuilder class.

Report a bug

10.5.6.2. Using BootstrapServiceRegistryBuilder

Example 10.20. Using BootstrapServiceRegistryBuilder

BootstrapServiceRegistry bootstrapServiceRegistry = new

BootstrapServiceRegistryBuilder()

// pass in org.hibernate.integrator.spi.Integrator instances which are not

// auto-discovered (for whatever reason) but which should be included

.with( anExplicitIntegrator )

// pass in a class-loader Hibernate should use to load application classes

.withApplicationClassLoader( anExplicitClassLoaderForApplicationClasses )

// pass in a class-loader Hibernate should use to load resources

.withResourceClassLoader( anExplicitClassLoaderForResources )

// see BootstrapServiceRegistryBuilder for rest of available methods

...

// finally, build the bootstrap registry with all the above options

.build();

Report a bug

10.5.6.3. BootstrapRegistry Services org.hibernate.service.classloading.spi.ClassLoaderService

Hibernate needs to interact with ClassLoaders. However, the manner in which Hibernate (or any library) should interact with ClassLoaders varies based on the runtime environment which is hosting the application. Application servers, OSGi containers, and other modular class loading systems impose very specific class-loading requirements. This service is provides Hibernate an abstraction from this environmental complexity. And just as importantly, it does so in a single-swappable-component manner.

In terms of interacting with a ClassLoader, Hibernate needs the following capabilities: the ability to locate application classes the ability to locate integration classes the ability to locate resources (properties files, xml files, etc) the ability to load java.util.ServiceLoader

Note

Currently, the ability to load application classes and the ability to load integration classes are combined into a single "load class" capability on the service. That may change in a later release.

org.hibernate.integrator.spi.IntegratorService

24 2

Chapter 10. Hibernate

Applications, add-ons and others all need to integrate with Hibernate which used to require something, usually the application, to coordinate registering the pieces of each integration needed on behalf of each integrator. The intent of this service is to allow those integrators to be discovered and to have them integrate themselves with Hibernate.

This service focuses on the discovery aspect. It leverages the standard Java

java.util.ServiceLoader capability provided by the

org.hibernate.service.classloading.spi.ClassLoaderService in order to discover implementations of the org.hibernate.integrator.spi.Integrator contract.

Integrators would simply define a file named /META-

INF/services/org.hibernate.integrator.spi.Integrator and make it available on the classpath. java.util.ServiceLoader covers the format of this file in detail, but essentially it list classes by FQN that implement the org.hibernate.integrator.spi.Integrator one per line.

Report a bug

10.5.7. The SessionFactory Registry

10.5.7.1. SessionFactory Registry

While it is best practice to treat instances of all the registry types as targeting a given

org.hibernate.SessionFactory, the instances of services in this group explicitly belong to a single org.hibernate.SessionFactory.

The difference is a matter of timing in when they need to be initiated. Generally they need access to the

org.hibernate.SessionFactory to be initiated. This special registry is

org.hibernate.service.spi.SessionFactoryServiceRegistry

Report a bug

10.5.7.2. SessionFactory Services org.hibernate.event.service.spi.EventListenerRegistry

Description

Service for managing event listeners.

Initiator org.hibernate.event.service.internal.EventListenerServiceInitiator

Implementations org.hibernate.event.service.internal.EventListenerRegistryIm pl

Report a bug

10.5.8. Integrators

10.5.8.1. Integrators

The org.hibernate.integrator.spi.Integrator is intended to provide a simple means for allowing developers to hook into the process of building a functioning SessionFactory. The

org.hibernate.integrator.spi.Integrator interface defines 2 methods of interest:

integrate allows us to hook into the building process; disintegrate allows us to hook into a

SessionFactory shutting down.

24 3

JBoss Enterprise Application Platform 6 Development Guide

Note

There is a 3rd method defined on org.hibernate.integrator.spi.Integrator, an overloaded form of integrate accepting a

org.hibernate.m etam odel.source.MetadataIm plem entor instead of

org.hibernate.cfg.Configuration. This form is intended for use with the new metamodel code scheduled for completion in 5.0.

In addition to the discovery approach provided by the IntegratorService, applications can manually register Integrator implementations when building the BootstrapServiceRegistry.

Report a bug

10.5.8.2. Integrator use-cases

The main use cases for an org.hibernate.integrator.spi.Integrator right now are registering event listeners and providing services (see

org.hibernate.integrator.spi.ServiceContributingIntegrator). With 5.0 we plan on expanding that to allow altering the metamodel describing the mapping between object and relational models.

Example 10.21. Registering event listeners

public class MyIntegrator implements org.hibernate.integrator.spi.Integrator {

public void integrate(

Configuration configuration,

SessionFactoryImplementor sessionFactory,

SessionFactoryServiceRegistry serviceRegistry) {

// As you might expect, an EventListenerRegistry is the thing with which event listeners are registered It is a

// service so we look it up using the service registry

final EventListenerRegistry eventListenerRegistry = serviceRegistry.getService( EventListenerRegistry.class );

// If you wish to have custom determination and handling of "duplicate" listeners, you would have to add an

// implementation of the org.hibernate.event.service.spi.DuplicationStrategy contract like this

eventListenerRegistry.addDuplicationStrategy( myDuplicationStrategy );

// EventListenerRegistry defines 3 ways to register listeners:

// 1) This form overrides any existing registrations with

eventListenerRegistry.setListeners( EventType.AUTO_FLUSH, myCompleteSetOfListeners );

// 2) This form adds the specified listener(s) to the beginning of the listener chain

eventListenerRegistry.prependListeners( EventType.AUTO_FLUSH, myListenersToBeCalledFirst );

// 3) This form adds the specified listener(s) to the end of the listener chain

eventListenerRegistry.appendListeners( EventType.AUTO_FLUSH, myListenersToBeCalledLast );

}

24 4

Chapter 10. Hibernate

Report a bug

10.6. Bean Validation

10.6.1. About Bean Validation

Bean Validation, or JavaBeans Validation, is a model for validating data in Java objects. The model uses built-in and custom annotation constraints to ensure the integrity of application data. The specification is documented here: http://jcp.org/en/jsr/detail?id=303 .

Hibernate Validator is the JBoss Enterprise Application Platform's implementation of Bean Validation. It is also the reference implementation of the JSR.

JBoss Enterprise Application Platform 6 is 100% compliant with JSR 303 - Bean Validation. Hibernate

Validator also provides additional features to the specification.

To get started with Bean Validation, refer to the bean-validation quickstart example: Section 1.5.2.1,

“Access the Java EE Quickstart Examples” .

Report a bug

10.6.2. Hibernate Validator

Hibernate Validator is the reference implementation of JSR 303 - Bean Validation .

Bean Validation provides users with a model for validating Java object data. For more information, refer

to Section 10.6.1, “About Bean Validation” and Section 10.6.3.1, “About Validation Constraints”

Report a bug

10.6.3. Validation Constraints

10.6.3.1. About Validation Constraints

Validation constraints are rules applied to a java element, such as a field, property or bean. A constraint will usually have a set of attributes used to set its limits. There are predefined constraints, and custom ones can be created. Each constraint is expressed in the form of an annotation.

The built-in validation constraints for Hibernate Validator are listed here: Section 10.6.3.4, “Hibernate

Validator Constraints”

For more information, refer to Section 10.6.2, “Hibernate Validator” and Section 10.6.1, “About Bean

Validation” .

Report a bug

10.6.3.2. Create a Constraint Annotation in the JBoss Developer Studio

Prerequisites

Create a new Java class. For more information, refer to Section 10.6.3.3, “Create a New Java

Task Summary

This task covers the process of creating a constraint annotation in the JBoss Developer Studio, for use within a Java application.

Procedure 10.5. Task

1. Open a Java project in the JBoss Developer Studio.

24 5

JBoss Enterprise Application Platform 6 Development Guide

2. Create a Data Set

A constraint annotation requires a data set that defines the acceptable values.

a. Right click on the project root folder in the Project Explorer panel.

b. Select New → Enum.

c. Configure the following elements:

Package:

Nam e:

d. Click the Add... button to add any required interfaces.

e. Click Finish to create the file.

f. Add a set of values to the data set and click Save.

Example 10.22. Example Data Set

package com.example; public enum CaseMode {

UPPER,

LOWER;

}

3. Create the Annotation File

Class in the JBoss Developer Studio” .

4. Configure the constraint annotation and click Save.

Example 10.23. Example Constraint Annotation File

package com.mycompany; import static java.lang.annotation.ElementType.*; import static java.lang.annotation.RetentionPolicy.*; import java.lang.annotation.Documented; import java.lang.annotation.Retention; import java.lang.annotation.Target; import javax.validation.Constraint; import javax.validation.Payload;

@Target( { METHOD, FIELD, ANNOTATION_TYPE })

@Retention(RUNTIME)

@Constraint(validatedBy = CheckCaseValidator.class)

@Documented public @interface CheckCase {

String message() default "{com.mycompany.constraints.checkcase}";

Class<?>[] groups() default {};

Class<? extends Payload>[] payload() default {};

CaseMode value();

}

24 6

Result

Chapter 10. Hibernate

A custom constraint annotation with a set of possible values has been created, ready to be used in the Java project.

Report a bug

10.6.3.3. Create a New Java Class in the JBoss Developer Studio

Prerequisites