EJB Engine

This chapter describes basic knowledge of the EJB engine. It also describes the top-level concepts of JEUS EJB, such as its structure, configuration, operation, monitoring, and tuning.

1. Overview

The JEUS EJB engine provides a runtime environment for EJB. The term EJB Container used in the EJB standard is equivalent to the term EJB engine that will be used throughout this manual. For more information about EJB modules and EJB deployment, refer to EJB Modules and Common Characteristics of EJB.

2. Key Features

The following explains major functions of the EJB engine.

  • EJB Engine and Managed Server (MS)

    A single EJB engine can exist on a MS. However, multiple EJB engines can exist on a single domain because multiple MSs can exist on a domain.

    Usually, multiple MSs and EJB engines are configured and executed across multiple machines (CPUs). The MSs are clustered and managed by MASTER. Such configuration is often referred to as a cluster of engines. This is desirable since it results in better system performance and higher reliability and safety. In EJB Clustering, EJB clustering will be described in detail.

  • Main EJB Engine Settings

    The main configuration file for the EJB engines is <ejb-engine> in domain.xml. More information will be discussed in Configuring the EJB Engine.

  • EJB Engine Logging

    Logs can be written on MSs according to the setting in domain.xml, but a user can also keep a separate EJB engine log (jeus.ejb). Even if a separate EJB engine log is used, the EJB engine log is also recorded in the MS log .

    When a file handler is configured in the log handler, the log file is created using the specified file name. It is also possible to display any log messages using a console handler. Normally, in this case, the log messages will be displayed on the command screen, where the MS was started, through the pipe.

    A user-generated user handler can also be registered. For more information, refer to Logging in JEUS Server Guide.

  • Active Management

    In active management, the EJB engine sends out email notifications to the administrator if a problem occurs in the EJB modules.

    For example, when a fatal error occurs, such as an infinite loop or deadlock due to an error in the Bean class implementation, the EJB engine detects the error and sends out a notification. Additionally, you can configure an error-policy to send a notification e-mail and display a message to recommend a restart of the MS, where the relevant EJB is running, for any abnormal activities. For detailed explanations about active management configuration, see Configuring the EJB Engine.

  • HTTP Invoke

    When a remote client looks up an EJB instance through the JNDI naming service, it will get back an EJB RMI stub that is used to invoke methods on the EJB. By default, this remote communication from stub to EJB is carried out through the RMI runtime. The RMI communication is based on a TCP socket, which has a constraint in an environment where there is a firewall because it requires a separate TMI communication port. In this case, a special communication mode called HTTP invoke mode is needed.
    In this mode, a RMI request from a remote client is wrapped with HTTP and sent to a web engine, which forwards the request to a servlet (jeus.rmi.http.ServletHandler) that handles RMI requests. The servlet sends the request to the RMI runtime, then calls an actual EJB method, and wraps and sends the result to the remote client. The HTTP invoke mode can be configured for each EJB engine or EJB component.

    If the HTTP invoke mode is configured in the <invoke-http> element of domain.xml, the mode is applied to all the modules in the EJB engine. The settings in jeus-ejb-dd.xml of the EJB module can only be applied to a specific EJB component. The settings in jeus-ejb-dd.xml takes precedence over those in domain.xml. For more information about configurations of domain.xml and jeus-ejb-dd.xml, see Configuring the HTTP Invocation Environment.

3. EJB Engine Directory Structure

The following figure shows directories and files used to manage EJB engines.

{JEUS_HOME}
    |--bin
    |   |--[01]appcompiler
    |   |--[01]jeusadmin
    |--domains
    |     |--<domain_name>
    |           |--config
    |           |    |--[X]domain.xml
    |           |--servers
    |                |--<server_name>
    |                       |--logs
    |                            |--[T]error.log
    |--lib
        |--schemas
             |--jakartaee
             |--jeus

* Legend
- [01]: binary or executable file
- [X] : XML document
- [J] : JAR file
- [T] : Text file
- [C] : Class file
- [V] : java source file
- [DD] : deployment descriptor

Basic directories are the same as Directory Structure. Main directories used by an EJB engine are as follows:

bin

Contains the tool for managing EJB engines.

EJB Engine Management Tool Description

appcompiler

Creates classes necessary to deploy EJB, compiles and fast deploys the classes.

jeusadmin

Used to control and monitor an EJB engine.
domains/<doamin name>/servers/<server name>/logs

