Documentation, Enhance Quiesce for resources that must remain available while applications are stopping

Feature epic details

• For the title of this issue, type: Documentation, Development epic name
• Link to development epic: Enhance Quiesce for resources that must remain available while applications are stopping
• Target GA release: 26.0.0.10

Operating systems

Does the documentation apply to all operating systems?

• Yes
• No; specify operating systems: ______

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

See the beta blog post here: BETA BLOG - Support Added for Configuring Enterprise Beans Quiesce Behavior

There are 2 main points.... summarized in blog post as:

Environment entry that configures singleton bean destruction on server quiesce.
By default, a singleton bean is destroyed during application stop, which occurs after the server quiesce period that occurs when the server stop command is issued. Configuring an application to be notified of the beginning of the quiesce period can be useful to allow the application to begin shutting down before being stopped and avoid starting new work while the server is stopping. A Boolean environment entry can be added for a singleton bean to force destruction prior to the server quiesce period.

Environment entry that configures message endpoint deactivation on server quiesce.
By default, a message endpoint is deactivated during the quiesce period after the server stop command is issued to prevent additional messages from being delivered while the server is stopping. A Boolean environment entry can be added for a message-driven bean to skip message endpoint deactivation during the server quiesce period.

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:

See the beta blog post here: BETA BLOG - Support Added for Configuring Enterprise Beans Quiesce Behavior

There are two new properties that may be specified as environment entries:

1. io.openliberty.ejb.destroyOnQuiesce
2. io.openliberty.ejb.deactivateOnQuiesce

See the blog post for examples of how to configure them; supported values

Updates to existing topics

To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ

It would be nice if a link could be added from the server stop command page to the new page below:

Page to update : https://openliberty.io/docs/latest/reference/command/server-stop.html

Add the following sentence in the top section just prior to "Usage examples":

An application can be configured to be notified when the server quiesce stage starts and to control the behavior for message-driven bean deactivation. See "Configuring Enterprise Beans Quiesce Behavior" (new page below)

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.

Please add two new topics to the open-liberty documentation using the following navigation:

DEVELOPMENT
 Jakarta Enterprise Beans (EJB)
  Configuring Enterprise Beans Quiesce Behavior

And here are the proposals for the 2 new topics:

---

Jakarta Enterprise Beans (EJB)

Overview of Jakarta Enterprise Beans (EJB)

An enterprise bean is a Java component that can be combined with other resources to create Java applications. There are two types of enterprise beans supported by Liberty, session beans, and message-driven beans.

All beans reside in Enterprise JavaBeans (EJB) containers, which provide an interface between the beans and the application server on which they reside.

An Enterprise Beans application (EJB) is a set of beans that are packaged as a combination of a Java™ archive file (JAR), web application archive file (WAR), or an enterprise application archive file (EAR). Liberty provides several features to enable support for Enterprise Bean applications.

Session beans overview

Session beans typically contain the high-level and mid-level business logic for an application. Each method on a session bean performs a particular high-level operation. For example, submitting an order or transferring money between accounts. Session beans often invoke methods on JPA entities in the course of their business logic.

Session beans can be singleton, stateful or stateless. A stateful bean instance is intended for use by a single client during its lifetime, where the client performs a series of method calls that are related to each other in time for that client. One example is a shopping cart where the client adds items to the cart over the course of an online shopping session. In contrast, a stateless bean instance is typically used by many clients during its lifetime, so stateless beans are appropriate for business logic operations that can be completed in the span of a single method invocation. Stateful beans should be used only where absolutely necessary. Using stateless beans improves the ability to debug, maintain, and scale the application.

The EJB 3.0 specification simplifies session beans. They often invoke method on JPA entities in the course of their business logic:

• Define the business interface (optional)
• Define the class that implements it.
• Add metadata with annotations or with XML deployment descriptors.

Singleton Session Beans

Introduced in the EJB 3.1 specification, a singleton session bean is instantiated once per application and exists for the lifecycle of the application. Singleton session beans are designed for circumstances in which a single enterprise bean instance is shared across and concurrently accessed by clients.

EJB annotations overview

Starting with the EJB 3.0 specification, all EJB configuration that can be specified in ejb-jar.xml may also be specified using annotations. There are two types of annotations:

• component defining annotations
• reference/injection annotations

EJB components, Web components, and application clients can use annotations such as @EJB and @Resource to declare EJB and resource references and the injection of those references. For EJB references defined either in ejb-jar.xml or with the @EJB annotation, the application may allow the EJBContainer to dynamically bind the reference to the EJB (auto-link) if the referenced bean is located in the same enterprise archive (EAR) file. Otherwise, the application must provide a binding for the reference in either the ibm-ejb-jar-bnd.xml file or ibm-web-bnd.xml file (which may be set during application install). For more information about reference bindings, see the topic "EJB 3.0 and EJB 3.1 application bindings overview" in the Knowledge Center. The reference to that page can be found below in the "Related information" section.

