0
# Application Lifecycle
1

2
The Application Lifecycle capability manages the complete lifecycle of Quarkus applications, from startup to shutdown, including lifecycle events and application modes.
3

4
## Core Classes
5

6
### Main Application Entry Point
7

8
```java { .api }
9
public final class Quarkus {
10
    // Run QuarkusApplication until completion
11
    public static int run(Class<? extends QuarkusApplication> quarkusApplication, String... args);
12
    
13
    // Run with custom exit handling
14
    public static int run(Class<? extends QuarkusApplication> quarkusApplication, 
15
                         BiConsumer<Integer, Throwable> exitHandler, String... args);
16
    
17
    // Start application that runs until signal or exit call
18
    public static void run(String... args);
19
    
20
    // Shutdown methods
21
    public static void asyncExit(int code);
22
    public static void asyncExit();
23
    public static void waitForExit();
24
    public static void blockingExit();
25
    
26
    // Manual lifecycle control for serverless environments
27
    public static void manualInitialize();
28
    public static void manualStart();
29
    
30
    // Thread checking
31
    public static boolean isMainThread(Thread thread);
32
}
33
```
34

35
### Application Interface
36

37
```java { .api }
38
// Interface for command-mode applications
39
public interface QuarkusApplication {
40
    /**
41
     * Main application entry point.
42
     * @param args Command line arguments
43
     * @return Exit code (0 for success, non-zero for error)
44
     * @throws Exception Any unhandled exception
45
     */
46
    int run(String... args) throws Exception;
47
}
48
```
49

50
### Application Base Class
51

52
```java { .api }
53
public abstract class Application implements Closeable {
54
    // Abstract methods for subclasses
55
    public abstract void doStart(String[] args) throws Exception;
56
    public abstract void doStop() throws Exception;
57
    public abstract String getName();
58
    
59
    // Lifecycle management
60
    public void start(String[] args) throws Exception;
61
    public void stop();
62
    public void stop(Runnable afterStopTask);
63
    public void close();
64
    public void awaitShutdown();
65
    
66
    // State checking
67
    public boolean isStarted();
68
    
69
    // Static access to current application
70
    public static Application currentApplication();
71
}
72
```
73

74
## Lifecycle Events
75

76
### Startup Event
77

78
```java { .api }
79
public class StartupEvent extends jakarta.enterprise.event.Startup {
80
    // CDI event fired after application startup
81
    // Use with @Observes annotation
82
}
83
```
84

85
### Shutdown Event
86

87
```java { .api }
88
public class ShutdownEvent extends jakarta.enterprise.event.Shutdown {
89
    /**
90
     * Check if this is a standard shutdown (vs signal-based)
91
     * @return true for normal shutdown, false for signal interruption
92
     */
93
    public boolean isStandardShutdown();
94
    
95
    public enum ShutdownReason {
96
        STANDARD,      // Normal application shutdown
97
        NON_STANDARD   // Signal-based shutdown (SIGTERM, SIGINT)
98
    }
99
}
100
```
101

102
### Startup Task Interface
103

104
```java { .api }
105
public interface StartupTask {
106
    /**
107
     * Execute startup task during application initialization.
108
     * @param context Startup context for sharing data between tasks
109
     * @throws Exception Any initialization error
110
     */
111
    void deploy(StartupContext context) throws Exception;
112
}
113

114
public class StartupContext implements Closeable {
115
    Object getValue(String name);
116
    void putValue(String name, Object value);
117
    void setCommandLineArguments(String[] args);
118
    String getCurrentBuildStepName();
119
    void close();
120
}
121
```
122

123
## Main Method Annotation
124

125
```java { .api }
126
@Retention(RetentionPolicy.RUNTIME)
127
@Target(ElementType.TYPE)
128
public @interface QuarkusMain {
129
    /**
130
     * Unique name for the main method (optional).
131
     * @return Main method name
132
     */
133
    String name() default "";
134
}
135
```
136

137
## Usage Examples
138

139
### Basic Application
140