The directory where the log files of EJB engine are stored. If a separate file handler is specified, a separate file will be created, otherwise, the setting in the server log configuration file will be followed.

4. Configuring the EJB Engine

This section explains how to configure EJB engines using domain.xml.

EJB engine configuration is divided into three sections as follows. The specified settings are stored in the domain.xml file, under the JEUS_HOME/domains/<domain name>/config directory.

There is one EJB engine in each MS. For details on how to add an MS, refer to JEUS Configuration in JEUS Server Guide.

4.1. Basic Configurations

The following example configures the basic settings of the EJB engine in domain.xml.

Configuring EJB Engine: <domain.xml>
<ejb-engine>
    <resolution>1000</resolution>
    <use-dynamic-proxy-for-ejb2>true</use-dynamic-proxy-for-ejb2>
    <enable-user-notify>false</enable-user-notify>
    <timer-service>
        <support-persistence>true</support-persistence>
        <max-retrial-count>1</max-retrial-count>
        <retrial-interval>5000</retrial-interval>
        <thread-pool>
            <min>2</min>
            <max>30</max>
            <period>3600000</period>
        </thread-pool>
    </timer-service>
    <async-service>
        <thread-min>0</thread-min>
        <thread-max>10</thread-max>
        <access-timeout>30000</access-timeout>
    </async-service>
</ejb-engine>

The following table describes the configuration items of Basic Options andAdvanced Options by section.

  • Basic Options

    Tag Description

    Use Dynamic Proxy For Ejb2

    Uses dynamic proxy instead of RMI stub.

    Resolution

    The interval for checking the active status of the EJB engine (activation/passivation). When Active Management is used, this checks the number of blocked threads. This also monitors the beans that have been idle for longer than the passivation timeout period.

  • Advanced Options

    • Ejb Engine

      Tag Description

      Enable User Notify

      Records EJB exceptions in the user log that is configured on the server. For more information about the user log, refer to Logging in JEUS Server Guide.

    • Async Service

      The following table describes the asynchronous service invocation options.

      Tag Description

      Thread Min

      The minimum number of threads that can be maintained.

      Thread Max

      The maximum number of threads that can be maintained.

      Access Timeout

      The waiting period before deleting the Future object if the client does not invoke the get method after an asynchronous method has finished processing.

      This prevents memory leaks that are caused by the client forgetting to call the get method.

    • Invoke Http

      This option is used when EJB RMI stubs cannot access an RMI runtime port.

      Tag Description

      HTTP Port

      Web server port to receive the HTTP-RMI requests. The RMI handler Servlet must be already deployed and running on this web server and web engine.

      Url

      This must be configured to the URI path of the RMI handler Servlet that will be invoked by the HTTP-RMI stub.

      • This URI only contains the request path of the Servlet, and excludes the protocol, Web server IP address, and the port number. You must set the <contex-path> option of jeus-web-dd.xml and <url-pattern> option of web.xml. If a separate jeus-web-dd.xml file is not created, the war file name, which is the default setting for the <context-path> option, is used (in the example, rmiHandlerServlet).

      • The protocol is implicitly set to HTTP and the IP address is assumed to be same as the IP address of the RMI runtime. This means that the Web server and the Web engine that will receive HTTP-RMI requests must be on the same machine as the RMI runtime. The address of the RMI runtime will be known to the RMI stub. The web server port must be configured in the <http-port> element.

      • The jeus-web-dd.xml file is not included in the rmiHandlerServlet.war, provided by JEUS. Therefore, by default, context uses rmiHadlerServlet, which has the same name as the module. A Servlet handler is set in the <url-pattern> element. If you want to use configuration other than the default one, create the jeus-web-dd.xml file, edit the web.xml file, and then deploy the rmiHandlerServlet.war file.

4.2. Configuring Active Management

Active Management setting consists of the engine restart and email notification options. Engine restart condition is determined according to the maximum number of blocked EJB threads allowed before the EJB engine is restarted.

The following example configures the Active Management setting of an EJB engine in domain.xml.

<ejb-engine>
    <resolution>1000</resolution>
    <use-dynamic-proxy-for-ejb2>true</use-dynamic-proxy-for-ejb2>
    <enable-user-notify>false</enable-user-notify>
    <active-management>
        <max-blocked-thread>-1</max-blocked-thread>
        <max-idle-time>300000</max-idle-time>
    </active-management>
</ejb-engine>

