Table of Contents
This chapter describes EJB module structure and how to manage the modules.
EJB modules represent the deployable unit for a JEUS EJB engine. It is a concept of grouping EJB components and using deployment descriptors (hereafter DD) to describe the configuration settings. Even if you are only deploying one Enterprise JavaBean, it must be packaged in an EJB module.
Note
A DD (ejb-jar.xml) is required for components of EJB 2.1 or earlier. However, for components of EJB 3.0 or later, DD is optional because annotation is supported.
The following figure shows the four main activities involved when managing an EJB module in JEUS. For more detailed information, refer to each section.
-
assembly: "3.3. Assembling EJB Modules"
-
deployment: "3.4. Deploying EJB Modules"
-
control (undeployment, redeployment, stop-application, start-application): "3.5.1. Controlling EJB Modules"
-
monitoring: "3.5.2. Monitoring EJB Modules"
The following figure shows the flow chart for managing EJB modules.
Structure of EJB Module JAR File
The following figure explains the structure of standard EJB module JAR file.
- META-INF
-
Classification Description ejb-jar.xml Actual standard EJB DD. It may not exist if annotation is used to describe configuration information. It is required for EJB 2.x style. jeus-ejb-dd.xml DD needed when EJB is deployed to JEUS (optional). - <package name>/
-
Contains the EJB classes. They must be organized to reflect the Java package hierarchy as defined in the EJB source code. Example: if an EJB declares that it is part of the package called "mypackage", the EJB classes must reside directly beneath a directory named "mypackage" in the EJB JAR file.
The following table describes the components of EJB.
Classification Description Interface EJB 2.x, 3.0, or later style interface used for client access. Enterprise Bean class Bean classes that implement the actual business logic according to the interfaces. - Helper library
-
Library defined in the MANIFEST.MF Class-Path entry.
As we see in the [Figure 3.1], steps for assembling an EJB module are as follows:
-
Compile the EJB classes
Compile the EJB source files implemented by the developer
-
If necessary, create the DDs
-
Create ejb-jar.xml DD
-
Create jeus-ejb-dd.xml DD
-
-
Package the EJB JAR file
Package the EJB classes and DDs into a JAR file
We will illustrate the procedures by using a simple example bean called counter. The counter bean is a stateful session bean that resides in the JEUS_HOME/samples/ejb/basic/statefulSession/ directory. It contains the following two Java source files:
-
Counter.java (business interface)
-
CounterEJB.java (bean implementation)
Note
For more information about stateful session beans and the other bean types, refer to "Chapter 7. Session Beans" and "Chapter 9. Message Driven Beans (MDBs)".
The first step in assembling an EJB module from existing EJB source files is to compile the source files. This is accomplished by using the JDK javac compiler. Default classpath is JEUS_HOME/lib/system/javaee.jar, but if you are using annotation that corresponds to the jeus-ejbdd.xml file, set the classpath to JEUS_HOME/lib/system/jeusapi.jar. If there are other helper classes, add them all to the classpath.
The following example shows how to compile EJB Java files for the counter bean in a Unix environment.
$ javac –classpath JEUS_HOME/lib/system/javaee.jar *.java
The previous command will create the class files.
There are two DDs that must be prepared before deploying an EJB module:
-
DD with the name, ejb-jar.xml, placed in the META-INF directory of the EJB module. Some or all parts of configuration information can be created using annotation when you create the EJB components. If you want to apply DD setting without using annotation, set the <metadata-complete> attribute in ejb-jar.xml as true. If annotation and DDs are used together, DD settings override the annotation settings.
-
DD with the name, jeus-ejb-dd.xml, placed in the META-INF directory of the EJB module. For more information, refer to "Creating jeus-ejb-dd.xml DD".
Creating standard EJB DDs (ejb-jar.xml)
The DD format complies with the EJB specification. Annotation is enough in most cases, but a DD can be used when necessary.
package ejb.basic.statefulSession;
@Remote
public interface Counter
{
public void increase();
...
}
package ejb.basic.statefulSession;
@Stateful
@EJB(name="counter")
@TransactionManagement( TransactionManagementType.BEAN)
public class CounterEJB implements Counter {
private int count = 0;
public void increase()
{
count++;
}
...
}
The following example is a simple Java EE EJB DD of the counter bean.
[Example 3.1] DD in the EJB Specification: <<ejb-jar.xml>>
<?xml version="1.0"?>
<ejb-jar version="3.2" xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/ejb-jar_3_2.xsd">
<enterprise-beans>
<session>
<ejb-name>counter</ejb-name>
<business-remote>ejb.basic.statefulSession.Counter</business-remote>
<ejb-class>ejb.basic.statefulSession.CounterEJB</ejb-class>
<session-type>Stateful</session-type>
<transaction-type>Bean</transaction-type>
</session>
</enterprise-beans>
<assembly-descriptor/>
</ejb-jar>
Note
For EJB 3.0 or later, ejb-jar.xml is optional because all contents of ejb-jar.xml can be described using annotation.
Creating JEUS EJB DD (jeus-ejb-dd.xml)
The main reason for creating JEUS EJB DD is to map the basic settings and external references, which are needed for deployment to an EJB engine. Instance pooling, entity bean, and DB table mappings are also configured in the DD.
Note
Such settings are needed to deploy EJB modules according to JEUS, but some parts can be configured using annotation. Also, since they can be deployed using the default values without the jeusejb- dd.xml file, this file is only necessary when separate environment settings are needed.
JEUS EJB DDs are additional settings added to the standard Java EE DDs. Like the standard EJB DDs, JEUS EJB DDs are also applied to an EJB module.
[Example 3.2] JEUS EJB DD: <<jeus-ejb-dd.xml>>
<?xml version="1.0"?>
<jeus-ejb-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<module-info>
<role-permission>
<!-- See chapter "4.2.6. Configuring EJB Security" -->
. . .
</role-permission>
</module-info>
<beanlist>
<jeusbean>
<!-- See chapters "Chapter 4. Common Characteristics of EJB"
and "Chapter 7. Session Beans" -->
. . .
</jeusbean>
<jeusbean>
<!-- See chapters "Chapter 4. Common Characteristics of EJB"
and "Chapter 7. Session Beans" -->
. . .
</jeusbean>
. . .
</beanlist>
<ejb-relation-map>
<!-- See chapter "Chapter 8. Entity Beans" -->
</ejb-relation-map>
<message-destination>
<jndi-info>
<ref-name>ejb/AccountEJB</ref-name>
<export-name>ACCEJB</export-name>
</jndi-info>
</message-destination>
<library-ref>
<library-name>jsf</library-name>
<specification-version>
<value>1.2</value>
</specification-version>
<implementation-version>
<value>1.2</value>
</implementation-version>
</library-ref>
</jeus-ejb-dd>
The following are the main elements of a JEUS EJB DD:
| Element | Description |
|---|---|
| <module-info> | Specifies the information that is applied to all EJB modules. For more information about role assignment, refer to "4.2.6. Configuring EJB Security". |
| <beanlist> | Defines EJBs included in the EJB module. The name and content of this element can have various features according to the bean type (SessionBean. Entity Bean, and MDB). For more information about <beanlist> and its child tags, refer to "Chapter 4. Common Characteristics of EJB" and from "Chapter 7. Session Beans" to "Chapter 9. Message Driven Beans (MDBs)". |
| <ejb-relation-map> | Configures EJB relationship mappings that define CRM mappings for CRM 2.0 beans. Since using CMP is no longer recommended, use JPA instead. |
| <message-destination> | Maps message destination defined in the <message-destination> element of ejb-jar.xml and the actual destination object registered with JNDI. |
| <library-ref> | Configures the shared library information that is used by the application. |
The following explains how to package EJB classes and DDs into a JAR file.
You can create an EJB JAR file using a JAR utility. We assume that:
-
The counter EJB class files reside in the ejb/basic/statefulSession directory.
-
The ejb-jar.xml and jeus-ejb-dd.xml do not exist because annotations are used in the classes.
The following explains how to pack an EJB JAR file.
-
Pack the EJB classes into a JAR file as follows.
$ jar cf countermod.jar ejb/basic/statefulSession counterbeanclient.jar
The JAVA EE EJB module named countermod.jar is created.
-
In order to use this EJB in a client, you need an interface file. Create the counterbeanclient.jar file, which will be distributed for client use, as follows:
$ jar cf counterbeanclient.jar ejb/basic/statefulSession/Counter.class
Note
The counterbeanclient.jar is a library distributed for remote clients to use.
This section describes how to deploy EJB modules.
In general, deployment may be accomplished through the console tool or WebAdmin by compiling EJB classes. But you can reduce the deployment time by using the appcompiler to precompile the classes. You can also use the Auto Deploy function for easy deployment of EJB modules. For more information about deployment, refer to "JEUS Applications & Deployment Guide".
EJB modules are deployed on JEUS by using the following methods as described in [Figure 3.1].
-
For EJB 2.x modules, the stub and skeleton files can be created in advance by using the appcompiler tool, speeding up the deployment process.
-
EJB modules are automatically deployed to an EJB engine whenever the engine boots.
-
Runtime Deployment of an EJB Module
EJB modules are deployed to an already running EJB engine using the console tool or WebAdmin.
Using the appcompiler Tool
For EJB 2.x modules, stub and skeleton files can be created in advance by using the appcompiler tool, speeding up the deployment.
When you are using the appcompiler tool, specify the -f option with the deployment command in the console tool. Without this option, the appcompiler tool does not work.
For more information about the appcompiler tool, refer to JEUS Reference Book. "4.3. appcompiler".
Boot-time Deployment of an EJB Module
Boot-time Deployment refers to deploying EJB modules to an EJB engine whenever an MS boots. Boot-time deployment is applied to the applications deployed through DAS. For more information about application deployment settings, refer to the deployment section in JEUS Applications & Deployment Guide. "Chapter 4. Application Implementation and Deployment".
Multiple applications can be registered to a single domain.
Runtime Deployment of an EJB module
Runtime-deployment is an act of actually deploying an EJB module to an already running EJB engine. By using the deploy command in the console tool, an EJB module can be installed to a running EJB engine.
The following explains how the countermod EJB module is deployed. The following assumes that:
-
On JEUS, adminServer (DAS) and server 1 (MS) are already running.
-
The countermod module exists in the form of countermod.jar file or countermod directory under the JEUS_HOME/apphome directory.
EJB module's runtime deployment is done using the console tool or WebAdmin.
-
Using WebAdmin
To deploy an EJB module,
-
Click [Applications] on the left pane to go to the Application List page. Select an application from the list to deploy and click [Deploy].
-
Click [Lock & Edit] to change to the edit mode.
-
Set the required deployment properties and then click [OK].
Note
For more information about deployment settings, refer to the deployment section in JEUS Applications & Deployment Guide. "Chapter 4. Application Implementation and Deployment".
-
The deployed application can be controlled when the [Stop], [Undeploy], [Redeploy], [Add Target] and [Remove Target] buttons become available in the rightmost column. For more information about the function of each button, refer to "3.5.1. Controlling EJB Modules".
-
-
Using the Console Tool
To deploy an EJB module.
-
Execute the console tool. For more information about the console tool, refer to JEUS Reference Book. "4.2.2. Local Commands".
$ jeusadmin -host localhost:9736
-
Enter the user name and password.
User name: administrator Password: Attempting to connect to localhost:9736. The connection has been established to Domain Administration Server adminServer in the domain domain1. JEUS8 Administration Tool To view help, use the 'help' command. [DAS]domain1.adminServer>
-
Deploy the countermod EJB module using the deploy command.
[DAS]domain1.adminServer> deploy countermod -servers server1
-
In order to verify the deployment result, execute the following command. All the deployed applications, including the countermod module, are displayed.
[DAS]domain1.adminServer> application-info
-
After an EJB module has been deployed, its class files and configuration files will be distributed throughout the JEUS installation directory as shown in the following figure.
JEUS_HOME/domains/<domain name>/servers/<server name>/.workspace/deployed/ directory contains applications deployed to the MS specified by the <server name> option. It will contain deployed EJB implementation classes of the EJB module as well as helper classes.
Deployed files are placed in the following directories.
For Exploded EAR deployment and Exploded Standalone deployment, the reference to the original directory is used, instead of copying the files to the webhome directory. JEUS classifies deploying the packaged archive file as a COMPONENT type and deploying the directory with the unpacked files as an EXPLODED COMPONENT type.
Note
From here on, we will only discuss the standalone modules. For additional information about EAR deployment mode or detailed information about deployment, please refer to the deployment section of the "JEUS Applications & Deployment Guide".
You can control and monitor the status of the deployed EJB modules. (refer to [Figure 3.1].)
In order to control the runtime status of EJBs of an EJB module, you can use the stop-application, start-application, redeploy-application, and undeploy commands. There are mainly two ways to control a deployed EJB module: using the console tool or the GUI admin tool called WebAdmin.
-
Controlling EJB modules using the WebAdmin
-
Controlling EJB modules using the console tool
This section will explain how to control an EJB module using the undeploy command.
Using WebAdmin
EJB modules can be controlled and monitored
The following are the steps for undeploying an EJB module.
-
Click [Applications] on the left pane to go to the Deployed Applications page. The buttons for the deployed application represents each command available in the console tool.
Select an application from the list to undeploy and click [Undeploy].
-
When the Undeploy screen appears, set the 'Timeout' option. If an application receives a request to undeploy, while it has pending requests, the undeploy request waits for the specified amount of time. Click [OK] to start undeployment.
Note
The 'Graceful' option determines which application will be undeployed when both an old application and a new application exist on the same domain.
-
When the application is successfully undeployed, the following message will appear. The 'State' and 'Command' columns of the application will also change.
Using the Console
The following control commands are available in the console tool. All the commands receive the EJB module ID as a parameter.
-
Reloads the specified EJB module. This means that the EJB module that is currently running will be discarded from the EJB engine’s runtime environment and then re-read/redeployed from the disk.
When the EJB module is redeployed, all the transactions performed by the EJB module will be rolled back together.
redeploy-application <application-id>
-
Suspends the specified EJB module. This means that the EJB module that is currently running will be temporarily inaccessible. The start-application command can make the EJB module accessible.
stop-application <application-id> -
Activates the EJB module which was suspended with the stop-application command.
start-application <application-id> -
Removes the selected EJB module from the EJB engine’s runtime memory so that the EJB clients are not able to access the EJB. However, the physical file is not deleted.
undeploy <application-id>
Following is a simple example illustrating how to undeploy an EJB module using the console tool:
-
Executes the console tool.
$ jeusadmin -host localhost:9736
-
Enter user name and password.
User name: administrator Password: Attempting to connect to localhost:9736. The connection has been established to Domain Administration Server adminServer in the domain domain1. JEUS8 Administration Tool To view help, use the 'help' command. [DAS]domain1.adminServer>
-
To undeploy the countermod EJB module, enter the following:
[DAS]domain1.adminServer> undeploy countermod
-
To verify the undeployment result, enter the following. The countermod module is not included in the list of deployed modules that is displayed.
[DAS]domain1.adminServer> application-info
Note
For more information about the console tool, refer to JEUS Reference Book. "4.2. jeusadmin".
EJB modules can be monitored using the console tool. To monitor the status and runtime information of an EJB module, execute the application-info command in the console tool. For more information about the application-info command, refer to JEUS Reference Book. "4.2.7. EJB Engine Commands".
-
Monitoring module information
Displays information about the module.
[DAS]domain1.adminServer>application-info -server server1 -id countermod -detail General information about the EJB module [countermod]. ============================================================== +-------------+----------------------------------------------+ | Module Name | Unique Module Name | +-------------+----------------------------------------------+ | countermod | countermod | +-------------+----------------------------------------------+ ============================================================== Beans ================================================================================ +-----------+-------------------------+-------------------+--------------------+ | Bean Name | Type | Local Export Name | Remote Export Name | +-----------+-------------------------+-------------------+--------------------+ | Count | StatelessSessionBean | | Count | +-----------+-------------------------+-------------------+--------------------+ ================================================================================
-
Monitoring EJB list
Displays a list of EJBs of the relevant module("application-id").
[DAS]domain1.adminServer>application-info -server server1 -id countermod -bean Count Module name : countermod Bean name : Count ================================================================================ +---------------+-----------+-------------------+--------------+---------------+ | Name | (Count) | WaterMark(High:Low| Bound(Upper:L| Time(Max:Min:T| | | | :Cur) | ower) | otal) | +---------------+-----------+-------------------+--------------+---------------+ | create | times(0) | | | | +---------------+-----------+-------------------+--------------+---------------+ | comitted | transactio| | | | | |n(0) | | | | +---------------+-----------+-------------------+--------------+---------------+ | total-remote-t| |thread(100:100:100)| | | |hread | | | | | +---------------+-----------+-------------------+--------------+---------------+ | timed-rb | transactio| | | | | |n(0) | | | | +---------------+-----------+-------------------+--------------+---------------+ | remove | times(0) | | | | +---------------+-----------+-------------------+--------------+---------------+ | active-bean | | bean(0:0:0) | | | +---------------+-----------+-------------------+--------------+---------------+ | request | request(0)| | | | +---------------+-----------+-------------------+--------------+---------------+ | total-bean | | bean(0:0:0) | | | +---------------+-----------+-------------------+--------------+---------------+ | rolledback | transactio| | | | | |n(0) | | | | +---------------+-----------+-------------------+--------------+---------------+ | active-thread | | thread(0:0:0) | | | +---------------+-----------+-------------------+--------------+---------------+ | MethodReadyCou| | bean(0:0:0) | | | |nt | | | | | +---------------+-----------+-------------------+--------------+---------------+ ================================================================================
Note
You can use both the WebAdmin and console tool can be used to monitor EJB modules. With the console tool, you can obtain more detailed information about the EJB module. With the WebAdmin, you can monitor some EJB module information by using the [JNDIs] or [EJBTimers] menu under the [Monitoring] menu. For more information about monitoring, refer to JEUS Server Guide. "4.2.2. Checking Bound Objects" and "10.2. Configuring Timer Monitoring".