0
# Quarkus Core Runtime
1

2
Quarkus Core Runtime provides the foundational components for Quarkus, a Cloud Native and Container First Java framework designed for building high-performance applications with minimal footprint. It includes essential runtime services, dependency injection capabilities, configuration management, and core infrastructure needed to run Quarkus applications.
3

4
## Package Information
5

6
- **Package Name**: quarkus-core
7
- **Package Type**: maven
8
- **Group ID**: io.quarkus
9
- **Artifact ID**: quarkus-core
10
- **Language**: Java
11
- **Installation**: Include in your Maven `pom.xml`:
12

13
```xml
14
<dependency>
15
    <groupId>io.quarkus</groupId>
16
    <artifactId>quarkus-core</artifactId>
17
    <version>3.23.0</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
// Application lifecycle and entry points
25
import io.quarkus.runtime.Quarkus;
26
import io.quarkus.runtime.QuarkusApplication;
27
import io.quarkus.runtime.Application;
28

29
// Lifecycle events
30
import io.quarkus.runtime.StartupEvent;
31
import io.quarkus.runtime.ShutdownEvent;
32

33
// Runtime context
34
import io.quarkus.runtime.LaunchMode;
35
import io.quarkus.runtime.ExecutionMode;
36

37
// Configuration annotations
38
import io.quarkus.runtime.annotations.ConfigRoot;
39
import io.quarkus.runtime.annotations.ConfigItem;
40

41
// Reflection and native image support
42
import io.quarkus.runtime.annotations.RegisterForReflection;
43

44
// Logging
45
import io.quarkus.logging.Log;
46
```
47

48
## Basic Usage
49

50
### Simple Application Startup
51

52
```java
53
import io.quarkus.runtime.Quarkus;
54
import io.quarkus.runtime.QuarkusApplication;
55
import io.quarkus.runtime.annotations.QuarkusMain;
56

57
@QuarkusMain
58
public class MyApplication implements QuarkusApplication {
59
    @Override
60
    public int run(String... args) throws Exception {
61
        System.out.println("Application starting...");
62
        
63
        // Application logic here
64
        
65
        Quarkus.waitForExit();
66
        return 0;
67
    }
68
}
69
```
70

71
### Lifecycle Event Handling
72

73
```java
74
import jakarta.enterprise.event.Observes;
75
import io.quarkus.runtime.StartupEvent;
76
import io.quarkus.runtime.ShutdownEvent;
77
import io.quarkus.logging.Log;
78

79
public class LifecycleHandler {
80
    
81
    void onStart(@Observes StartupEvent ev) {
82
        Log.info("Application starting up");
83
    }
84
    
85
    void onStop(@Observes ShutdownEvent ev) {
86
        Log.info("Application shutting down");
87
        if (ev.isStandardShutdown()) {
88
            Log.info("Standard shutdown");
89
        }
90
    }
91
}
92
```
93

94
### Configuration
95

96
```java
97
import io.quarkus.runtime.annotations.ConfigRoot;
98
import io.quarkus.runtime.annotations.ConfigItem;
99
import io.quarkus.runtime.annotations.ConfigPhase;
100

101
@ConfigRoot(phase = ConfigPhase.RUNTIME_INIT)
102
public class MyConfig {
103
    
104
    @ConfigItem(defaultValue = "default-value")
105
    public String property;
106
    
107
    @ConfigItem(defaultValue = "8080")
108
    public int port;
109
}
110
```
111

112
## Architecture
113

114
Quarkus Core Runtime is organized into several key functional areas:
115

116
- **Application Lifecycle**: Entry points, startup/shutdown management
117
- **Configuration System**: Annotations and converters for application config
118
- **Reflection & Native Image**: Registration for GraalVM native compilation
119
- **Build-Time Processing**: Recorder annotations for bytecode generation
120
- **Logging**: Simplified static logging facade
121
- **Threading Control**: IO thread detection and blocking operation control
122
- **Runtime Context**: Execution modes and launch mode detection
123

124
## Capabilities
125

126
### Application Lifecycle Management
127

128
Controls application startup, shutdown, and lifecycle events with support for both traditional and command-mode applications.
129

130
```java { .api }
131
// Primary application entry point
132
public final class Quarkus {
133
    public static int run(Class<? extends QuarkusApplication> quarkusApplication, String... args);
134
    public static int run(Class<? extends QuarkusApplication> quarkusApplication, 
135
                         BiConsumer<Integer, Throwable> exitHandler, String... args);
136
    public static void run(String... args);
137
    public static void asyncExit(int code);
138
    public static void asyncExit();
139
    public static void waitForExit();
140
    public static void blockingExit();
141
    public static void manualInitialize();
142
    public static void manualStart();
143
    public static boolean isMainThread(Thread thread);
144
}
145

146
// Command-mode application interface
147
public interface QuarkusApplication {
148
    int run(String... args) throws Exception;
149
}
150

151
// Application lifecycle events
152
public class StartupEvent extends jakarta.enterprise.event.Startup {}
153
public class ShutdownEvent extends jakarta.enterprise.event.Shutdown {
154
    public boolean isStandardShutdown();
155
}
156
```
157

