Application files are distributed to each target server, and preparation tasks are performed. After the jobs are completed successfully, the application is ready to start.

The jobs are performed in two steps on DAS. All deployment-related commands are executed on DAS, and DAS sends the commands to each target server. When a user requests to deploy an application, the request is said to be successfully processed only when all servers, that received the request, can guarantee a successful deployment. The request is handled in two steps, the distribution step and the start step. If the distribution step fails, the deployment request will fail, and the application will be undeployed from all the servers.

These two steps can be executed using two commands, to distribute and to start an application, or using a single command, to deploy an application.

Step 1 (Distribution Step)

In the application distribution step in JEUS, an application is distributed to target servers or clusters, and then verified. In this step, application files are distributed to each server, and preparation and verification tasks are executed.

When all jobs are completed successfully, an application is ready to run. If the application is an EJB module, a service port is opened, and if it is a web module, its context gets connected to the web listener's context. However, the application is in the DISTRIBUTED state, where the application cannot be started.

If an application, in the DISTRIBUTED state, receives a request to run, an exception or an error will occur. If the application is an EJB module, the exception stating that the Bean does not exist will occur, and if the application is a web module, the "503 Service Unavailable" error will occur.

[2016.08.10 15:28:35][1] [t-1] [JNDI.Context-0073] exception occurred during JNDI operation
<<__Exception__>>
javax.naming.NamingException: javax.ejb.EJBException: java.rmi.RemoteException: EJB object is not read at 
jeus.ejb.client.BusinessObjectFactory.getObjectInstance(BusinessObjectFactory.
java:89)
   at javax.naming.spi.NamingManager.getObjectInstance(NamingManager.java:304)
   at jeus.jndi.JNSContext.lookupInternal(JNSContext.java:594)
   at jeus.jndi.JNSContext.lookup(JNSContext.java:549)
   at jeus.jndi.JNSContext.lookup(JNSContext.java:538)
   at jeus.jndi.JEUSFailoverContext.lookup(JEUSFailoverContext.java:314)
   at javax.naming.InitialContext.lookup(InitialContext.java:392)
   at test.HelloTest.testHelloBean(HelloTest.java:29)
   ......
Caused by: java.rmi.RemoteException: EJB object is not ready at 
jeus.ejb.container.RemoteInvocationManagerImpl.beforeInvoke(RemoteInvocationManagerImpl.
java:72
   at jeus.ejb.baseimpl.RemoteInvokerServer.preInvoke(RemoteInvokerServer.java:118)
   at jeus.ejb.baseimpl.RemoteInvokerServer.invoke(RemoteInvokerServer.java:97)
   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.
java:25)
   at java.lang.reflect.Method.invoke(Method.java:597)
   at sun.rmi.server.UnicastServerRef.dispatch(UnicastServerRef.java:305)
   at sun.rmi.transport.Transport$1.run(Transport.java:159)
   at java.security.AccessController.doPrivileged(Native Method)
   at sun.rmi.transport.Transport.serviceCall(Transport.java:155)
   at sun.rmi.transport.tcp.TCPTransport.handleMessages(TCPTransport.java:535)
   at sun.rmi.transport.tcp.TCPTransport$ConnectionHandler.run0(TCPTransport.
java:790)
   at sun.rmi.transport.tcp.TCPTransport$ConnectionHandler.run(TCPTransport.java:649)
   at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.
java:886)
   at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:908)
   at java.lang.Thread.run(Thread.java:662)

[Figure 1.1] An Error Which Occurs When a Web Module in DISTRIBUTED Receives a Request

When an application is successfully distributed to all target servers or clusters, this step is completed successfully. If the distribution job fails on one or more target servers or clusters, the user's deployment request will fail. In such case, the undeployment command will be sent to all successful servers, and all jobs in this step will be rolled back. If some of target servers are in a failed or shut down state, this step will also fail. At this time, the user needs to run the deployment command again on all other successful target servers.

When the distribution target is a cluster, even if some of the servers in the cluster is in a failed or shut down state, the distribution step can be successful. If all other servers, besides the failed servers, are successful, this step is also considered successful.

