0
# Core Runtime and Application Lifecycle
1

2
The Quarkus core runtime provides the fundamental classes and annotations for application lifecycle management, main entry points, and build-time processing configuration.
3

4
## Core Application Classes
5

6
### Quarkus Main Class
7

8
```java { .api }
9
public class Quarkus {
10
    public static void run(Class<? extends QuarkusApplication> application, String... args);
11
    public static void run(Class<? extends QuarkusApplication> application, 
12
                           BiConsumer<Integer, Throwable> exitHandler, String... args);
13
    public static void run(String... args);
14
    public static void waitForExit();
15
    public static void blockingExit();
16
    public static void asyncExit();
17
    public static void asyncExit(int code);
18
    public static boolean isMainThread(Thread thread);
19
    public static void manualInitialize();
20
    public static void manualStart();
21
}
22
```
23

24
The primary entry point for Quarkus applications. Use `run()` to start an application and `waitForExit()` to block until shutdown.
25

26
**Usage Example:**
27
```java
28
import io.quarkus.runtime.Quarkus;
29
import io.quarkus.runtime.QuarkusApplication;
30

31
public static void main(String... args) {
32
    Quarkus.run(MyApp.class, args);
33
}
34

35
public static class MyApp implements QuarkusApplication {
36
    @Override
37
    public int run(String... args) throws Exception {
38
        // Application logic here
39
        Quarkus.waitForExit();
40
        return 0;
41
    }
42
}
43
```
44

45
### QuarkusApplication Interface
46

47
```java { .api }
48
public interface QuarkusApplication {
49
    int run(String... args) throws Exception;
50
}
51
```
52

53
Interface for command-mode applications with custom startup logic. Implement this interface when you need to control the application lifecycle beyond simple REST services.
54

55
### Application Abstract Class
56

57
```java { .api }
58
public abstract class Application implements Closeable {
59
    public static final String APP_CLASS_NAME = "io.quarkus.runner.ApplicationImpl";
60
    
61
    // Public lifecycle methods
62
    public final void start(String[] args);
63
    public final void stop();
64
    public final void stop(Runnable afterStopTask);
65
    public final void close();
66
    public void awaitShutdown();
67
    public boolean isStarted();
68
    
69
    // Static access
70
    public static Application currentApplication();
71
    
72
    // Abstract methods for subclasses
73
    protected abstract void doStart(String[] args);
74
    protected abstract void doStop();
75
    public abstract String getName();
76
}
77
```
78

79
Base abstract class for Quarkus applications providing thread-safe lifecycle management. Generated application classes extend this to provide the actual implementation.
80

81
### ApplicationLifecycleManager
82

83
```java { .api }
84
public class ApplicationLifecycleManager {
85
    public static final String QUARKUS_APPCDS_GENERATE_PROP = "quarkus.appcds.generate";
86
    
87
    // Application lifecycle
88
    public static void run(Application application, String... args);
89
    public static void run(Application application, Class<? extends QuarkusApplication> quarkusApplication,
90
                          BiConsumer<Integer, Throwable> exitCodeHandler, String... args);
91
    
92
    // Application access and state
93
    public static Application getCurrentApplication();
94
    public static int getExitCode();
95
    public static boolean isVmShuttingDown();
96
    public static boolean isAppCDSGeneration();
97
    
98
    // Exit handling
99
    public static void exit();
100
    public static void exit(int code);
101
    public static void waitForExit();
102
    
103
    // Exit code handlers
104
    public static BiConsumer<Integer, Throwable> getDefaultExitCodeHandler();
105
    public static void setDefaultExitCodeHandler(BiConsumer<Integer, Throwable> defaultExitCodeHandler);
106
    public static void setDefaultExitCodeHandler(Consumer<Integer> defaultExitCodeHandler);
107
    
108
    // Callbacks
109
    public static void setAlreadyStartedCallback(Consumer<Boolean> alreadyStartedCallback);
110
}
111
```
112

113
Manages application lifecycle including startup, shutdown handling, exit code management, and signal handling for graceful termination.
114