The following table describes the configuration items of Basic Options andAdvanced Options by section.

  • Basic Options

    Tag Description

    Max Blocked Thread

    Maximum number of blocked EJB threads allowed before recommending the restart of the EJB engine. If this number is set too low, the EJB engine restart will be recommended too often.

    The default value is set to -1, which means that there is no limit on the allowed number of blocked threads. This means that the EJB engine does not restart because of blocked threads.

    Max Idle Time

    Maximum idle time for EJB threads. If a thread remains idle for this time period, it will be added to the blocked thread list.

    This setting is used to determine if a thread is blocked.

  • Advanced Options

    • Email Notify

      Configures where to send an email message when the restart recommendation conditions trigger an EJB engine to restart.

      Tag Description

      SMTP Host Address

      Host address of the SMTP server.

      Sender ID

      ID to authenticate using SMTP address.

      Sender Password

      Password of the ID for authentication through the SMTP address.

      From Address

      Address of the sender.

      To Address

      Address of the recipient.

      CC Address

      Recipient of a carbon copy (CC).

      Bcc Address

      Recipient of a blind carbon copy (BCC).

      Property

      If there are other necessary properties besides the basic SMTP properties, they can be configured as key-value pairs.

4.3. Configuring Timer Service

The EJB timer service enables you to receive timer callback periodically or at a specified time. Refer to the EJB specifications for information about basic usage of the timer service. This chapter will cover the explanation and setting of the timer service in JEUS EJB. For more information, refer to EJB Timer Service.

5. Configuring System Logs

As system logging and user logging settings are common settings that apply not only to the EJB engine but also to all other engines, refer to Logging in JEUS Server Guide.

6. Controlling and Monitoring of EJB Engine

Controlling the EJB engine is similar to controlling other JEUS engines (servlet or JMS). You can monitor the execution environment information and status information of the EJB engine using the console tool. For more information, refer to EJB Engine Commands in JEUS Reference Guide.

7. Tuning the EJB Engine

There are a number of configuration settings that can be tweaked to increase the overall performance of individual JEUS EJB engines. In this section, we will briefly touch the following performance-related settings of the EJB engine.

The following are required for tuning purposes.

  • Tuning the engine resolution

  • Using the fast-deploy feature

  • Configuring system logs for optimal performance

  • Not using Active Management

  • Using the HTTP invoke mode

For more information or tips about the EJBMain.xml file, refer to "11. domain.xml EJB Engine Configuration" section of the JEUS XML Reference. In the XML/Schema, those names marked with 'P' are related to performance.

7.1. Tuning the Engine Resolution

Resolution checks for the EJB engine status are performed in the following two cycles.

  • Active management check cycle: Checks the number of blocked threads and then restarts the EJB engine.

  • Passivation check cycle: Checks all sub components (e.g. Bean pool) and checks whether each Bean should be inactivated.

Use a long resolution period for bette<par performance (by performing engine self-maintenance less often) at the expense of a less reliable engine that wastes system memory. If the value is low, the engine can be kept up-to-date but this will impact the overall performance. Therefore, it is very important to set an appropriate value.

Depending on the resolution value, <passivation-timeout> or <disconnect-timeout> may not be triggered at the expected time.

7.2. Using the Fast-Deploy Feature

The fast deployment option configured for each application instead of being configured in the EJBMain.xml file. Nevertheless, it has a significant effect on the system performance.

If the EJB modules that are to be deployed during engine boot-time have already been compiled to generate the RMI stubs and skeletons, you must use the -fast option when running the deploy command. This will cause the engine to skip RMI class generation during the EJB module deployment.

For more information about EJB modules and deployment, see EJB Modules.

7.3. Configuring System Logs for Optimal Performance

The system log settings can be tweaked in three ways for optimal performance:

  • If possible, it is better to use a file handler in order to improve logging performance.

  • Set a large value for the buffer size of the file handler.

  • Set the log level to SEVERE.

These suggestions only apply to a stable production environment. In the development environment, opposite settings might be preferred, e.g., using console handler, small buffer size, and the FINE log level.

7.4. Not Using Active Management

It is not necessary to use Active Management at the EJB engine level. By default, this setting is not used since it could lower the performance. Instead, it is more convenient to use Active Management defined in the Servlet engine. In most cases, Active Management is not configured in the EJBMain.xml file.

7.5. Using the HTTP Invoke Mode

Using the HTTP invoke mode can improve the performance when there are high number of requests. Web server controls the number of requests to JEUS by creating fewer connections than RMI, which creates a separate thread for each client request. But keep in mind that converting to HTTP protocol generally lowers the performance.