Step 2 (Start Step)

An application, which is already distributed on the target servers or clusters, are started in this step, called the application start step in JEUS, and the application becomes available for service.

Different from the distribution step, when one or more servers of the target servers or clusters is successful in the start step, the step is marked as successful. This is because, with the successful completion of the distribution step, the application is already verified and ready to run.

If the start step fails, this indicates that a server is in a failed state for the moment. After the server's status becomes normal, the start step has potential to succeed and become available for service. If a server fails during this step, DAS retries this step on the failed server 10 times, every 5 seconds, using different threads.

If all the tries fail, the server must be manually restored, because the server will remain in the failed state. If this step is retried for an application after the server is restored, it will execute successfully on the server.

In JEUS 8, an ID is assigned to each application to allow a domain to identify and manage the application. An application ID must be unique on a domain, because it is used to identify an application in a domain. It is recommended to use alphanumeric characters for the application IDs.

An application is assigned an ID when it is installed. If an ID is not assigned to an application during installation, an ID will be created using the name of the application file. For example, if examples.ear is not assigned an ID during installation, its ID will be examples_ear.

An application ID is used to issue control and search commands, such as deploy and undeploy. If an application file is located in a repository separate from a domain, its name is used as its ID.

When DAS receives an application file, it creates a directory in the application's INSTALL_HOME directory, which is in a domain directory with the application's ID. It then locates the file in the created directory.

When an application is installed, it is placed in the following directory. For detailed information about the INSTALL_HOME directory, see Section 1.1.4, “Domain's INSTALL_HOME Directory”.

INSTALL_HOME/<APPLICATION_ID>/<APPLICATION_FILE>

When a server receives or decompresses an application file, it locates the file in the APPLICATION_ID directory, under the DEPLOYED subdirectory.

Because a domain controls commands of applications, the application status shows the statuses of all the target servers. Each server shows statuses of applications, which are running on it.

Status of Applications in a Domain

Status of applications in DAS is changed as follows:

INSTALLED → DISTRIBUTING → DISTRIBUTED → STARTING → RUNNING

Description for each status is as follows:

[Figure 1.2] The Life Cycle of Applications on a Domain

Status of Applications in a Server

Status of applications on a server is changed as follows:

DISTRIBUTING → DISTRIBUTED → STARTING → RUNNING

Description for each status is as follows:

[Figure 1.3] The Life Cycle of Applications on a Server

The directory structure used to deploy an application is as follows:

Domain's INSTALL_HOME Directory

When an application is installed on a domain, it is placed in the APPLICATION_INSTALL_HOME directory.

[Figure 1.4] Domain's INSTALL_HOME Directory

An Application Repository Managed by a Domain

The following shows an application repository that is added to a domain.

[Figure 1.5] Application Repository Directory Added in a Domain

An application repository includes both applications in the form of a directory and an archive. When applications are included in an application repository by a user, an application ID cannot be specified by the user, and is always created using the file name. For information about how to add and delete an application repository, see "1.5.1. Adding, Deleting, and Searching Application Repositories".

Image Directory of an Application Deployed on a Server

A server receives an application from DAS and places it in the following path to deploy it.

SERVER_HOME/.workspace/deployed

The path is called DEPLOYED_HOME. A directory is created under the DEPLOYED_HOME directory using the application ID as its name. Received application files are placed in the new directory.

When deployed, an archived application is decompressed in a directory called the application's deployment image directory. The directory is named with the application file's name. For example, the name of the image directory where myApp.ear is decompressed is 'myApp_ear___'.

If the extension of an application file is ear, the file's modules also need to be decompressed under the ear image directory. The directory where the modules are decompressed is named in the same way as an image directory. For example, the name of the directory where ejb.jar is decompressed is 'ejb_jar'.

[Figure 1.6] Image Directory of an ear Application Deployed on a Server

gen Directory of an Application

In some cases, when an application is deployed on a server, the necessary files for the application are created.

For EJB or web applications, those files need to be created in a directory under the '_generated_' directory, in the DEPLOYED_HOME directory. The directory is created using an application ID, so that each application is has its own directory. The directory is called an application's gen directory.