141
```java
142
import io.quarkus.runtime.Quarkus;
143
import io.quarkus.runtime.QuarkusApplication;
144
import io.quarkus.runtime.annotations.QuarkusMain;
145

146
@QuarkusMain
147
public class SimpleApplication implements QuarkusApplication {
148
    @Override
149
    public int run(String... args) throws Exception {
150
        System.out.println("Application started with args: " + Arrays.toString(args));
151
        
152
        // Application logic here
153
        doBusinessLogic();
154
        
155
        // Wait for shutdown signal
156
        Quarkus.waitForExit();
157
        return 0;
158
    }
159
    
160
    private void doBusinessLogic() {
161
        // Your application logic
162
    }
163
}
164
```
165

166
### Lifecycle Event Handling
167

168
```java
169
import jakarta.enterprise.context.ApplicationScoped;
170
import jakarta.enterprise.event.Observes;
171
import io.quarkus.runtime.StartupEvent;
172
import io.quarkus.runtime.ShutdownEvent;
173
import io.quarkus.logging.Log;
174

175
@ApplicationScoped
176
public class ApplicationLifecycleHandler {
177
    
178
    void onStart(@Observes StartupEvent event) {
179
        Log.info("Application is starting up");
180
        // Initialize resources, connections, etc.
181
        initializeResources();
182
    }
183
    
184
    void onStop(@Observes ShutdownEvent event) {
185
        Log.info("Application is shutting down");
186
        if (event.isStandardShutdown()) {
187
            Log.info("Normal shutdown process");
188
        } else {
189
            Log.warn("Emergency shutdown (signal received)");
190
        }
191
        // Cleanup resources
192
        cleanupResources();
193
    }
194
    
195
    private void initializeResources() {
196
        // Resource initialization logic
197
    }
198
    
199
    private void cleanupResources() {
200
        // Resource cleanup logic
201
    }
202
}
203
```
204

205
### Custom Exit Handler
206

207
```java
208
import io.quarkus.runtime.Quarkus;
209
import io.quarkus.runtime.QuarkusApplication;
210
import java.util.function.BiConsumer;
211

212
public class ApplicationWithCustomExit implements QuarkusApplication {
213
    @Override
214
    public int run(String... args) throws Exception {
215
        BiConsumer<Integer, Throwable> exitHandler = (exitCode, throwable) -> {
216
            if (throwable != null) {
217
                System.err.println("Application failed: " + throwable.getMessage());
218
            }
219
            System.out.println("Application exiting with code: " + exitCode);
220
        };
221
        
222
        Quarkus.run(MyMainApplication.class, exitHandler, args);
223
        return 0;
224
    }
225
}
226

227
class MyMainApplication implements QuarkusApplication {
228
    @Override
229
    public int run(String... args) throws Exception {
230
        // Main application logic
231
        return 0;
232
    }
233
}
234
```
235

236
### Serverless Application (Lambda/Azure Functions)
237

238
```java
239
import io.quarkus.runtime.Quarkus;
240

241
public class ServerlessHandler {
242
    private static boolean initialized = false;
243
    
244
    public String handleRequest(String input) {
245
        if (!initialized) {
246
            // Manual initialization for serverless
247
            Quarkus.manualInitialize();
248
            Quarkus.manualStart();
249
            initialized = true;
250
        }
251
        
252
        // Process request
253
        return processInput(input);
254
    }
255
    
256
    private String processInput(String input) {
257
        // Your business logic
258
        return "Processed: " + input;
259
    }
260
}
261
```
262

263
### Multiple Main Methods
264

265
```java
266
@QuarkusMain(name = "web-server")
267
public class WebServerApplication implements QuarkusApplication {
268
    @Override
269
    public int run(String... args) throws Exception {
270
        // Start web server
271
        return 0;
272
    }
273
}
274

275
@QuarkusMain(name = "batch-processor")
276
public class BatchProcessorApplication implements QuarkusApplication {
277
    @Override
278
    public int run(String... args) throws Exception {
279
        // Run batch processing
280
        return 0;
281
    }
282
}
283
```
284

285
Run specific main method:
286
```bash
287
java -jar app.jar -Dquarkus.main.name=batch-processor
288
```
289

290
## Error Handling
291

292
The lifecycle system provides several exception types for different failure scenarios:
293

294
```java { .api }
295
// Thrown when port binding fails during startup
296
public class QuarkusBindException extends RuntimeException {
297
    public QuarkusBindException(String message, Throwable cause);
298
}
299

300
// Internal exception to halt build steps
301
public class PreventFurtherStepsException extends RuntimeException {
302
    public PreventFurtherStepsException(String message);
303
}
304
```