View Source

h1. Introduction

{section}
{column}

Several concurrent life-cycles exist in Petals ESB:
* [the Petals ESB container life-cycle|#petals-esb-lifecycle],
* [the shared-library life-cycle|#sharedlibrary-lifecycle],
* [the component life-cycle|#component-lifecycle],
* [the service-assembly life-cycle|#service-assembly-lifecycle],
* [the service-unit life-cyle|#service-unit-lifecycle].

At the bottom of this page, we also explain the interrelation between registering endpoints (usually SU provides, but also components' native services) and processing messages arriving on these endpoints.

{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

{anchor:petals-esb-lifecycle}
h1. The Petals ESB container life-cyle

The Petals ESB container life-cycle is very simple.
{gliffy:name=Petals ESB lifecyle|version=2}
It contains only one state: STARTED. The implicit 'STOPPED' state does not physically exist because in such state no Petals ESB process is running.

The transition from state 'STOPPED' to 'STARTED' is realized using the Petals ESB startup script '{{petals-esb}}'. The return to the state 'STOPPED' is realized using {{^C}} or the command '{{petals-esb stop}}'. See [Starting and stopping Petals ESB].

*When stopping a Petals ESB container, _all its components are shutdown_*. When starting the Petals ESB container, shared libraries, components, service assemblies and service units are restored to the state in which they were when stopping the container.

{anchor:sharedlibrary-lifecycle}
h1. The shared-library life-cyle

h2. The life-cycle

The shared-library life-cycle is simple.
{gliffy:name=Shared-Library lifecyle|version=3}
It contains only one state: INSTALLED. The implicit state 'UNINSTALLED' does not prysically exist because the shared-library is not instantiated or loaded in memory at that time.
The transition from state 'UNINSTALLED' to 'INSTALLED' is realized by installing the shared library, and the return to the state 'UNINSTALLED' is realized by uninstalling the shared-library. A shared library can be (un)installed using [Petals CLI|petalsesb:Command Line Interface], [the Petals Autoloader|Petals ESB "Autoloader"], Petals Ant Tasks or the JMX API.

{anchor:sharedlibrary-lifecycle-constraints}
h2. Constraints

The shared library life-cycle is linked to the component life-cycle:
* A shared library required by a component must be installed before the component can be loaded.
* A shared library can not be uninstalled if a component requiring it is installed.

|| Component state || installSharedLibrary || uninstallSharedLibrary ||
| UNLOADED | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! |
| LOADED/UNINSTALLED | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |
| INSTALLED/SHUTDOWN | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |
| STOPPED | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |
| STARTED | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |

{anchor:component-lifecycle}
h1. The component life-cycle

h2. The life-cycle

The component life-cycle is the more complex life-cycle of Petals ESB life-cycles. It is composed of two correlated sub life-cycles:
* The component installer life-cycle that drives the installation of the component.
* The component life-cycle itself.

{gliffy:name=Component lifecyle|version=8}

The state {{INITIALIZED}} is a temporary state in the startup transition. The transition {{init}} and {{start}} are automatically chained when starting a component from the state {{SHUTDOWN}}.

Actions associated to states:
* When initializing the component:
** The endpoints of the [native services|Glossary#Native_Service] are registered.
* When starting the component:
** It will be able to process request messages.
* When stopping the component:
** Request messages are not processed anymore.
** All resources (as database, pools, ...) used by the message processing are released.
* When shutting down the component:
** All resources (as database, pools, ...) used by the service unit (un)deployment on state {{STARTED}} and {{STOPPED}} are released.
** The endpoints of the native services are unregistered.

h2. Constraints

The component life-cycle is linked to:
* [The shared life-cycle|#sharedlibrary-lifecycle-constraints].
* [The service-assembly lifecycle|#serviceassembly-lifecycle-constraints].
* The service-unit life-cycle with the following constraint:
|| Service unit state || loadNewInstaller || install || start || stop || shutdown || uninstall || unloadInstaller ||
| UNDEPLOYED | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! |
| SHUTDOWN | !checkErro.png|align=center,width=20px!| !checkErro.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |
| STOPPED | !checkErro.png|align=center,width=20px!| !checkErro.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |
| STARTED | !checkErro.png|align=center,width=20px!| !checkErro.png|align=center,width=20px!| !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |
** A component required by a service unit must be installed and running (ie. in state STOPPED or STARTED) before the service unit can be deployed.
** A component with service units deployed can only be started or stopped: all service units must be undeployed before applying any of the other transitions.
** Stopping the container is the only way to have the component shutdown (without state persistence) even if service units are deployed on.

{anchor:service-assembly-lifecycle}
h1. The service-assembly life-cycle

h2. The life-cycle

The service assembly life-cycle can be viewed as a wrapper of all its service unit life-cycles. It drives the life-cycle of its service-units.
{gliffy:name=Service-Assembly lifecyle}

The transitions from state 'UNDEPLOYED' to 'SHUTDOWN' is realized by deploying the service assembly, and the return to the state 'UNDEPLOYED' is realized by undeploying the service assembly. A service assembly can be (un)deployed/started/stopped/shutdown using [Petals CLI|petalsesb:Command Line Interface], [the Petals Autoloader|Petals ESB "Autoloader"], Petals Ant Tasks or the JMX API.

Actions associated to states:
* When deploying the service assembly, all service-units not in state {{DEPLOYED}} are deployed.
* When starting the service assembly, all service-units not in state {{STOPPED}} are initialized, then all service-units not in state {{STARTED}} are started.
* When stopping the service assembly, all service-units not in state {{STOPPED}} are stopped.
* When shutting down the service assembly, all service-units not in state {{SHUTDOWN}} are shutdown.
* When undeploying the service assembly, all service-units not in state {{UNDEPLOYED}} are undeployed.

{anchor:serviceassembly-lifecycle-constraints}
h2. Constraints

The service assembly life-cycle is linked to the component life-cycle:
* To realize a transition on the service-assembly life-cycle, the component must be in state STARTED or STOPPED.

|| Component state || deploy || start || stop || shutdown || undeploy ||
| UNLOADED | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |!checkErro.png|align=center,width=20px! |
| LOADED/UNINSTALLED | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |!checkErro.png|align=center,width=20px! |
| INSTALLED/SHUTDOWN | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! | !checkErro.png|align=center,width=20px! |!checkErro.png|align=center,width=20px! |
| STOPPED | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! |!checkOk.png|align=center,width=20px! |
| STARTED | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! | !checkOk.png|align=center,width=20px! |!checkOk.png|align=center,width=20px! |

{anchor:service-unit-lifecycle}
h1. The service-unit life-cyle

The service unit life-cycle is simple:
{gliffy:name=Service-Unit lifecyle|version=3}
The implicit state 'UNDEPLOYED' does not physically exist because the service unit is not deployed in memory at that point.

Actions associated to states:
* When deploying a provider service unit, it is registered by the component.
* When initializing a service unit, its resources are allocated.
* When starting a service unit, its provides endpoints are registered, external listening is started and consumptions of services are started.
* When stopping a service unit, its provides endpoints are unregistered, external listening is stopped and consumptions of services are stopped,
* When shutting down a service unit, its resources are released.
* when undeploying a provider service unit, it unregistered from the component.

{petalslink}
According to the JBI specification, actually, the 'STOPPED' and 'STARTED' state are used for a two-phases start (see javax.jbi.component.ServiceUnitManager javadoc):
* Initialising the SU (going into the 'STOPPED' state) is the first phase of the two-phases start: services that are related to deployment (such as answering requests needed for deployment of other SUs of the same SA I guess...) are ready to answer requests.
* Starting the SU (going into the 'STARTED' state) is the second phase of the the two-phases start: request related to deployment are sent now.

We don't really implement that, all endpoints are registered after start, but actually we have no example where this two-phase start is needed... this is not clear!
{petalslink}


h1. Registering endpoints and processing messages for them

On the one hand, once an endpoint is registered, there is the possibility of request messages arriving for it, this is why SUs endpoints are only registered once their SU have been completely started.
On the other hand, when a component is stopped, it stops processing requests, but the endpoints are not unregistered: in that case, the messages are not lost and simply kept in the delivery channel of the component until it is started again.

It is the responsibility of the administrator to not keep a component in a 'STOPPED' state while its SUs are in a 'STARTED' state for too long.

To summarize:
* Message processing is the responsibility of the component lifecycle at the transition between 'STOPPED' and 'STARTED'.
* Registration of SU endpoints is the responsibility of the SU lifecycle at the transition between 'STOPPED' and 'STARTED'.
* For the special case of native services, registration of endpoints is the responsibility of the component lifecycle at the transition between 'SHUTDOWN' and 'STARTED'/'STOPPED'.