The following files are created in the gen directory of each application:

[Figure 1.7] gen Directory of an ear Application Deployed on a Server

To deploy an application, specify the target servers where the application will run on. The targets can be one or more servers and/or clusters. You can also add a virtual host to deploy and start the web module on a specific host.

Server

Because a server is the minimum unit which services an application, it can be a target where the application is deployed on.

When the deploy command is sent to multiple servers, if the deployment fails on one or more servers or one or more servers are shut down, the distribution step will fail. If the distribution step fails, take an appropriate action for the servers and run the deploy command again, or exclude the failed servers and run the deploy command again.

When a server is in the STANDBY or SUSPENDED state, it can't start an application, because this means that the server is not running normally. When a server is in the RUNNING state after the server has restarted or resumed, it can start an application. For detailed information about server statuses, see JEUS Server Guide. "3.1.1. Life Cycle of Managed Servers".

If a user runs only the distribute command, not the deploy command, an application will not start. Even after the server restarts, the status needs to be maintained. Therefore, DAS records the status of the application, in the '.deployInfo.ser' file under the INSTALL_HOME directory. When the server restarts, a status notification is sent to the user in order to continue processing the previously started jobs.

Cluster

If an application's target is a cluster, the application can only be deployed on the cluster, and not on a server within the cluster. If an application fails to be distributed on even one of the servers in a cluster, the application will fail to be deployed on the cluster.

However, unlike using a list of servers as a target for deployment, an application can be successfully deployed on the cluster even if some servers in a cluster are not alive. If the application is successfully deployed on all live servers in the cluster, it is successfully deployed on the cluster.

If a server failed or is not in the RUNNING state during deployment, the applications on the server must be deployed after the server is failbacked or restarted. It is the role of DAS to guarantee successful deployment when a server boot-time deployment fails.

DAS, at most, guarantees that an application is successfully deployed on the members of a cluster which failed the boot-time deployment with retries. It retries up to five times, in five minutes intervals. If all the trials fail, DAS will notify that the deployment can no longer be guaranteed, since the failure cannot be recovered in JEUS. The user needs to find the reason and resolve the problem. This guarantee applies not only to servers that were not in the RUNNING state during the deploy process, but also to servers that were dynamically included to the cluster.

If all retries of DAS when deployment fails, the following message will be displayed:

Deployment reattempts of the application[examples] failed 5 times. 
No more deployment attempts will be made. solve the problem for deploying application.

An application cannot be deployed on a server that is included in a cluster. If attempted, the following warning message will be displayed for the user to run the undeploy or the remove-application-target command:

WARNING: The server[server1] is part of the cluster[cluster1], so this application[exampes] can only be deployed to the cluster. 
Deploy again this application to the cluster target.

The previous problem occurs when a user manually modifies the domain.xml file, which is prohibited. JEUS does not provide support for resolving errors caused by this action.

If an independently running server is dynamically added to a cluster, applications currently running on the server will be undeployed, and the server will be removed from the target list. Also, applications which need to be deployed on the cluster will be dynamically deployed, since the user probably intends to use the applications in the cluster.

However, it is not recommended to dynamically add an existing server to a cluster, even if it is intended by the user. This may cause a problem for services already running on the server. Therefore, to expand a cluster, add the new server, and then add the server as a member of the cluster.

.

Virtual Host

Web engine allows a web context to run on a specific host registered as a virtual host. A virtual host cannot be used alone, but can be used along with server or cluster targets. If there is no virtual host, an application is deployed on the default virtual host.

For detailed information about a virtual host, refer to JEUS Web Engine Guide. "5. Virtual Hosts." For detailed information about the deploy command, see "4.3.3. Deploying Applications".

Runtime deployment is deploying an application or a module on a running server. It can be executed by accessing DAS using the WebAdmin or console tool.

In JEUS 7 or later versions, runtime deployment indicates permanent deployment. Permanent deployment means that if an application is successfully distributed with the deploy or distribute command, the details are recorded in the domain.xml file to save the application information. When DAS or MS reboots, it reads information about the application, and the application is deployed via boot-time deployment. The domain.xml is the configuration file for JEUS domains.