158
[Application Lifecycle](./application-lifecycle.md)
159

160
### Configuration System
161

162
Comprehensive configuration management with annotations, converters, and runtime configuration support.
163

164
```java { .api }
165
// Configuration root annotation
166
@Retention(RetentionPolicy.RUNTIME)
167
@Target(ElementType.TYPE)
168
public @interface ConfigRoot {
169
    ConfigPhase phase() default ConfigPhase.RUNTIME_INIT;
170
}
171

172
// Configuration item annotation
173
@Retention(RetentionPolicy.RUNTIME)
174
@Target({ElementType.FIELD, ElementType.METHOD})
175
public @interface ConfigItem {
176
    String name() default "";
177
    String defaultValue() default "";
178
    boolean generateDocumentation() default true;
179
}
180

181
// Configuration phases
182
public enum ConfigPhase {
183
    BUILD_TIME, RUNTIME_INIT, BOOTSTRAP
184
}
185
```
186

187
[Configuration System](./configuration.md)
188

189
### Runtime Context and Threading
190

191
Provides execution mode detection, launch mode management, and threading control for optimal performance.
192

193
```java { .api }
194
// Launch mode detection
195
public enum LaunchMode {
196
    NORMAL, DEVELOPMENT, TEST;
197
    
198
    public boolean isDevOrTest();
199
    public String getDefaultProfile();
200
    public static LaunchMode current();
201
    public static boolean isDev();
202
    public static boolean isRemoteDev();
203
}
204

205
// Execution mode tracking
206
public enum ExecutionMode {
207
    STATIC_INIT, RUNTIME_INIT, RUNNING, UNSET;
208
    
209
    public static ExecutionMode current();
210
}
211

212
// Blocking operation control
213
public final class BlockingOperationControl {
214
    public static boolean isBlockingAllowed();
215
    public static void setIoThreadDetector(IOThreadDetector... detectors);
216
}
217
```
218

219
[Runtime Context and Threading](./runtime-context.md)
220

221
### Native Image and Reflection Support
222

223
Registration system for GraalVM native image compilation with reflection and proxy support.
224

225
```java { .api }
226
// Reflection registration
227
@Retention(RetentionPolicy.RUNTIME)
228
@Target(ElementType.TYPE)
229
public @interface RegisterForReflection {
230
    boolean methods() default true;
231
    boolean fields() default true;
232
    boolean ignoreNested() default false;
233
    Class<?>[] targets() default {};
234
    String[] classNames() default {};
235
    boolean serialization() default false;
236
    boolean registerFullHierarchy() default false;
237
}
238

239
// Proxy registration
240
@Retention(RetentionPolicy.RUNTIME)
241
@Target(ElementType.TYPE)
242
public @interface RegisterForProxy {
243
    Class<?>[] value() default {};
244
}
245
```
246

247
[Native Image Support](./native-image.md)
248

249
### Build-Time Processing
250

251
Recorder system for build-time code generation and bytecode manipulation.
252

253
```java { .api }
254
// Recorder class marker
255
@Retention(RetentionPolicy.RUNTIME)
256
@Target(ElementType.TYPE)
257
public @interface Recorder {}
258

259
// Initialization phase markers
260
@Retention(RetentionPolicy.RUNTIME)
261
@Target(ElementType.METHOD)
262
public @interface StaticInit {}
263

264
@Retention(RetentionPolicy.RUNTIME)
265
@Target(ElementType.METHOD)
266
public @interface RuntimeInit {}
267

268
// Main method marker
269
@Retention(RetentionPolicy.RUNTIME)
270
@Target(ElementType.TYPE)
271
public @interface QuarkusMain {
272
    String name() default "";
273
}
274
```
275

276
[Build-Time Processing](./build-time.md)
277

278
### Logging System
279

280
Static logging facade with build-time optimization and multiple log levels.
281

282
```java { .api }
283
public final class Log {
284
    // Level checking
285
    public static boolean isTraceEnabled();
286
    public static boolean isDebugEnabled();
287
    public static boolean isInfoEnabled();
288
    public static boolean isWarnEnabled();
289
    public static boolean isErrorEnabled();
290
    public static boolean isFatalEnabled();
291
    public static boolean isEnabled(Logger.Level level);
292
    
293
    // Logging methods (trace, debug, info, warn, error, fatal)
294
    public static void trace(Object message);
295
    public static void trace(Object message, Throwable t);
296
    public static void tracef(String format, Object... params);
297
    public static void tracev(String format, Object... params);
298
    // Similar methods for debug, info, warn, error, fatal
299
    
300
    // Generic logging
301
    public static void log(Logger.Level level, Object message);
302
    public static void log(Logger.Level level, Object message, Throwable t);
303
}
304
```
305

306
[Logging System](./logging.md)
307

308
### CDI and Dependency Injection
309

