Graceful Undeployment and Redeployment

This chapter describes graceful undeployment and redeployment, which undeploys and redeploys an application after processing all current requests.

1. Graceful Undeployment

Graceful Undeployment undeploys an application after all user requests being processed are completed.

EAR, EJB, and web applications can process graceful undeployment. For EJB applications, only SessionBeans can process graceful undeployment.

If there are incomplete user requests when an application receives the undeploy command, the application waits for the requests to complete. The -gracefultimeout option can be used with the undeploy command. An application can be undeployed before all requests are completed, depending on the option value. When graceful timeout expires and there are incomplete requests, the application is undeployed by sending an interrupt signal to threads that are currently handling the requests.

When an application receives the undeploy command, it goes into the DISTRIBUTED state, where it cannot be executed. The application waits until the requests, which are being processed, are completed or the graceful timeout is reached. It is recommended for the user to set an appropriate -gracefultimeout option value. If the user does not specify the gracefultimeout option value, the default value of 5 minutes is used. This only guarantees the completion of requests in progress for 5 minutes.

Applications in the DISTRIBUTED state cannot handle external requests. EAR applications can handle internal requests, even after the process to undeploy the applications starts. If multiple Beans exist, standalone EJB applications can also handle requests from other Beans, even after the undeployment starts.

The following figure illustrates the execution of graceful undeployment.

Graceful Undeployment of an EAR Application

In the previous figure, when web calls ejb1, the request can be handled, because myApp.ear is in the RUNNING state. When ejb1 calls ejb2, the request might be rejected, because the application is in the DISTRIBUTED state. However, because the request was sent to the application internally, it must be guaranteed to be handled, even if the application is in the DISTRIBUTED state. If an external application calls ejb1 in myApp.ear, the request may be rejected depending on the state of myApp.ear.

The call stack which calls ejb1 from the web, and then calls ejb2 from ejb1 is actually a single request. That is, from the point of myApp.ear, calling ejb2 from ejb1 is not considered a new request, but an existing request, triggered from the web. Even when myApp.ear is in the DISTRIBUTED state, the internal request that calls ejb2 must not fail. The request must be successfully handled, and the application must be undeployed, after the request is complete. Because it may take a long time to handle the request, the application can be undeployed before the request is complete, depending on the timeout value assigned with the undeploy command. When timeout is reached, the application sends an interrupt signal to the thread that handles the request to stop the job.

Even if a thread receives an interrupt signal, not all jobs, handled by the thread, are stopped. Some jobs are stopped, while for some jobs, the interrupt signal is ignored. JEUS does not take any special actions for stopped jobs. The corresponding application is responsible for any post-processing jobs. For more information about thread interruptions, refer to Thread Control.

Graceful Undeployment for internal requests within the application applies to a standalone EJB application as well as an EAR application. If there are multiple Beans in an EJB application, requests between Beans are regarded as internal requests in the same application. Thus, the requests that are currently being processed must be completed, even if an undeploy command is executed.

The undeploy command has the default timeout value of 5 minutes, which means that application request processing is guaranteed for five minutes. The guaranteed time can be changed using the -gracefultimeout option, which is the same as the -to option. If needed, a large timeout value may be specified for graceful undeployment.

To force an immediate undeployment without waiting for the completion of the requests in progress, you can use the -force (-f) option. In JEUS 6, this is the default behavior of undeployment. In this case, the completion of the requests in progress is not guaranteed.

2. Graceful Redeployment

Graceful Redeployment is a mechanism that provides application services uninterruptedly by redeploying a running application. The behavior of graceful redeployment varies with different application types.

This section first covers the general information, and then further explains the different behaviors of graceful redeployment for each application type.

2.1. Requirements for Graceful Redeployment

To use Graceful Redeployment, applications need to satisfy the following requirements.

Applications must be packaged into a .war or .jar file.
For a directory type application, the old and new application directories must be different. Since a directory type application uses the source directory as the service image, the graceful redeployment requirements cannot be satisfied if the old and new applications are in the same directory. However, for Staging Mode Redeployment, the old and new applications can reside in the same directory because the Staging Mode creates a service image for each application.
If an application is located in an application repository, it is impossible to redeploy by specifying a new application. Since an application in the repository is installed on the domain, it cannot be replaced with a new application through redeployment.
For application packaging, the following field must be added to the META-INF/MANIFEST.MF file.

A directory type application must also add the META-INF/MANIFEST.MF file and the following field.
```
Jeus-Use-Graceful-Redeploy: true
```
According to the MANIFEST.MF file rules, a new line (\n) must exist at the end of the file.
An application to redeploy must also add the aforementioned field. Otherwise, general redeployment is executed for the application.
For a directory type application, application-name and module-name must be the same in the standard DD of the old and new applications.
Last modified time of each packaged file must be unique.
For an EJB, graceful redeployment is supported only for session beans (remote interface).
In the SHARED mode, graceful redeployment of an application is not supported, and it is recommended to package the application into an EAR.