Because deployment can be executed only by using DAS, only DAS can write information about the applications in domain.xml. MS receives application settings from DAS when it boots, downloads application files registered in the settings, and executes boot-time deployment according to the domain.xml file.

For information about how to execute runtime deployment, see "4.3.3. Deploying Applications".

Boot-time deployment is deploying an application registered in domain.xml when MS boots. Because permanent deployment is the default setting for JEUS 7 or later versions, applications, which were deployed once already, are deployed again when MS boots.

Boot-Time Deployment in the DEPENDENT State

When MS boots, it receives the file, domain.xml, from DAS. If there are applications registered in the file, MS checks to see if the applications need to be deployed on itself. The applications are not deployed individually on the MS. All applications are distributed first, and if the distribution is successful, the start step is executed.

The execution of the distribution step is similar for when a server boots or when a server is running. First, the server receives application files from DAS. If the application files already exist on the server, these files and the application files installed on DAS are compared to see if the application files need to be sent to the server. Then, the server decompresses the application files, loads the relevant classes, and executes the distribution step to configure the environment for the applications to run in.

If one or more applications fail to be distributed when a server boots, the server goes into the STANDBY state and stops the booting process. At this time, the start-server command is executed, and the failed applications are retried to be distributed. If all applications are distributed, the start step can be executed. If one or more applications fail to be distributed again, the server will remain in the STANDBY state.

To force a server into the RUNNING state, even if one or more applications fail to be distributed to the server, run the following command:

[DAS]domain1.adminServer>>start-server -force server1

If the previous start-server command is executed with the -force option, the status of the server becomes RUNNING, and only distributed applications are started in the server.

When the applications are successfully distributed during boot-time deployment, MS checks with DAS to see if the application can be started. If the applications are in the DEPLOYED or RUNNING states in DAS, they are ready to start. If MS fails to get the status of the application, it does not execute the start step. At this point, the MS stops booting and goes into the STANDBY state.

To start an application, regardless of the status of the application in DAS, run the start-server command with the -force option to force the server into the RUNNING state.

If an application stops and starts when a server is in the SUSPENDED state, the application's status needs to be maintained for when the server resumes again and goes into the RUNNING state. At this point, the server does not retrieve the status information from DAS again. Even if the server is in the SUSPENDED state, the server can get the start and stop commands from DAS. The server remembers the commands and is able to maintain the application status when it resumes, even if the application cannot execute the commands.

Boot-time Deployment in the INDEPENDENT State

When a server boots in the INDEPENDENT state, it is not managed by DAS. Because the server cannot access DAS, it cannot receive application files from DAS. Therefore, if the previously received application files do not exist on the server or are damaged, boot-time deployment cannot be executed.

When a server boots in the INDEPENDENT state, deployment can be executed only when the server is able to access application files. A server can access the application files in the following cases:

If one of the three situations are not possible, an application cannot be deployed. At this time, a server goes into the STANDBY state and stops booting.

To force the server into the RUNNING state, connect to the server using the console tool and run the local-start-server command.

When a server boots in the INDENDENT state, it cannot retrieve a list of applications, which only needs to be distributed, from DAS. Therefore, the server starts all applications which have been successfully distributed.

If a server which boots in the INDEPENDENT state goes into the DEPENDENT state by being connected to DAS, it tries to redistribute all applications that failed to distribute according to the specified options. If all the applications are successfully distributed, the server will get a list of applications, which need to be started from DAS, and starts the applications in the same way as during the boot-time deployment.

If there is a running application that only needs to be distributed, the server stops the application. However, if a server goes into the DEPENDENT state during booting because DAS is restored, the server does not handle these tasks.

One of the major roles of DAS is synchronizing the application files. The application files in DAS and MS need to be synchronized when:

DAS synchronizes not only the application files, but also the statuses of applications in the domain.

When boot-time deployment is executed, if an application is in the DISTRIBUTED status in DAS, the application will be in the DISTRIBUTED status in MS. To start this application, the user needs to run the start-application command.