115
## Core Annotations
116

117
### @QuarkusMain
118

119
```java { .api }
120
@Target(ElementType.TYPE)
121
@Retention(RetentionPolicy.RUNTIME)
122
public @interface QuarkusMain {
123
    String name() default "";
124
}
125
```
126

127
Marks the main entry point class for a Quarkus application. Use this when you need a custom main method instead of standard REST services.
128

129
**Usage Example:**
130
```java
131
@QuarkusMain
132
public class Main {
133
    public static void main(String... args) {
134
        Quarkus.run(HelloApp.class, args);
135
    }
136
    
137
    public static class HelloApp implements QuarkusApplication {
138
        @Override
139
        public int run(String... args) throws Exception {
140
            System.out.println("Application started");
141
            Quarkus.waitForExit();
142
            return 0;
143
        }
144
    }
145
}
146
```
147

148
### Build-Time Processing Annotations
149

150
```java { .api }
151
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
152
@Retention(RetentionPolicy.RUNTIME)
153
public @interface RegisterForReflection {
154
    Class<?>[] value() default {};
155
    String[] classNames() default {};
156
    boolean methods() default true;
157
    boolean fields() default true;
158
    boolean ignoreNested() default false;
159
}
160
```
161

162
Registers classes for reflection in native image compilation.
163

164
**Usage Example:**
165
```java
166
@RegisterForReflection(classNames = {"com.example.MyClass", "com.example.AnotherClass"})
167
public class ReflectionConfiguration {
168
}
169
```
170

171
```java { .api }
172
@Target(ElementType.TYPE)
173
@Retention(RetentionPolicy.RUNTIME)
174
public @interface RegisterForProxy {
175
    Class<?>[] value() default {};
176
}
177
```
178

179
Registers interfaces for dynamic proxy generation in native images.
180

181
```java { .api }
182
@Target(ElementType.CONSTRUCTOR)
183
@Retention(RetentionPolicy.RUNTIME)
184
public @interface RecordableConstructor {
185
}
186
```
187

188
Marks constructors as recordable during build-time processing.
189

190
```java { .api }
191
@Target(ElementType.TYPE)
192
@Retention(RetentionPolicy.RUNTIME)
193
public @interface Recorder {
194
}
195
```
196

197
Marks classes that participate in bytecode recording during the build process.
198

199
### Initialization Phase Annotations
200

201
```java { .api }
202
@Target(ElementType.METHOD)
203
@Retention(RetentionPolicy.RUNTIME)
204
public @interface StaticInit {
205
}
206
```
207

208
Indicates that a recorder method should run during static initialization phase.
209

210
```java { .api }
211
@Target(ElementType.METHOD)
212
@Retention(RetentionPolicy.RUNTIME)
213
public @interface RuntimeInit {
214
}
215
```
216

217
Indicates that a recorder method should run during runtime initialization phase.
218

219
## Application Lifecycle Events
220

221
### Startup and Shutdown Events
222

223
```java { .api }
224
public class StartupEvent {
225
    // CDI event fired during application startup
226
}
227

228
public class ShutdownEvent {
229
    // CDI event fired during application shutdown
230
}
231
```
232

233
CDI events that can be observed to hook into application lifecycle.
234

235
**Usage Example:**
236
```java
237
import jakarta.enterprise.event.Observes;
238

239
@ApplicationScoped
240
public class LifecycleBean {
241
    
242
    void onStart(@Observes StartupEvent ev) {
243
        System.out.println("The application is starting...");
244
    }
245

246
    void onStop(@Observes ShutdownEvent ev) {
247
        System.out.println("The application is stopping...");
248
    }
249
}
250
```
251

252
### Lifecycle Annotations
253

254
```java { .api }
255
@Target(ElementType.METHOD)
256
@Retention(RetentionPolicy.RUNTIME)
257
public @interface Startup {
258
    int value() default 0;  // Priority
259
}
260
```
261

262
Marks methods to execute during application startup.
263

