(This document is working in progress).
This page will cover some of the internal design details of the deployment framework which are of interest for the container teams.

Main Scenarios

Deployment

The basic deployment phases are: prepare, load, start.
All three phases will be invoked for the deployed target.
When the deployed target is not DAS, only the prepare phase will be invoked on DAS.
The internal phase generateArtifacts (part of the prepare) will be invoked to generate artifacts on DAS. When the deployed target is not DAS, the artifacts on DAS will be synchronized to target instances (no artifacts generation happens on instances).
The Origin for deployment is Origin.deploy/deploy_instance. Origin.isDeploy will return true for deployment.

Enable

All three phases (prepare, load, start) will be invoked on the enabled target.
When the enabled target is not DAS, no phases are executed and only the domain.xml is updated on DAS.
No artifacts generation happens for enable.
The Origin for enable is Origin.load.

Create application ref

All three phases (prepare, load, start) will be invoked on the create-application-ref command target.
When the create-application-ref target is not DAS, no phases are executed and only the domain.xml is updated on DAS.
No artifacts generation happens for create application ref.
The Origin for create-application-ref is Origin.create_application_ref on DAS and Origin.deploy_instance on the instance.

Application loading in server start

All three phases (prepare, load, start) will be invoked on the referenced server instance.
When an application is not referenced by DAS, only the prepare phase will be invoked for DAS start up.
No artifacts generation happens for server start.
The Origin for enable is Origin.load.

Undeployment

The basic undeployment phases are: stop, unload, clean.
All three phases will be invoked for the undeployed target.
When the undeployed target is not DAS, only the clean phase will be invoked on DAS.
The Origin for deployment is Origin.undeploy.

Disable

The stop and unload phases will be invoked on the disabled target.
When the disabled target is not DAS, no phases are executed and only the domain.xml is updated on DAS.
The Origin for disable is Origin.unload.

Delete application ref

The stop and unload phases will be invoked on the disabled target.
When the disabled target is not DAS, no phases are executed and only the domain.xml is updated on DAS.
The Origin for delete-application-ref is Origin.unload on DAS and Origin.undeploy on the instance.

Application unloading in server shutdown

The stop and unload phases will be invoked on the referenced server instance.
The Origin for enable is Origin.unload.

Deployment Events

Other than the formal Deployment/Container SPI , there is also the lightweight event mechanism to hook into the deployment framework.

During the deployment lifecycle, there are events sent at each main phase, such as after application is prepared, after the application is loaded, after the application is started etc. A class could be registered as an event listener and take certain actions upon receiving the event.

The main events are sent from these classes during deployment lifecycle:
1. v3/core/kernel/src/main/java/com/sun/enterprise/v3/server/ApplicationLifecycle.java
For example:
events.send(new Event<DeploymentContext>(Deployment.APPLICATION_PREPARED, context), false);

2. v3/common/internal-api/src/main/java/org/glassfish/internal/data/ApplicationInfo.java
For example:
events.send(new Event<ApplicationInfo>(Deployment.APPLICATION_LOADED, this), false);

3. v3/common/internal-api/src/main/java/org/glassfish/internal/data/ModuleInfo.java
For example:
events.send(new Event<ModuleInfo>(Deployment.MODULE_LOADED, this), false);

The application loading/starting events are sent from ApplicationInfo and module level loading/starting events are sent from ModuleInfo. The ApplicationLifecycle sends the rest of the events.

In the event sent from ApplicationLifecycle, the hook object from the event is the DeploymentContext, while the hook object sent from the event sent from ApplicationInfo/ModuleInfo classes are ApplicationInfo and ModuleInfo objects. The application information could be obtained from these hook objects.

An event could be synchronous or asynchronous, the events used in the above examples have "false" as the last param which means they are synchronous events.

To become an event listener:
1. The class needs to implement the EventListener interface.
2. It need to inject an Events object and register itself as a listener with the Events object.
3. Have an event() method and perform actions on the event.

Some of the examples for the listener classes:
v3/deployment/admin/src/main/java/org/glassfish/deployment/admin/DeployCommand listens to the APPLICATION_PREPARED event sent from ApplicationLifecycle.
And these two classes listen to the events sent from ApplicationInfo and ModuleInfo.
v3/security/core/src/main/java/com/sun/enterprise/security/SecurityDeployer.java
v3/web/weld-integration/src/main/java/org/glassfish/weld/WeldDeployer.java

Offline Mode

Deployment

When the target instances are offline, the deployment operation will execute on DAS first. And when the target instances are back up on line, the instances will synchronize with the DAS for the domain.xml and the application bits. As part of the synchronization, the relevant application entries will be added to the instances domain.xml and the applications bits added to the instances applications directory.The instances will then load the application based on the domain.xml.
When some of the target instances are up and some are offline, the applications will be deployed to the online instances as usual. And the offline instances will load up the applications when they are brought back online.

Undeployment

When the target instances are offline, the undeployment operations will execute on DAS first. And when the target instances are back up on line, the instances will synchronize with the DAS for the domain.xml and application bits. As part of the synchronization, the relevant application entries will be removed from the instances domain.xml and the applications bits removed from the instances applications directory.
When some of the target instances are up and some are offline, the applications will be undeployed from the online instances as usual. And the offline instances will clean up the domain.xml and applications bits when they are brought back online.

Error Handling

Deployment

When an application failed to deploy on DAS, we failed the deployment and roll back (if the deployed target is not DAS, the code will not reach the instances as DAS part runs first). The stop, unload, clean will be invoked on DAS to rollback the deployment on DAS.

When an application failed to load on instances (some of the instances or all the instances), the stop, unload, clean will be invoked on the relevant instances to rollback the loading. However, we don't fail and rollback the overall deployment, no rollback is done for DAS part of the deployment which has already completed before reaching the instances. We will inform the user the application has failed to load on instanceXXX and advise them to fix their application and redeploy.