EJB implementation classes may be configured using the @Stateless, @Stateful, @Singleton, and @MessageDriven annotations. The interfaces for an EJB may be configured using @Local, @Remote, @LocalHome, @RemoteHome and @LocalBean. There are several other component defining annotations related to transaction settings, timers, lifecycle, etc.

Message driven beans overview

Message-driven beans enable asynchronous message servicing.

• The EJB container and a Java Message Service (JMS) provider work together to process messages. When a message arrives from another application component through JMS, the EJB container forwards it through an onMessage method call to a message-driven bean instance, which then processes the message. In other respects, message-driven beans are similar to stateless session beans.
• The EJB container and a Java Connector Architecture (JCA) resource adapter work together to process messages from an enterprise information system (EIS). When a message arrives from an EIS, the resource adapter receives the message and forwards it to a message-driven bean, which then processes the message. The message-driven bean is provided services such as transaction support by the EJB container in the same way that other enterprise beans are provided service.

EJBContainer overview

An Enterprise JavaBeans (EJB) container provides a run-time environment for enterprise beans within the application server. The container handles all aspects of an enterprise bean's operation within the application server and acts as an intermediary between the user-written business logic within the bean and the rest of the application server environment.

One or more EJB modules, each containing one or more enterprise beans, can be installed in a single container.

The EJB container provides many services to the enterprise bean, including the following:

• Transaction Management : beginning, committing, and rolling back transactions as necessary.
• Lifecycle Management : maintaining pools of enterprise bean instances ready for incoming requests and moving these instances between the inactive pools and an active state, ensuring that threading conditions within the bean are satisfied.
• JNDI Access
• Security Services : The container enforces data protection and access controls implicitly, supporting role-based authorization.
• Asynchronous Services : allows methods to execute asynchronously in the background using the @Asynchronous annotation.
• Timer Service: supports automatic and programmatic scheduling of timers.

By dynamically maintaining a set of active bean instances and synchronizing bean state with persistent storage when beans are moved into and out of active state, the container makes it possible for an application to manage many more bean instances than could otherwise simultaneously be held in the application server's memory. In this respect, an EJB container provides services similar to virtual memory within an operating system.

Features providing capabilities of the Enterprise Beans APIs

The following features provide the minimum set of capabilities for the Enterprise Beans APIs.

ejbLite
enterpriseBeansLite

This feature enables the lite subset of the enterprise beans technology as defined in the Enterprise Beans specification. This subset includes support for local session beans that are written to the Enterprise Beans 3.x APIs. Beginning with the ejbLite-3.2 feature, the subset also includes support for nonpersistent enterprise bean timers and asynchronous local interface methods.

Other than enabling the feature in the server.xml file, no additional configuration is required for this feature.

mdb

This feature enables the message-driven bean subset of the enterprise beans technology, which is similar to the support that the ejbLite and enterpriseBeansLite features enable for session beans. The feature does not enable session beans, so if both session and message-driven beans are needed, then both features need to be enabled in the server.xml file.

The following features provide extensions to the core Enterprise Beans features, which, when they are combined, support the full set of Enterprise Beans APIs:

ejbHome
enterpriseBeansHome

This feature enables support of the Enterprise Beans 2.x APIs, specifically, support for the javax.ejb.EJBLocalHome interface. The javax.ejb.EJBHome interface is also supported when combined with the ejbRemote or enterpriseBeansHome features. Since this feature is not useful without the corresponding ejbLite or enterpriseBeansLite feature, enabling this feature automatically enables the corresponding ejbLite or enterpriseBeansLite feature.

Other than enabling the feature in the server.xml file, no additional configuration is available for this feature, unless application security (for example, the appSeciruty-2.0 feature) is also enabled. When application security is enabled, more security configuration is required. For more information, see Getting started with security in Liberty.

ejbPersistentTimer
enterpriseBeansPersistentTimer

This feature enables support for persistent Enterprise Beans timers. Enabling this feature automatically enables the corresponding ejbLite feature.

In addition to enabling this feature in the server.xml file, a data source must also be configured to provide the persistent store for the timers. By default, the DefaultDataSource data source is used.

ejbRemote
enterpriseBeansRemote

This feature enables support for remote Enterprise Beans interfaces. Enabling this feature automatically enables the corresponding ejbLite feature.

Other than enabling the feature in the server.xml file, no additional configuration is required for this feature.

The following feature provides a convenient way to enable the full set of Enterprise Beans APIs:

ejb
enterpriseBeans

This feature enables all of the core and extension features for the specification level of the configured feature. For example, ejb-3.1 enables ejbLite-3.1 and mdb-3.1. This feature provides no additional support beyond what is provided by enabling all of the core and extension Enterprise Beans features.

Other than enabling the feature in the server.xml file, no additional configuration is required for this feature beyond what is required for the ejbPersistentTimer, enterpriseBeansPersistentTimer, ejbRemote, and enterpriseBeansRemote features.

