JBoss.org Community Documentation

Chapter 16. Usage of JBoss specific deployment descriptors

The EJB 3.0 specification supports the usage of deployment descriptors to describe ejb metadata or override most metadata described via annotations. The jboss.xml deployment descriptor describes JBoss specific metadata, including remote and local JNDI names, cluster configuration, a security domain, additional references, security principal, and container configuration. Annotations which define the ejb (e.g. @Stateful, @Remote) cannot be overridden.

jboss.xml :

Take a look at META-INF/jboss.xml.

  • The jndi-name element defines the remote JNDI binding for the ShoppingCartBean stateful session bean. This JNDI binding overrides the default binding or a binding specified through the @RemoteBinding annotation. Similarly, the local-jndi-name element specifies the local JNDI binding.
  • The clustered element indicates that the ejb is clustered, with partition-name and load-balance-policy specifying the cluster name and load balance policy, respectively. These elements will override the parameters specified in the @Clustered annotation. In this example, you will see that the ShoppingCartBean ejb is clustered.


    If you build and run this example with the "default" server configuration, the deployment will fail, as the default server configuration does not support clustering. You will have to run this example on the "all" server configuration which supports clustering
  • The security-domain element specifies a security domain for the ejb, overriding any security domain set through the @SecurityDomain annotation. In this example, you will see that a security domain is set through the jboss.xml deployment descriptor and unless a Principal and Credential (i.e. user/password) is set in the client, requests to the ejb will fail with a javax.ejb.EJBAccessException.


    The jboss.xml shows using the security-domain at a bean level as well at the entire deployment level. Each bean can have its own security-domain and will override the one set at the deployment level.

Building and Running

From the command prompt, move to the "jboss_deployment_descriptor" folder under the Section 1.3, “Set the EJB3_TUTORIAL_HOME”

Ant Users:

Make sure the "all" server configuration of JBossAS-5.x is running

$ ant
$ ant run

     [java] Attempting to buy 1 memory stick with incorrect password
     [java] Caught javax.ejb.EJBAccessException as expected
     [java] Setting user/password
     [java] bill is a shopper, so is allowed to buy
     [java] Buying 1 memory stick
     [java] Buying another memory stick
     [java] Buying a laptop
     [java] Print cart:
     [java] 2     Memory stick
     [java] 1     Laptop
     [java] bill is not a clerk, so is not allowed to price check
     [java] Caught EJBAccessException as expected
     [java] Checkout
     [java] Should throw an object not found exception by invoking on cart after @Remove method
     [java] Successfully caught no such object exception.
     [java] Caught javax.ejb.EJBAccessException, for SLSB, as expected
     [java] Now passing the correct user/password to access the SLSB
     [java] Successfully accessed SLSB


Maven Users: Make sure the AS is not running.

$ mvn clean install -PRunSingleTutorial