2.2. Considerations for Graceful Redeployment

The following must be considered to execute graceful redeployment.

Verify if the graceful redeployment function needs to be used before a service starts. To use the function, ensure that the requirements listed above are met.
An existing application is not immediately undeployed, and thus two applications exist on JVM simultaneously for some time. Thus, the size of the JVM permgen area should be calculated in advance because an OutOfMemoryError may occur if the size is not big enough.
If the JNI library is used, JVM cannot concurrently load the same library using System.loadLibrary(). Therefore, graceful redeployment cannot be used if JNI library is used.

2.3. Graceful Redeployment Execution

Graceful redeployment can be executed with the redeploy command. The following example shows how to execute graceful redeployment:

Assume that there are the following packaged war files.

old application : myservice.war (08/09/2016 1:00 pm)
new application : myservice.war (08/25/2016 11:00 am)
install id = myservice_war, context path = /myservice

A service provider discovered an issue with myservice.war, which had been packaged and deployed on August 9, 2016, at 1:00 p.m. The service provider fixed the issue, and newly packaged the file on August 25, 2016, at 11:00 a.m. The service provider decides to execute graceful redeployment instead of stopping JEUS, because there are users who are already using the service.

Under such a circumstance, the service provider runs the following command by using the console tool.

[MASTER]domain1.adminServer>redeploy myservice_war -path /path_to_new_application/myservice.war

To execute graceful redeployment, the redeploy command does not require a special option. JEUS determines whether to execute graceful redeployment using the precondition field in the META-INF/MANIFEST.MF file and the packaging time. If the field does not exist in the META-INF/MANIFEST.MF file of the application, packaged on August 9, 2016, at 1:00 p.m., or the field is set to false, normal redeployment is executed.

If handling client request takes a long time, set an appropriate value for the undeploy timeout option so that the previous application request can be processed within the timeout period before the redeployment.

How to forcibly Undeploy a Previous Version of an Application

When graceful redeployment is successfully completed, new users start to use the new version of myservice.war. Existing users who have been using the previous version continue to use the previous version. New users and existing users are classified based on (socket) connections. For web applications, HTTP sessions are also classified this way.

The main purpose of graceful redeployment is for the users to be able to use the services, uninterrupted. Therefore, the previous version is not undeployed, until all connections to it have been terminated and the HTTP sessions created through the connections have been deleted. If the previous version remains undeployed because the HTTP session timeout is too long, a service administrator can forcibly undeploy by using the following undeploy command as follows:

[MASTER]domain1.adminServer>undeploy -old myservice_war

How to Automatically Undeploy a Previous Version of an Application After a Timeout

To automatically undeploy the previous version of the application, myservice.war, after a certain time period, use the Timeout option (in seconds), with the redeploy command as follows:

[MASTER]domain1.adminServer>redeploy -path /path_to_new_application/myservice.war -to 5

How to Roll Back to a Previous Version When the Previous Version and a New Version Exist Simultaneously

If a service provider detects that the new version of myservice.war has a problem while the previous version has not been undeployed yet, the previous version should be rolled back. To roll back the previous version, undeploy the new version with the undeploy command as follows:

Run the undeploy command as follows:

[MASTER]domain1.adminServer>undeploy -new myservice_war

Assuming that the new version of the application myservice.war contains a critical issue, it is required to immediately undeploy it. In this case, users of the new version experience interruption of service. To avoid such a situation, undeploy the previous version and then redeploy the new version.

How to Only Distribute a New Application

To provide a new version of myservice.war to users, after checking if the application will run normally, only issue the distribute command using the redeploy command as follows:

[MASTER]domain1.adminServer>redeploy myservice_war -path /path_to_new_application/myservice.war -distonly

The method to check if a new application will run normally varies depending on the application type. For information about how to check if a new web application will run normally, see How to Check if a New Web Application will Run Normally.

To start the new application after checking the behavior, run the start command as follows:

[MASTER]domain1.adminServer>start -new myservice_war

To undeploy the new application because of an issue, run the undeploy command along with the -new option as follows:

[MASTER]domain1.adminServer>undeploy -new myservice_war

How to Undeploy Both Previous and New Versions of an Application

When a previous version and a new version exist simultaneously, you need to explicitly specify the version to be undeployed using the -old or -new option. To undeploy both applications, use the -all option with the undeploy command as follows:

[MASTER]domain1.adminServer>undeploy -all myservice_war

How to Forcibly Replace a Previous Version of an Application

To force normal redeployment instead of using graceful redeployment, run the redeploy command as follows:

[MASTER]domain1.adminServer>redeploy myservice_war -path /path_to_new_application/myservice.war -force

How to Verify if the Current Application is Set to Use Graceful Redeployment

To confirm if a currently running application is utilizing the graceful redeployment feature, view the details about the application. If the application uses graceful redeployment, you will find an item labeled 'Packaged Time' among the application details. This will allow you to determine whether the feature is enabled as well as when the application was packaged.