The following convenience features include Enterprise Beans features.

webProfile

This feature enables all features that are required for the Java EE or Jakarta EE Web Profile, which includes either the ejbLite or enterpriseBeansLite feature.

javaee
jakartaee

This feature enables all features that are required for the Java EE or Jakarta EE Full Profile, which includes either the ejb or enterpriseBeans convenience feature.

Note: Enterprise Beans 2.x API entity beans are not supported by Liberty. For persistence, the Java Persistence API (JPA) must be used instead.

---

Configuring Enterprise Beans Quiesce Behavior

Environment entry that configures singleton bean destruction on server quiesce.

By default, a singleton bean is destroyed during application stop, which occurs after the server quiesce period that occurs when the server stop command is issued. Configuring an application to be notified of the beginning of the quiesce period can be useful to allow the application to begin shutting down before being stopped and avoid starting new work while the server is stopping. A Boolean environment entry can be added for a singleton bean to force destruction prior to the server quiesce period.

Syntax for the environment entry is:

    <session>
        <ejb-name>SingletonQuiesceBean</ejb-name>
        <env-entry>
            <env-entry-name>io.openliberty.ejb.destroyOnQuiesce</env-entry-name>
            <env-entry-type>java.lang.Boolean</env-entry-type>
            <env-entry-value>true</env-entry-value>
        </env-entry>
    </session>

When this environment entry is not configured, or is configured with the value of "false", the singleton bean will be destroyed during application stop after the server quiesce period. If the configured value is "true", singleton bean destruction will occur at the beginning of the server quiesce period.

Since this is a custom environment property, defining the environment entry with @Resource or <env-entry> in ejb-jar.xml is not required. Providing the environment entry binding in ibm-ejb-jar-bnd.xml or in <ejb-jar-bnd> in server.xml will override the default value of the property.

Syntax for environment entry binding in ibm-ejb-jar-bnd.xml:

    <session name="SingletonQuiesceBean" simple-binding-name="SingletonQuiesce">
        <env-entry name="io.openliberty.ejb.destroyOnQuiesce" value="true"/>
    </session>

Syntax for environment entry binding in server.xml:

    <webApplication location="sample-application.war">
        <ejb-jar-bnd>
            <session name="SingletonQuiesceBean" simple-binding-name="SingletonQuiesce">
                <env-entry name="io.openliberty.ejb.destroyOnQuiesce" value="true"/>
            </session>
        </ejb-jar-bnd>
    </webApplication>

Note: this setting is not supported in web.xml, ibm-web-bnd.xml, or web-bnd in server.xml. Values configured in these locations will be ignored.

Note: if the singleton bean is configured for destruction during the server quiesce period but the --force option is used on the server stop commend, then the quiesce period will be skipped and the singleton bean will be destroyed when the application is stopped.

Environment entry that configures message endpoint deactivation on server quiesce.

By default, a message endpoint is deactivated during the quiesce period after the server stop command is issued to prevent additional messages from being delivered while the server is stopping. A Boolean environment entry can be added for a message-driven bean to skip message endpoint deactivation during the server quiesce period.

Syntax for the environment entry is:

    <session>
        <ejb-name>MessageBean</ejb-name>
        <env-entry>
            <env-entry-name>io.openliberty.ejb.deactivateOnQuiesce</env-entry-name>
            <env-entry-type>java.lang.Boolean</env-entry-type>
            <env-entry-value>false</env-entry-value>
        </env-entry>
    </session>

When this environment entry is not configured, or is configured with the value of "true", the message endpoint will be deactivated during the server quiesce period. If the configured value is "false", message endpoint deactivate will be deferred until application stop, after the "@PreDestory" method has been called on all "@Startup" singleton beans in the application.

Since this is a custom environment property, defining the environment entry with @Resource or <env-entry> in ejb-jar.xml is not required. Providing the environment entry binding in ibm-ejb-jar-bnd.xml or in <ejb-jar-bnd> in server.xml will override the default value of the property.

Syntax for environment entry binding in ibm-ejb-jar-bnd.xml:

    <message-driven name="MessageBean">
        <env-entry name="io.openliberty.ejb.deactivateOnQuiesce" value="false"/>
    </message-driven>

Syntax for environment entry binding in server.xml:

    <webApplication location="sample-application.war">
        <ejb-jar-bnd>
            <message-driven name="MessageBean">
                <env-entry name="io.openliberty.ejb.deactivateOnQuiesce" value="false"/>
            </message-driven>
        </ejb-jar-bnd>
    </webApplication>

Note: this setting is not supported in web.xml, ibm-web-bnd.xml, or web-bnd in server.xml. Values configured in these locations will be ignored.

Note: if the message endpoint is configured to deactivate during the server quiesce period but the --force option is used on the server stop commend, then the quiesce period will be skipped and the message endpoint will be deactivated when the application is stopped.