Table of Contents
This chapter describes graceful undeployment and redeployment, which undeploys and redeploys an application after processing all current requests.
Graceful Undeployment undeploys an application after all user requests, which are being processed, are completed.
EAR, EJB, and web applications can process graceful undeployment. For EJB applications, only the SessionBean 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.
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 should 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 should not fail. The request should be successfully handled, and the application should 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.
Note
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 JEUS Server Guide. "3.3.2. 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, which are currently being processed, should 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, you can also use a large timeout value 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 JEUS6, this is the default behavior of undeployment. In this case, the completion of the requests in progress is not guaranteed. For more information about graceful undeployment, refer to "4.3.5. Undeploying Applications".
Graceful Redeployment redeploys a running application without terminating the application. This function operates differently, depending on the application type.
This section first covers the general information, and then explains the operations of graceful redeployment for each application type.
The following preconditions should be met to execute graceful redeployment:
-
An application should be packaged into a war file or a 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 in the 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
Note
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.
-
In the SHARED mode, graceful redeployment of an application is not supported, and it is recommended to package the application into an EAR.
The following should be considered to execute graceful redeployment:
-
You must determine if the graceful redeployment function needs to be used before a service starts. To use the function, fulfill the previously described preconditions.
-
An existing application is not immediately undeployed. 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.
Graceful redeployment can be executed with the redeploy command. The following explains how to execute graceful redeployment with the following example:
Assume that there are the following packaged war files:
-
old application : myservice.war (05/09/2012 1:00 pm)
-
new application : myservice.war (05/25/2012 11:00 am)
-
install id = myservice_war, context path = /myservice
A service provider detected a problem with myservice.war, which was packaged and deployed on May 9, 2012, at 1:00 p.m. It resolved the problem, and newly packaged the file on May 25, 2012, at 11:00 a.m. The service provider decides to execute graceful redeployment instead of stopping JEUS, because there are users who are using the service, at the time.
The service provider runs the following command using the console tool:
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 May 9, 2012, at 1:00 p.m., or the field is set to false, normal redeployment is executed.
Note
If handling client request is taking 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 command:
undeploy -old myservice_war
How to Automatically Undeploy a Previous Version of an Application After a Timeout Period
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:
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 as follows:
undeploy -new myservice_war
Warning
A new version is immediately undeployed, because it is assumed that the new version has a critical problem. Therefore, users who use the new version cannot continue to use the service. To avoid this situation, undeploy and then redeploy the previous version.
How to 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:
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 Section 2.2.4, “How to Check if a New Web Application will Run Normally”.
To start the new application after the check, run the start command as follows:
start -new myservice_war
To undeploy the new application that has a problem, run the undeploy command along with the -new option as follows:
undeploy -new myservice_war
How to Undeploy Both a 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 as follows:
undeploy -all myservice_war
How to Forcibly Replace a Previous Version of an Application
To unconditionally execute normal redeployment, instead of graceful redeployment, run the redeploy command as follows:
redeploy myservice_war -path /path_to_new_application/myservice.war -force
A new version of a web application can be redeployed, without stopping the service of an existing application.
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.
Note
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 "2.2.3. Graceful Redeployment Execution".
How to Check if a New Web Application will Run Normally
Methods to check if a new web application will run normally or not, after the application is distributed, is described in Section 2.2.3, “How to 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/
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.
The graceful redeployment of WEB and EJB modules in an EAR file is guaranteed for EAR applications. Like 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.
Note
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 "Java EE 6 Platform Specification".