264
```java { .api }
265
@Target(ElementType.METHOD)
266
@Retention(RetentionPolicy.RUNTIME)
267
public @interface Shutdown {
268
    int value() default 0;  // Priority
269
}
270
```
271

272
Marks methods to execute during application shutdown.
273

274
**Usage Example:**
275
```java
276
@ApplicationScoped
277
public class AppInitializer {
278
    
279
    @Startup
280
    void init() {
281
        System.out.println("Initializing application resources...");
282
    }
283
    
284
    @Shutdown
285
    void cleanup() {
286
        System.out.println("Cleaning up application resources...");
287
    }
288
}
289
```
290

291
### StartupTask Interface
292

293
```java { .api }
294
public interface StartupTask {
295
    void deploy(StartupContext context);
296
}
297
```
298

299
Interface for implementing build-time startup initialization tasks. Generally provided by generated bytecode during Quarkus build process.
300

301
```java { .api }
302
public class StartupContext implements Closeable {
303
    public void putValue(String name, Object value);
304
    public Object getValue(String name);
305
    public void close();
306
    public void setCommandLineArguments(String[] commandLineArguments);
307
    public String getCurrentBuildStepName();
308
    public void setCurrentBuildStepName(String currentBuildStepName);
309
}
310
```
311

312
## ExecutionModeManager
313

314
```java { .api }
315
public final class ExecutionModeManager {
316
    public static void staticInit();
317
    public static void runtimeInit();
318
    public static void running();
319
    public static void unset();
320
    public static ExecutionMode getExecutionMode();
321
}
322

323
public enum ExecutionMode {
324
    STATIC_INIT,      // Static initialization phase
325
    RUNTIME_INIT,     // Runtime initialization phase  
326
    RUNNING,          // Application is running
327
    UNSET;            // Unset state
328
    
329
    public static ExecutionMode current();
330
}
331
```
332

333
Manages the current execution phase during Quarkus application lifecycle. The ExecutionMode enum tracks whether the application is in static initialization, runtime initialization, running, or unset state.
334

335
## Configuration Runtime Support
336

337
### QuarkusConfigFactory
338

339
```java { .api }
340
public final class QuarkusConfigFactory extends SmallRyeConfigFactory {
341
    @Override
342
    public SmallRyeConfig getConfigFor(SmallRyeConfigProviderResolver configProviderResolver, 
343
                                       ClassLoader classLoader);
344
    public static void setConfig(SmallRyeConfig config);
345
    public static void releaseTCCLConfig();
346
}
347
```
348

349
Factory for creating and managing SmallRye configuration instances with Quarkus-specific enhancements.
350

351
### ConfigUtils
352

353
```java { .api }
354
public final class ConfigUtils {
355
    public static SmallRyeConfigBuilder configBuilder();
356
    public static SmallRyeConfigBuilder emptyConfigBuilder();
357
    public static List<String> getProfiles();
358
    public static boolean isProfileActive(String profile);
359
    public static boolean isPropertyPresent(String propertyName);
360
    public static boolean isPropertyNonEmpty(String propertyName);
361
    public static boolean isAnyPropertyPresent(Collection<String> propertyNames);
362
    public static <T> Optional<T> getFirstOptionalValue(List<String> propertyNames, Class<T> propertyType);
363
}
364
```
365

366
Utility methods for configuration management, profile checking, and property validation.
367

368
### ConfigurationException
369

370
```java { .api }
371
public class ConfigurationException extends RuntimeException implements ConfigurationProblem {
372
    public ConfigurationException(Set<String> configKeys);
373
    public ConfigurationException(String msg);
374
    public ConfigurationException(String msg, Set<String> configKeys);
375
    public ConfigurationException(Throwable cause, Set<String> configKeys);
376
    public ConfigurationException(String msg, Throwable cause);
377
    public ConfigurationException(String msg, Throwable cause, Set<String> configKeys);
378
    public ConfigurationException(Throwable cause);
379
    
380
    public Set<String> getConfigKeys();
381
}
382
```
383

384
Exception thrown for configuration-related errors with support for tracking problematic configuration keys.