8.8. Reference
8.8.1. EJB JNDI Naming Reference
The JNDI lookup name for a session bean has the syntax of:
ejb:<appName>/<moduleName>/<distinctName>/<beanName>!<viewClassName>?stateful
<appName>- If the session bean's JAR file has been deployed within an enterprise archive (EAR) then this is the name of that EAR. By default, the name of an EAR is its filename without the
.earsuffix. The application name can also be overridden in itsapplication.xmlfile. If the session bean is not deployed in an EAR then leave this blank. <moduleName>- The module name is the name of the JAR file that the session bean is deployed in. By the default, the name of the JAR file is its filename without the
.jarsuffix. The module name can also be overridden in the JAR'sejb-jar.xmlfile. <distinctName>- JBoss EAP 6 allows each deployment to specify an optional distinct name. If the deployment does not have a distinct name then leave this blank.
<beanName>- The bean name is the classname of the session bean to be invoked.
<viewClassName>- The view class name is the fully qualified classname of the remote interface. This includes the package name of the interface.
?stateful- The
?statefulsuffix is required when the JNDI name refers to a stateful session bean. It is not included for other bean types.
8.8.2. EJB Reference Resolution
This section covers how JBoss implements
@EJB and @Resource. Please note that XML always overrides annotations but the same rules apply.
Rules for the @EJB annotation
- The
@EJBannotation also has amappedName()attribute. The specification leaves this as vendor specific metadata, but JBoss recognizesmappedName()as the global JNDI name of the EJB you are referencing. If you have specified amappedName(), then all other attributes are ignored and this global JNDI name is used for binding. - If you specify
@EJBwith 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
@EJBinjection. If there are more than one EJB that publishes same business interface, then an exception is thrown. If there is only one bean with that interface then that one is used. - Search the EAR for EJBs that publish that interface. If there are duplicates, then an exception is thrown. Otherwise the matching bean is returned.
- Search globally in JBoss runtime for an EJB of that interface. Again, if duplicates are found, an exception is thrown.
@EJB.beanName()corresponds to<ejb-link>. If thebeanName()is defined, then use the same algorithm as@EJBwith no attributes defined except use thebeanName()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.
8.8.3. Project dependencies for Remote EJB Clients
Maven projects that include the invocation of session beans from remote clients require the following dependencies from the JBoss EAP 6 Maven repository.
| GroupID | ArtifactID |
|---|---|
| org.jboss.spec | jboss-javaee-6.0 |
| org.jboss.as | jboss-as-ejb-client-bom |
| org.jboss.spec.javax.transaction | jboss-transaction-api_1.1_spec |
| org.jboss.spec.javax.ejb | jboss-ejb-api_3.1_spec |
| org.jboss | jboss-ejb-client |
| org.jboss.xnio | xnio-api |
| org.jboss.xnio | xnio-nio |
| org.jboss.remoting3 | jboss-remoting |
| org.jboss.sasl | jboss-sasl |
| org.jboss.marshalling | jboss-marshalling-river |
With the exception of
jboss-javaee-6.0 and jboss-as-ejb-client-bom, these dependencies must be added to the <dependencies> section of the pom.xml file.
The
jboss-javaee-6.0 and jboss-as-ejb-client-bom dependencies should be added to the <dependencyManagement> section of your pom.xml with the scope of import.
Note
The
artifactID's versions are subject to change. Refer to the Maven repository for the relevant version.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.spec</groupId>
<artifactId>jboss-javaee-6.0</artifactId>
<version>3.0.0.Final-redhat-1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.jboss.as</groupId>
<artifactId>jboss-as-ejb-client-bom</artifactId>
<version>7.1.1.Final-redhat-1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Refer to
ejb-remote/client/pom.xml in the quickstart files for a complete example of dependency configuration for remote session bean invocation.
8.8.4. jboss-ejb3.xml Deployment Descriptor Reference
jboss-ejb3.xml is a custom deployment descriptor that can be used in either EJB JAR or WAR archives. In an EJB JAR archive it must be located in the META-INF/ directory. In a WAR archive it must be located in the WEB-INF/ directory.
The format is similar to
ejb-jar.xml, using some of the same namespaces and providing some other additional namespaces. The contents of jboss-ejb3.xml are merged with the contents of ejb-jar.xml, with the jboss-ejb3.xml items taking precedence.
This document only covers the additional non-standard namespaces used by
jboss-ejb3.xml. Refer to http://java.sun.com/xml/ns/javaee/ for documentation on the standard namespaces.
The root namespace is
http://www.jboss.com/xml/ns/javaee.
Assembly descriptor namespaces
The following namespaces can all be used in the
<assembly-descriptor> element. They can be used to apply their configuration to a single bean, or to all beans in the deployment by using * as the ejb-name.
- The clustering namespace:
urn:clustering:1.0 xmlns:c="urn:clustering:1.0"
This allows you to mark EJB's as clustered. It is the deployment descriptor equivalent to@org.jboss.ejb3.annotation.Clustered.<c:clustering> <ejb-name>DDBasedClusteredSFSB</ejb-name> <c:clustered>true</c:clustered> </c:clustering>
- The security namespace (
urn:security) xmlns:s="urn:security"
This allows you to set thesecurity-domainand therun-as-principalfor 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 adapter namespace:
urn:resource-adapter-binding xmlns:r="urn:resource-adapter-binding"
This allows you to set the resource adapter for a Message-Driven Bean.<r:resource-adapter-binding> <ejb-name>*</ejb-name> <r:resource-adapter-name>myResourceAdapter</r:resource-adapter-name> </r:resource-adapter-binding>
- The IIOP namespace:
urn:iiop xmlns:u="urn:iiop"
The IIOP namespace is where IIOP settings are configured.- The pool namespace:
urn:ejb-pool:1.0 xmlns:p="urn:ejb-pool:1.0"
This allows you to select the pool that is used by the included stateless session beans or Message-Driven Beans. Pools are defined in the server configuration.<p:pool> <ejb-name>*</ejb-name> <p:bean-instance-pool-ref>my-pool</p:bean-instance-pool-ref> </p:pool>
- The cache namespace:
urn:ejb-cache:1.0 xmlns:c="urn:ejb-cache:1.0"
This allows you to select the cache that is used by the included stateful session beans. Caches are defined in the server configuration.<c:cache> <ejb-name>*</ejb-name> <c:cache-ref>my-cache</c:cache-ref> </c:cache>
Example 8.8. jboss-ejb3.xml file
<?xml version="1.1" encoding="UTF-8"?>
<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:c="urn:clustering:1.0"
xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd"
version="3.1" impl-version="2.0">
<enterprise-beans>
<message-driven>
<ejb-name>ReplyingMDB</ejb-name>
<ejb-class>org.jboss.as.test.integration.ejb.mdb.messagedestination.ReplyingMDB</ejb-class>
<activation-config>
<activation-config-property>
<activation-config-property-name>destination</activation-config-property-name>
<activation-config-property-value>java:jboss/mdbtest/messageDestinationQueue
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
</enterprise-beans>
<assembly-descriptor>
<c:clustering>
<ejb-name>DDBasedClusteredSFSB</ejb-name>
<c:clustered>true</c:clustered>
</c:clustering>
</assembly-descriptor>
</jboss:ejb-jar>Note
There are known issues with the
jboss-ejb3-spec-2_0.xsd that may result in schema validation errors. You can ignore these errors. For more information, see https://bugzilla.redhat.com/show_bug.cgi?id=1192591.
