0
# Lifecycle Management
1

2
State machine-based deployment lifecycle with standard states, bindings, and transition management. The lifecycle system defines how applications progress through deployment states and provides hooks for custom behavior at each transition.
3

4
## Capabilities
5

6
### AppLifeCycle
7

8
Manages the lifecycle of an App in the DeploymentManager with a default graph setup. Extends the Graph class to provide a complete state machine for deployment operations.
9

10
```java { .api }
11
/**
12
 * Manages the lifecycle of an App in the DeploymentManager with a default graph setup
13
 */
14
public class AppLifeCycle extends Graph {
15
    // Standard lifecycle state constants
16
    public static final String UNDEPLOYED = "undeployed";
17
    public static final String DEPLOYING = "deploying"; 
18
    public static final String DEPLOYED = "deployed";
19
    public static final String STARTING = "starting";
20
    public static final String STARTED = "started";
21
    public static final String STOPPING = "stopping";
22
    public static final String UNDEPLOYING = "undeploying";
23
    public static final String FAILED = "failed";
24
    
25
    /** Creates default lifecycle graph with standard states and transitions */
26
    public AppLifeCycle();
27
    
28
    /** Adds a lifecycle binding for state transition processing */
29
    public void addBinding(AppLifeCycle.Binding binding);
30
    
31
    /** Removes a lifecycle binding */
32
    public void removeBinding(AppLifeCycle.Binding binding);
33
    
34
    /** Returns all lifecycle bindings */
35
    public Set<AppLifeCycle.Binding> getBindings();
36
    
37
    /** Returns bindings for a specific node */
38
    public Set<AppLifeCycle.Binding> getBindings(Node node);
39
    
40
    /** Returns bindings for a specific node name */
41
    public Set<AppLifeCycle.Binding> getBindings(String nodeName);
42
    
43
    /** Executes all bindings for a node during app lifecycle transition */
44
    public void runBindings(Node node, App app, DeploymentManager deploymentManager) throws Throwable;
45
}
46
```
47

48
**Usage Examples:**
49

50
```java
51
import org.eclipse.jetty.deploy.AppLifeCycle;
52
import org.eclipse.jetty.deploy.bindings.*;
53

54
// Get the lifecycle from deployment manager
55
AppLifeCycle lifecycle = deploymentManager.getLifeCycle();
56

57
// Add custom bindings for specific states
58
lifecycle.addBinding(new DebugBinding(AppLifeCycle.DEPLOYING, AppLifeCycle.STARTED));
59

60
// Custom binding implementation
61
AppLifeCycle.Binding customBinding = new AppLifeCycle.Binding() {
62
    @Override
63
    public String[] getBindingTargets() {
64
        return new String[] { AppLifeCycle.STARTED };
65
    }
66
    
67
    @Override
68
    public void processBinding(Node node, App app) throws Exception {
69
        System.out.println("App started: " + app.getPath());
70
        // Custom initialization logic here
71
    }
72
};
73
lifecycle.addBinding(customBinding);
74

75
// Check bindings for a specific state
76
Set<AppLifeCycle.Binding> startBindings = lifecycle.getBindings(AppLifeCycle.STARTED);
77
System.out.println("Bindings for 'started' state: " + startBindings.size());
78
```
79

80
### AppLifeCycle.Binding Interface
81

82
Interface for objects that process lifecycle state transitions. Bindings are executed when apps transition through lifecycle states.
83

84
```java { .api }
85
/**
86
 * Interface for objects that process lifecycle state transitions
87
 */
88
public static interface AppLifeCycle.Binding {
89
    /** Returns array of target node names this binding should be executed for */
90
    String[] getBindingTargets();
91
    
92
    /** Processes a lifecycle binding when an app transitions to the target state */
93
    void processBinding(Node node, App app) throws Exception;
94
}
95
```
96

97
### Standard Bindings
98

99
Pre-built binding implementations for standard deployment operations.
100

