Chapter 3. EJB Module

Table of Contents

3.1. Overview
3.2. Managing EJB Modules
3.3. Assembling EJB Modules
3.3.1. Compiling EJB Classes
3.3.2. Creating Deployment Descriptors
3.3.3. Packaging EJB JAR File
3.4. Deploying EJB Modules
3.4.1. Deployment
3.4.2. Directory Structure of Deployed EJB Module
3.5. Controlling and Monitoring EJB Modules
3.5.1. Controlling EJB Modules
3.5.2. Monitoring EJB Modules

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

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.

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

ClassificationDescription
ejb-jar.xmlThe 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.xmlThe DD needed when deploying EJB 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.

ClassificationDescription
InterfaceThe EJB 2.x, 3.0, or later style interface used for client access.
Enterprise Bean classBean classes that implement the actual business logic according to the interfaces.

Helper library

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

  1. Compile the EJB classes

    Compile the EJB source files implemented by the developer

  2. If necessary, create the DDs

    • Create ejb-jar.xml DD

    • Create jeus-ejb-dd.xml DD

  3. 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 Bean" and "Chapter 9. Message Driven Bean(MDB)".

There are two DDs that must be prepared before deploying an EJB module:

Creating standard EJB DDs (ejb-jar.xml)

The DD format complies with the EJB specification. Annotation is enough in most cases, but 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 is the ejb-jar.xml file, the standard DD, which describes the aforementioned annotations. The following example is a simple Java EE EJB DD of the counter bean.


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 when deploying 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. EJB Security Configuration" -->
            . . .
        </role-permission>
    </module-info>
    <beanlist>
        <jeusbean>
            <!-- See chapters "Chapter 4. Common Characteristics of EJB"
                 and "Chapter 7. Session Bean" -->
            . . .
        </jeusbean>
        <jeusbean>
            <!-- See chapters "Chapter 4. Common Characteristics of EJB"
                 and "Chapter 7. Session Bean" -->
            . . .
        </jeusbean>
            . . .
    </beanlist>
    <ejb-relation-map>
        <!-- See chapter "Chapter 8. Entity Bean" -->
    </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>1.2</specification-version>
        <implementation-version>1.2</implementation-version>
    </library-ref>

</jeus-ejb-dd> 
 


Main parts of JEUS EJB DD are as follows:

ElementDescription
<module-info>Specifies the information that is applied to all EJB modules. For more information about role assignment, refer to "4.2.6. EJB Security Configuration".
<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 Bean" to "Chapter 9. Message Driven Bean(MDB)".
<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.

This section describes how to deploy EJB modules.

In general, deployment may be accomplished through the console tool or WebAdmin by compiling EJB classes. However, using the appcompiler to precompile the classes can help reduce the deployment time. 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].

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 using the appcompiler, use the -f option with the deployment command in the console tool. The appcompiler does not work without this option.

For more information on the appcompiler tool, refer to JEUS Reference Book. "4.3. appcompiler".

Boot-time Deployment of an EJB Module

Boot time Deployment is deploying EJB modules to an EJB engine whenever MS boots. Boot-time deployment is applied to the applications deployed through DAS whenever MS is started. For more information about application deployment settings, refer to the deployment section inJEUS 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, domain 1, which is DAS, and server 1, which is 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.

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.

Deployment ModeDescription
EAR Deploy ModeWhen EAR file is deployed, the modules are placed under the directory created with the EAR file name.
Standalone Deploy ModeWhen JAR file is deployed, the file is placed under the "<jar file_name>_jar___" directory, which is under the root directory that has the JAR file name.
Exploded EAR Deploy ModeUnpacked EAR file is deployed.
Exploded Standalone Deploy ModeUnpacked JAR file is deployed.

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.

The status of the deployed EJB modules can be controlled and monitored. (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: through the console tool or through 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

To undeploy an EJB module,

Using the Console

The following control commands are available in the console tool. All the commands receive the EJB module ID as a parameter.

Following is a simple example illustrating how to undeploy an EJB module using the console tool:

  1. Executes the console tool.

    $ jeusadmin -host localhost:9736
  2. 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.
    JEUS7 Administration Tool
    To view help, use the 'help' command.
    [DAS]domain1.adminServer>

  3. To undeploy the countermod EJB module, enter the following:

    [DAS]domain1.adminServer> undeploy countermod
  4. 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

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

Both the WebAdmin and console tool can be used to monitor EJB modules. Compared to the WebAdmin, the console tool allows users to obtain more detailed information about the EJB module. When using the WebAdmin, some EJB module information can be monitored 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".