Appendix A. Reference Material
A.1. Jakarta Enterprise Beans Java Naming and Directory Interface Reference
The Java Naming and Directory Interface lookup name for a session bean uses the following syntax:
ejb:<appName>/<moduleName>/<distinctName>/<beanName>!<viewClassName>?stateful
-
<appName>
: If the session bean’s JAR file has been deployed within an enterprise archive (EAR) then theappName
is the name of the respective EAR. By default, the name of an EAR is its file name without the.ear
suffix. The application name can be overridden in itsapplication.xml
file. If the session bean is not deployed in an EAR, then leave theappName
blank. -
<moduleName>
: ThemoduleName
is the name of the JAR file in which the session bean is deployed. The default name of the JAR file is its file name without the.jar
suffix. The module name can be overridden in the JAR’sejb-jar.xml
file. -
<distinctName>
: JBoss EAP allows each deployment to specify an optional distinct name. If the deployment does not have a distinct name, then leave thedistinctName
blank. -
<beanName>
: ThebeanName
is the simple class name of the session bean to be invoked. -
<viewClassName>
: TheviewClassName
is the fully qualified class name of the remote interface. This includes the package name of the interface. -
?stateful
: The?stateful
suffix is required when the Java Naming and Directory Interface name refers to a stateful session bean. It is not included for other bean types.
For example, if we deployed hello.jar
having a stateful bean org.jboss.example.HelloBean
that exposed a remote interface org.jboss.example.Hello
, then the Java Naming and Directory Interface lookup name would be:
ejb:/hello/HelloBean!org.jboss.example.Hello?stateful"
A.2. Jakarta Enterprise Beans Reference Resolution
This section covers how JBoss EAP 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 amappedName()
attribute. The specification leaves this as vendor specific metadata, but JBoss EAP recognizesmappedName()
as the global Java Naming and Directory Interface name of the Jakarta Enterprise Beans you are referencing. If you have specified amappedName()
, then all other attributes are ignored and this global Java Naming and Directory Interface name is used for binding. If you specify
@EJB
with no attributes defined:@EJB ProcessPayment myEjbref;
Then the following rules apply:
-
The Jakarta Enterprise Beans JAR of the referencing bean is searched for Jakarta Enterprise Beans with the interface used in the
@EJB
injection. If there are more than one Jakarta Enterprise Beans 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 Jakarta Enterprise Beans that publish that interface. If there are duplicates, then an exception is thrown. Otherwise the matching bean is returned.
- Search globally in JBoss EAP runtime for an Jakarta Enterprise Beans of that interface. Again, if duplicates are found, an exception is thrown.
-
The Jakarta Enterprise Beans JAR of the referencing bean is searched for Jakarta Enterprise Beans with the interface used in the
-
@EJB.beanName()
corresponds to<ejb-link>
. If thebeanName()
is defined, then use the same algorithm as@EJB
with 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: it allows you to put a relative path to a JAR in the EAR where the Jakarta Enterprise Beans you are referencing is located. Refer to the Jakarta Enterprise Beans 3.2 specification for more details.
-
The
A.3. Project Dependencies for Remote Jakarta Enterprise Beans Clients
Maven projects that include the invocation of session beans from remote clients require the following dependencies from the JBoss EAP Maven repository. There are two ways to declare Jakarta Enterprise Beans client dependencies, as described in the sub-sections below.
The artifactId
versions are subject to change. See the JBoss EAP Maven Repository for the latest versions.
Maven Dependencies for Remote Jakarta Enterprise Beans Clients
The jboss-eap-jakartaee8
Bill of Materials (BOM) packages the correct version of many of the artifacts commonly required by a JBoss EAP application. The BOM dependency is specified in the <dependencyManagement>
section of the pom.xml
with the scope of import
.
Example: POM File <dependencyManagement>
Section
<dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.bom</groupId> <artifactId>jboss-eap-jakartaee8</artifactId> <version>7.4.0.GA</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>
The remaining dependencies are specified in the <dependencies>
section of the pom.xml
file.
Example: POM File <dependencies>
Section
<dependencies> <!-- Include the Enterprise Java Bean client JARs --> <dependency> <groupId>org.jboss.eap</groupId> <artifactId>wildfly-ejb-client-bom</artifactId> <type>pom</type> </dependency> <!-- Include any additional dependencies required by the application ... --> </dependencies>
The ejb-remote
quickstart that ships with JBoss EAP provides a complete working example of remote Jakarta Enterprise Beans client application. See the client/pom.xml
file located in root directory of that quickstart for a complete example of dependency configuration for remote session bean invocation.
Single artifactID for jboss-ejb-client Dependencies
You can use the wildfly-ejb-client-bom
artifactID
and add the jboss-ejb-client
library to include all the required dependencies for Jakarta Enterprise Beans clients:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.eap</groupId>
<artifactId>wildfly-ejb-client-bom</artifactId>
<version>JAKARTA_ENTERPRISE_BEANS_CLIENT_BOM_VERSION</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss</groupId>
<artifactId>jboss-ejb-client</artifactId>
</dependency>
</dependencies>
You must use the JAKARTA_ENTERPRISE_BEANS_CLIENT_BOM_VERSION that is available in the JBoss EAP Maven repository.
A.4. jboss-ejb3.xml Deployment Descriptor Reference
jboss-ejb3.xml
is a custom deployment descriptor that can be used in either Jakarta Enterprise Beans JAR or WAR archives. In a Jakarta Enterprise Beans 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
. See http://xmlns.jcp.org/xml/ns/javaee/ for documentation on the standard namespaces.
The root namespace is http://xmlns.jcp.org/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 a wildcard (*
) as theejb-name
. - The security namespace (
urn:security
) xmlns:s="urn:security"
This allows you to set the
security-domain
and therun-as-principal
for an Jakarta Enterprise Beans.<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>
<?xml version="1.1" encoding="UTF-8"?> <jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee" xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-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> </jboss:ejb-jar>
NoteThere are known issues with the
jboss-ejb3-spec-2_0.xsd
file 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.
A.5. Configure a Jakarta Enterprise Beans Thread Pool
You can create an Jakarta Enterprise Beans thread pool using the management console or the management CLI.
A.5.1. Configuring an Jakarta Enterprise Beans Thread Pool Using the Management Console
Procedure
- Log in to the management console.
-
Navigate to Configuration
Subsystems EJB and click View. -
Select Container
Thread Pool. - Click Add and specify the Name and Max Threads values.
- Click Save.
A.5.2. Configure an Jakarta Enterprise Beans Thread Pool Using the Management CLI
Procedure
Use the
add
operation with the following syntax:/subsystem=ejb3/thread-pool=THREAD_POOL_NAME:add(max-threads=MAX_SIZE)
-
Replace
THREAD_POOL_NAME
with the required name for the thread pool. -
Replace
MAX_SIZE
with the maximum size of the thread pool.
-
Replace
Use the
read-resource
operation to confirm the creation of the thread pool:/subsystem=ejb3/thread-pool=THREAD_POOL_NAME:read-resource
To reconfigure all the services in the
ejb3
subsystem to use a new thread pool, use the following commands:/subsystem=ejb3/thread-pool=bigger:add(max-threads=100, core-threads=10) /subsystem=ejb3/service=async:write-attribute(name=thread-pool-name, value="bigger") /subsystem=ejb3/service=remote:write-attribute(name=thread-pool-name, value="bigger") /subsystem=ejb3/service=timer-service:write-attribute(name=thread-pool-name, value="bigger") reload
XML Configuration Sample:
<subsystem xmlns="urn:jboss:domain:ejb3:5.0"> ... <async thread-pool-name="bigger"/> ... <timer-service thread-pool-name="bigger" default-data-store="default-file-store"> ... <remote connectors="http-remoting-connector" thread-pool-name="bigger"/> ... <thread-pools> <thread-pool name="default"> <max-threads count="10"/> <core-threads count="5"/> <keepalive-time time="100" unit="milliseconds"/> </thread-pool> <thread-pool name="bigger"> <max-threads count="100"/> <core-threads count="5"/> </thread-pool> </thread-pools> ...
A.5.3. Jakarta Enterprise Beans Thread Pool Attributes
Jakarta Enterprise Beans thread pools can be configured using attributes to run more efficiently for specific configuration needs.
-
The
max-threads
attribute determines the total or maximum number of threads that the executor supports.
/subsystem=ejb3/thread-pool=default:write-attribute(name=max-threads, value=9) {"outcome" => "success"}
-
The
core-threads
attribute determines the number of threads that are kept in the executor’s pool. This includes idle threads. If thecore-threads
attribute is not specified, it will default to the value ofmax-threads
.
/subsystem=ejb3/thread-pool=default:write-attribute(name=core-threads, value=3) {"outcome" => "success"}
-
The
keepalive-time
attribute determines the amount of time that a non-core thread will be allowed to remain idle. After this time, the non-core thread is removed.
/subsystem=ejb3/thread-pool=default:write-attribute(name=keepalive-time, value={time=5, unit=MINUTES}) {"outcome"=> "success"}
-
To change the time without changing the units of time for the
keepalive-time
attribute, use the following command:
/subsystem=ejb3/thread-pool=default:write-attribute(name=keepalive-time.time, value=10) {"outcome"=> "success"}
Revised on 2024-01-17 05:24:45 UTC