[MASTER]domain1.adminServer>appinfo -id myservice_war -server server1
Application information for the server [server1] in the domain [domain1].
================================================================================
+-------+--------+--------+-----+-------+--------+-------------------+---------+
| Appli | Applic | Applic | Sta |Target | Target |   Packaged Time   |  Target |
|cation | ation  | ation  | te  |Servers| Cluste |                   |VirtualH |
|   ID  |  Name  |  Type  |     |       |   rs   |                   |   ost   |
+-------+--------+--------+-----+-------+--------+-------------------+---------+
| myser | myserv | war    | RUN | serve |        | Tue Nov 14        |         |
|vice_w |ice     |        |NING |r1     |        |14:06:59 KST 2017  |         |
|ar     |        |        |     |       |        |                   |         |
+-------+--------+--------+-----+-------+--------+-------------------+---------+

2.4. Graceful Redeployment of Web Applications

A new version of a web application can be redeployed uninterruptedly, without stopping the current application service. Because general redeployment undeploys an existing web application, users may receive error messages in the web browser. However, if there are users who are using the application, graceful redeployment does not undeploy the existing version. It proceeds to deploy a new version of the web application, so that temporarily, the existing version and the new version exist simultaneously.

It can be determined if there are users, who are using an existing web application, by seeing if there are existing HTTP sessions or requests, that are currently being handled. The requests usually do not take a long time to be handled, if there is no DB delay problem or it is not being processed asynchronously, which takes a long time. However, HTTP sessions may remain for a long time until timeout is reached, which can prevent the existing web application from undeploying until timeout is reached. The user, who executes redeployment, should set an appropriate timeout to undeploy the existing version. The user should consider the characteristics of the requests and the HTTP sessions, or choose to forcibly undeploy the existing version.

When the new version is running successfully, new requests are no longer sent to the existing version. Users, who continues to use the existing version, are clients, who have connected before the successful completion of the graceful redeployment.

If users, who are using an existing version, are using an HTTP session, they cannot use the new version until the session expires. To prevent this, execute normal redeployment, or forcibly undeploy the existing application by executing graceful redeployment and setting the undeployment timeout. For detailed information, see Graceful Redeployment Execution.

How to Check if a New Web Application will Run Normally

You can confirm in advance if a new web application will run normally, after the application is distributed. For details about how to only distribute a new web application, see How to Only Distribute a New Application.

An HTTP request can be sent through the base port of the server, which distributed the new application. The following assumes that the application path of myservice.war is '/myservice,' the host name of the server that issued only the distribute command is host1, and the base port number of the server is 9736.

http://host1:9736/myservice/

2.5. Graceful Redeployment of EJB Applications

Graceful redeployment of EJB applications redeploys a new EJB file while guaranteeing the processing of existing EJB requests. Like graceful undeployment, graceful redeployment is supported only for session beans. Thus, in order to perform the graceful redeployment of a JAR application, the JAR file must only consist of session beans.

When graceful redeployment is performed, new clients use the new EJB by doing a lookup of the new EJB. Clients who are currently using the existing EJB are guaranteed the processing of requests for the Timeout period, specified by the user. If it is determined that there are no current requests for the existing EJB, the existing EJB will be undeployed, even if Timeout has not expired.

The request handling criteria varies depending on the EJB type. The request in progress is the criteria for stateless session beans, while the existence of a running session is the criteria for stateful session beans. In other words, for stateful session beans, undeployment will be performed when all sessions are destroyed, and it is determined that there will be no additional requests.

Currently, to improve performance, JEUS uses the client cache for Home Stub and EJB Object Stub. If a client is using the existing EJB from the cache, when graceful redeployment completes, the existing information in the cache must be deleted and new information about the new EJB must be obtained. EJB 3.x requires no additional configurations for normal operations, but for EJB 2.x, you must configure the <use-dynamic-proxy-for-ejb2> setting to true. The default value of <use-dynamic-proxy-for-ejb2> is true.

2.6. Graceful Redeployment of EAR Applications

The graceful redeployment of WEB and EJB modules in an EAR file is guaranteed for EAR applications. As in the graceful redeployment of standalone modules, the aforementioned services are guaranteed until the context’s session expires. JEUS guarantees the processing of the current requests from stateless session beans, and requests that were received before the expiration of the stateful session beans.

Since an EAR application is a single application, when an EJB module in the EAR file completes a request, the EJB module cannot be undeployed if there are requests from other modules that are still being processed. Like in graceful undeployment, a module which is currently processing a request can send another request to the EJB module. Hence, you cannot guarantee the completion of all EAR application requests by undeploying only a single EJB or WEB module. All WEB or EJB module requests in an EAR file must be completed before undeploying the current EAR application.

The name of the new application, as well as its module names, must be identical to those of the previous version of the application. For more information about configuring the application name, refer to "Jakarta EE 9 Platform Specification".