If MS goes into the DEPENDENT state from the INDEPENDENT state, application statuses as well as the application files are synchronized in MS. The statuses of applications that have become DEPENDENT in MS are changed according to the statuses of applications managed by DAS.

The statuses of all the applications in MS, that are in the INDEPENDENT state, need to be in the RUNNING state for the applications to run. If the MS goes into the DEPENDENT state, the statuses of the applications in MS will be changed according to those in DAS.

If the status of an application is DISTRIBUTED in DAS, the application in MS will be stopped and changed to the DISTRIBUTED state. If MS has an application which is already undeployed in DAS, the application will also be undeployed in MS.

The applications installed on DAS are gathered and managed in a directory. The applications cannot be manually located in this directory.

Multiple directories can be set as repositories. All set directories are regarded as application repositories. To add, delete, and search application repositories, use the WebAdmin or console tool.

Java EE applications, both archive modules and exploded modules, can be placed in a directory, that is configured as an application repository of a domain.

The application files cannot be added to or deleted from an application repository, registered in a domain, with the install-application and uninstall-application commands, respectively. If the files are manually added or deleted, this can be automatically detected in the domain. The manually added applications are in the INSTALLED status, and the manually deleted applications are no longer managed by the domain.

Because an application ID is the application filename, the name is specified with the -id option of the deploy command.

To update the application files, manually update the files, which are located in a repository. If a cycle for automatic redeployment is set when an application is deployed, by automatically detecting changes in the files, the application can be automatically redeployed.

If a filename in an application repository, to be added, is the same as an application ID, that is already in use in the domain, the application cannot be recognized in the domain. In this case, the following log message will appear:

[2016.08.08 12:37:40.625][1] [adminServer-68] [Deploy-0005] WARNING: 
The application[myApp] already exists on /JEUS_HOME/.applications/myApp.ear. 
Change the file name of [/home/user1/apps/myApp].

When a duplicated ID is used, if the application information is requested or DAS starts, the same log message will be generated.

If a valid application does not exist in an application repository, where you are trying to add to, the following log message will appear:

[2016.08.08 12:37:40.625][1] [adminServer-68] [Deploy-0062] WARNING: 
The repository(/home/user1/apps) does not contain any valid applications, 
but new applications can be added.

If the application files, distributed or deployed on a domain, exist in an application repository to be deleted, the application continues to be managed by the domain, even after the application repository is deleted. In this case, the following log message will appear:

[2016.08.08 12:44:04.328][1] [adminServer-93] [Deploy-0124] WARNING: 
The application[myApp] is RUNNING in repository[/home/user1/apps]. 
To remove this application from the domain, undeploy it.

Using WebAdmin

The following is the process of adding an application repository using WebAdmin:

Using the Console Tool

An application repository can be added to a domain with the add-application-repository command, and can be deleted from the domain with the remove-application-repository command. A subdirectory is created under the directory, where the applications installed on DAS reside, with an application ID that is assigned to it during the application installation. The application's archive files are placed in this new directory.

The following example adds, deletes, and searches application repositories using the console tool:

[DAS]domain1.adminServer>add-application-repository /apps/test
Successfully performed the ADD operation for An application repository.
Check the results using "add-application-repository or list-application-repositories"

[DAS]domain1.adminServer>list-application-repositories
Application Repositories
================================================================================
+------------------------------------------------------------------------------+
|                        Path to Application Repository                        |
+------------------------------------------------------------------------------+
| /apps/test                                                                   |
+------------------------------------------------------------------------------+
================================================================================

[DAS]domain1.adminServer>remove-application-repository /apps/test
Successfully performed the REMOVE operation for An application repository.
Check the results using "remove-application-repository or list-application-repositories"

[DAS]domain1.adminServer>list-application-repositories
Application Repositories
================================================================================
+------------------------------------------------------------------------------+
|                        Path to Application Repository                        |
+------------------------------------------------------------------------------+
(No data available)
================================================================================

After an application repository is added, the applications in the application repository can be deployed using the WebAdmin or console tool. For detailed information, see Section 4.3.3.2, “Using the Console Tool”.