101
#### DebugBinding
102

103
Debug binding that logs processing information during state transitions.
104

105
```java { .api }
106
/**
107
 * Debug binding that logs processing information
108
 */
109
public class DebugBinding implements AppLifeCycle.Binding {
110
    /** Creates binding for a single target state */
111
    public DebugBinding(String target);
112
    
113
    /** Creates binding for multiple target states */
114
    public DebugBinding(String... targets);
115
    
116
    /** Returns binding targets */
117
    public String[] getBindingTargets();
118
    
119
    /** Processes binding with debug logging */
120
    public void processBinding(Node node, App app) throws Exception;
121
}
122
```
123

124
#### OrderedGroupBinding  
125

126
Provides ordered execution of multiple bindings within a declared binding target.
127

128
```java { .api }
129
/**
130
 * Provides ordered execution of bindings within a declared binding target
131
 */
132
public class OrderedGroupBinding implements AppLifeCycle.Binding {
133
    /** Creates ordered group for specified target states */
134
    public OrderedGroupBinding(String[] bindingTargets);
135
    
136
    /** Adds a binding to the ordered execution group */
137
    public void addBinding(AppLifeCycle.Binding binding);
138
    
139
    /** Adds multiple bindings to the ordered execution group */
140
    public void addBindings(AppLifeCycle.Binding[] bindings);
141
    
142
    /** Returns binding targets */
143
    public String[] getBindingTargets();
144
    
145
    /** Processes all bindings in the specified order */
146
    public void processBinding(Node node, App app) throws Exception;
147
}
148
```
149

150
#### StandardDeployer
151

152
Standard deployer binding for the "deploying" lifecycle state.
153

154
```java { .api }
155
/**
156
 * Standard deployer binding for the "deploying" lifecycle state
157
 */
158
public class StandardDeployer implements AppLifeCycle.Binding {
159
    /** Creates standard deployer binding */
160
    public StandardDeployer();
161
    
162
    /** Returns ["deploying"] */
163
    public String[] getBindingTargets();
164
    
165
    /** Deploys the context handler to the server */
166
    public void processBinding(Node node, App app) throws Exception;
167
}
168
```
169

170
#### StandardStarter
171

172
Standard starter binding for the "starting" lifecycle state.
173

174
```java { .api }
175
/**
176
 * Standard starter binding for the "starting" lifecycle state  
177
 */
178
public class StandardStarter implements AppLifeCycle.Binding {
179
    /** Creates standard starter binding */
180
    public StandardStarter();
181
    
182
    /** Returns ["starting"] */
183
    public String[] getBindingTargets();
184
    
185
    /** Starts the context handler */
186
    public void processBinding(Node node, App app) throws Exception;
187
}
188
```
189

190
#### StandardStopper
191

192
Standard stopper binding for the "stopping" lifecycle state.
193

194
```java { .api }
195
/**
196
 * Standard stopper binding for the "stopping" lifecycle state
197
 */
198
public class StandardStopper implements AppLifeCycle.Binding {
199
    /** Creates standard stopper binding */
200
    public StandardStopper();
201
    
202
    /** Returns ["stopping"] */
203
    public String[] getBindingTargets();
204
    
205
    /** Stops the context handler */
206
    public void processBinding(Node node, App app) throws Exception;
207
}
208
```
209

210
#### StandardUndeployer
211

212
Standard undeployer binding for the "undeploying" lifecycle state.
213

214
```java { .api }
215
/**
216
 * Standard undeployer binding for the "undeploying" lifecycle state
217
 */
218
public class StandardUndeployer implements AppLifeCycle.Binding {
219
    /** Creates standard undeployer binding */
220
    public StandardUndeployer();
221
    
222
    /** Returns ["undeploying"] */
223
    public String[] getBindingTargets();
224
    
225
    /** Undeploys and destroys the context handler */
226
    public void processBinding(Node node, App app) throws Exception;
227
}
228
```
229