310
Arc CDI container integration providing access to CDI context and bean management.
311

312
```java { .api }
313
// CDI container access
314
public final class Arc {
315
    public static ArcContainer initialize();
316
    public static ArcContainer initialize(ArcInitConfig config);
317
    public static ArcContainer container();
318
    public static void shutdown();
319
    public static void setExecutor(ExecutorService executor);
320
}
321

322
// Main CDI container interface
323
public interface ArcContainer {
324
    // Bean access
325
    <T> InstanceHandle<T> instance(Class<T> type, Annotation... qualifiers);
326
    <T> InstanceHandle<T> instance(TypeLiteral<T> type, Annotation... qualifiers);
327
    <T> InjectableInstance<T> select(Class<T> type, Annotation... qualifiers);
328
    <T> InjectableInstance<T> select(TypeLiteral<T> type, Annotation... qualifiers);
329
    <T> Supplier<InstanceHandle<T>> instanceSupplier(Class<T> type, Annotation... qualifiers);
330
    
331
    // Bean listing
332
    <T> List<InstanceHandle<T>> listAll(Class<T> type, Annotation... qualifiers);
333
    <T> List<InstanceHandle<T>> listAll(TypeLiteral<T> type, Annotation... qualifiers);
334
    
335
    // Context management
336
    ManagedContext requestContext();
337
    InjectableContext getActiveContext(Class<? extends Annotation> scopeType);
338
    Collection<InjectableContext> getContexts(Class<? extends Annotation> scopeType);
339
    
340
    // CDI integration
341
    BeanManager beanManager();
342
    void shutdown();
343
}
344

345
// Instance handle for managed beans
346
interface InstanceHandle<T> extends AutoCloseable {
347
    T get();
348
    InjectableBean<T> getBean();
349
    void destroy();
350
    void close();
351
    boolean isAvailable();
352
}
353

354
// Injectable instance for programmatic lookup
355
interface InjectableInstance<T> extends Instance<T>, Iterable<T> {
356
    <U extends T> InjectableInstance<U> select(Class<U> subtype, Annotation... qualifiers);
357
    <U extends T> InjectableInstance<U> select(TypeLiteral<U> subtype, Annotation... qualifiers);
358
    InjectableInstance<T> select(Annotation... qualifiers);
359
    InstanceHandle<T> getHandle();
360
    Iterable<InstanceHandle<T>> handles();
361
}
362
```
363

364
## Types
365

366
### Core Types
367

368
```java { .api }
369
// Application base class
370
public abstract class Application implements Closeable {
371
    public abstract void doStart(String[] args) throws Exception;
372
    public abstract void doStop() throws Exception;
373
    public abstract String getName();
374
    
375
    // Instance methods
376
    public void start(String[] args) throws Exception;
377
    public void stop();
378
    public void stop(Runnable afterStopTask);
379
    public void close();
380
    public void awaitShutdown();
381
    public boolean isStarted();
382
    public static Application currentApplication();
383
}
384

385
// Startup task context
386
public class StartupContext implements Closeable {
387
    public Object getValue(String name);
388
    public void putValue(String name, Object value);
389
    public void setCommandLineArguments(String[] args);
390
    public String getCurrentBuildStepName();
391
    public void close();
392
}
393

394
// Shutdown task context
395
public interface ShutdownContext {
396
    void addShutdownTask(Runnable runnable);
397
    void addLastShutdownTask(Runnable runnable);
398
}
399

400
// IO thread detector interface
401
public interface IOThreadDetector {
402
    boolean isInIOThread();
403
}
404
```
405

406
### Configuration Types
407

408
```java { .api }
409
// Memory size representation
410
public final class MemorySize {
411
    public MemorySize(long bytes);
412
    public long getBytes();
413
    public static MemorySize parse(String input);
414
    
415
    // String representation methods
416
    public String toString();
417
    public String toHumanReadableString();
418
}
419

420
// Configuration converters
421
public class DurationConverter implements Converter<Duration> {
422
    public Duration convert(String value);
423
}
424

425
public class MemorySizeConverter implements Converter<MemorySize> {
426
    public MemorySize convert(String value);
427
}
428

429
public class PathConverter implements Converter<Path> {
430
    public Path convert(String value);
431
}
432

433
public class InetAddressConverter implements Converter<InetAddress> {
434
    public InetAddress convert(String value);
435
}
436
```
437

438
### Exception Types
439

440
```java { .api }
441
// Runtime exceptions
442
public class BlockingOperationNotAllowedException extends IllegalStateException {
443
    public BlockingOperationNotAllowedException(String message);
444
}
445

446
public class QuarkusBindException extends RuntimeException {
447
    public QuarkusBindException(String message, Throwable cause);
448
}
449

450
public class ConfigurationException extends RuntimeException {
451
    public ConfigurationException(String message);
452
    public ConfigurationException(String message, Throwable cause);
453
}
454

455
public class PreventFurtherStepsException extends RuntimeException {
456
    public PreventFurtherStepsException(String message);
457
}
458
```