230
**Usage Examples:**
231

232
```java
233
import org.eclipse.jetty.deploy.bindings.*;
234

235
// Use debug binding to trace lifecycle transitions
236
DebugBinding debugAll = new DebugBinding(
237
    AppLifeCycle.DEPLOYING,
238
    AppLifeCycle.STARTING, 
239
    AppLifeCycle.STOPPING,
240
    AppLifeCycle.UNDEPLOYING
241
);
242
lifecycle.addBinding(debugAll);
243

244
// Create ordered execution group for complex deployment
245
OrderedGroupBinding deploymentGroup = new OrderedGroupBinding(
246
    new String[] { AppLifeCycle.DEPLOYING }
247
);
248

249
// Add bindings in specific order
250
deploymentGroup.addBinding(new CustomSecurityBinding());
251
deploymentGroup.addBinding(new StandardDeployer());
252
deploymentGroup.addBinding(new CustomLoggingBinding());
253

254
lifecycle.addBinding(deploymentGroup);
255

256
// Override standard bindings with custom implementations
257
lifecycle.removeBinding(standardDeployer); // Remove default
258
lifecycle.addBinding(new CustomDeployer()); // Add custom
259

260
// Conditional binding based on app properties
261
AppLifeCycle.Binding conditionalBinding = new AppLifeCycle.Binding() {
262
    @Override
263
    public String[] getBindingTargets() {
264
        return new String[] { AppLifeCycle.STARTED };
265
    }
266
    
267
    @Override
268
    public void processBinding(Node node, App app) throws Exception {
269
        if (app.getProperties().containsKey("enable.monitoring")) {
270
            // Enable monitoring for this app
271
            MonitoringService.register(app);
272
        }
273
    }
274
};
275
lifecycle.addBinding(conditionalBinding);
276
```
277

278
## Lifecycle State Flow
279

280
The standard lifecycle follows this state progression:
281

282
1. **UNDEPLOYED** → **DEPLOYING** → **DEPLOYED** → **STARTING** → **STARTED**
283
2. **STARTED** → **STOPPING** → **DEPLOYED** → **UNDEPLOYING** → **UNDEPLOYED**  
284
3. Any state → **FAILED** (on error)
285

286
**State Descriptions:**
287

288
- **UNDEPLOYED**: Initial state, app not yet processed
289
- **DEPLOYING**: App is being deployed (context handler creation)
290
- **DEPLOYED**: App successfully deployed but not started
291
- **STARTING**: App is being started
292
- **STARTED**: App is fully running and serving requests
293
- **STOPPING**: App is being stopped
294
- **UNDEPLOYING**: App is being undeployed (cleanup)
295
- **FAILED**: App encountered an error during lifecycle transition
296

297
**Usage Examples:**
298

299
```java
300
// Monitor app lifecycle states
301
App app = deploymentManager.getApp("/path/to/app.war");
302
DeploymentManager.AppEntry entry = deploymentManager.getAppEntries()
303
    .stream()
304
    .filter(e -> e.getApp().equals(app))
305
    .findFirst()
306
    .orElse(null);
307

308
if (entry != null) {
309
    Node currentState = entry.getLifecyleNode();
310
    System.out.println("App state: " + currentState.getName());
311
    
312
    // Request state transitions
313
    switch (currentState.getName()) {
314
        case AppLifeCycle.DEPLOYED:
315
            deploymentManager.requestAppGoal(app, AppLifeCycle.STARTED);
316
            break;
317
        case AppLifeCycle.STARTED:
318
            deploymentManager.requestAppGoal(app, AppLifeCycle.STOPPED);
319
            break;
320
        case AppLifeCycle.FAILED:
321
            // Attempt recovery
322
            deploymentManager.requestAppGoal(app, AppLifeCycle.UNDEPLOYED);
323
            break;
324
    }
325
}
326
```