0
# Checker Qual
1

2
Checker Qual provides type qualifier annotations for the Checker Framework static analysis tool. It contains 358 annotations organized across 32 packages that enable developers to specify type qualifiers in their Java code for pluggable type-checking, catching potential bugs at compile time through enhanced static analysis.
3

4
This Knowledge Tile documents the major annotation categories including nullness checking, bounds validation, concurrency analysis, string format validation, framework meta-annotations, units checking, resource management, method contracts, optional value checking, signedness tracking, and constant value analysis.
5

6
## Package Information
7

8
- **Package Name**: org.checkerframework:checker-qual
9
- **Package Type**: Maven
10
- **Language**: Java
11
- **Installation**: 
12
  - Maven: `<dependency><groupId>org.checkerframework</groupId><artifactId>checker-qual</artifactId><version>3.49.5</version></dependency>`
13
  - Gradle: `implementation 'org.checkerframework:checker-qual:3.49.5'`
14

15
## Core Imports
16

17
```java
18
import org.checkerframework.checker.nullness.qual.NonNull;
19
import org.checkerframework.checker.nullness.qual.Nullable;
20
import org.checkerframework.framework.qual.DefaultFor;
21
```
22

23
For module-based projects:
24
```java
25
module mymodule {
26
    requires org.checkerframework.checker.qual;
27
}
28
```
29

30
## Basic Usage
31

32
```java
33
import org.checkerframework.checker.nullness.qual.NonNull;
34
import org.checkerframework.checker.nullness.qual.Nullable;
35
import org.checkerframework.checker.index.qual.NonNegative;
36

37
public class Example {
38
    // Method ensures non-null return value
39
    public @NonNull String getName(@Nullable String input) {
40
        return input != null ? input : "default";
41
    }
42
    
43
    // Array access with bounds checking
44
    public void processArray(int @NonNull [] array, @NonNegative int index) {
45
        if (index < array.length) {
46
            System.out.println(array[index]);
47
        }
48
    }
49
}
50
```
51

52
## Architecture
53

54
Checker Qual is organized into several key areas:
55

56
- **Framework Annotations**: Core meta-annotations for defining type qualifier hierarchies and behavior
57
- **Checker-Specific Annotations**: Domain-specific annotations for nullness, bounds checking, locking, etc.
58
- **Common Utilities**: Shared annotations used across multiple checkers
59
- **Dataflow Annotations**: Annotations for method purity and side effects
60

61
The annotations work with the Checker Framework's pluggable type system to provide compile-time verification of program properties without runtime overhead.
62

63
## Capabilities
64

65
### Nullness Checking
66

67
Annotations for preventing null pointer exceptions through static analysis.
68

69
```java { .api }
70
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
71
public @interface NonNull {}
72

73
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
74
public @interface Nullable {}
75

76
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
77
public @interface MonotonicNonNull {}
78
```
79

80
[Nullness Annotations](./nullness.md)
81

82
### Index and Bounds Checking
83

84
Annotations for ensuring array bounds safety and preventing index out of bounds exceptions.
85

86
```java { .api }
87
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
88
public @interface NonNegative {}
89

90
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
91
public @interface IndexFor {
92
    String[] value();
93
}
94

95
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
96
public @interface LTLengthOf {
97
    String[] value();
98
}
99
```
100

101
[Index and Bounds Annotations](./index-bounds.md)
102

103
### Concurrency and Locking
104

105
Annotations for thread safety and lock-based synchronization analysis.
106

107
```java { .api }
108
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
109
public @interface GuardedBy {
110
    String[] value();
111
}
112

113
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
114
public @interface LockHeld {}
115

116
@Target(ElementType.METHOD)
117
public @interface Holding {
118
    String[] value();
119
}
120
```
121

122
[Concurrency Annotations](./concurrency.md)
123

124
### String and Format Validation
125

126
Annotations for validating string formats, regular expressions, and format strings.
127

128
```java { .api }
129
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
130
public @interface Regex {}
131

132
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
133
public @interface Format {
134
    ConversionCategory[] value();
135
}
136

137
public enum ConversionCategory {
138
    UNUSED, GENERAL, CHAR, INT, FLOAT, TIME, CHAR_AND_INT, INT_AND_TIME
139
}
140
```
141

142
[String and Format Annotations](./string-format.md)
143

144
### Framework Meta-Annotations
145

146
Core annotations for defining type qualifier hierarchies and their behavior.
147

148
```java { .api }
149
@Target(ElementType.ANNOTATION_TYPE)
150
public @interface SubtypeOf {
151
    Class<? extends Annotation>[] value();
152
}
153

154
@Target(ElementType.ANNOTATION_TYPE)
155
public @interface DefaultFor {
156
    TypeUseLocation[] value() default {};
157
    TypeKind[] typeKinds() default {};
158
    Class<?>[] types() default {};
159
}
160

161
public enum TypeUseLocation {
162
    FIELD, LOCAL_VARIABLE, PARAMETER, RETURN, UPPER_BOUND, LOWER_BOUND, OTHERWISE, ALL
163
}
164
```
165

166
[Framework Annotations](./framework.md)
167

168
### Units and Physical Quantities
169

170
Annotations for dimensional analysis and physical unit checking.
171

172
```java { .api }
173
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
174
public @interface Length {}
175

176
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
177
public @interface Mass {}
178

179
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
180
public @interface m {}
181

182
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
183
public @interface kg {}
184
```
185

186
[Units Annotations](./units.md)
187

188
### Resource Management
189

190
Annotations for tracking resource lifecycle and ensuring proper cleanup.
191

192
```java { .api }
193
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
194
public @interface MustCall {
195
    String[] value();
196
}
197

198
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
199
public @interface CalledMethods {
200
    String[] value();
201
}
202

203
@Target(ElementType.PARAMETER)
204
public @interface Owning {}
205
```
206

207
[Resource Management Annotations](./resources.md)
208

209
### Method Contracts and Side Effects
210

211
Annotations for specifying method contracts, purity, and side effects.
212

213
```java { .api }
214
@Target(ElementType.METHOD)
215
public @interface Pure {}
216

217
@Target(ElementType.METHOD)
218
public @interface SideEffectFree {}
219

220
@Target(ElementType.METHOD)
221
public @interface EnsuresNonNull {
222
    String[] value();
223
}
224

225
@Target(ElementType.METHOD)
226
public @interface RequiresNonNull {
227
    String[] value();
228
}
229
```
230

231
[Method Contracts](./contracts.md)
232

233
### Optional Value Checking
234

235
Annotations for validating Optional container states and preventing empty Optional access.
236

237
```java { .api }
238
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
239
public @interface Present {}
240

241
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
242
public @interface MaybePresent {}
243

244
@Target(ElementType.METHOD)
245
public @interface EnsuresPresent {
246
    String[] value();
247
}
248

249
@Target(ElementType.METHOD)
250
public @interface RequiresPresent {
251
    String[] value();
252
}
253
```
254

255
[Optional Checker](./optional.md)
256

257
### Initialization State Tracking
258

259
Annotations for tracking object initialization state during construction.
260

261
```java { .api }
262
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
263
public @interface Initialized {}
264

265
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
266
public @interface UnderInitialization {
267
    Class<?> value() default Object.class;
268
}
269
```
270

271
### Fake Enumeration (Fenum) Checking
272

273
Annotations for creating type-safe enumerations from integer constants.
274

275
```java { .api }
276
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
277
public @interface Fenum {
278
    String value();
279
}
280

281
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
282
public @interface SwingCompassDirection {}
283

284
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
285
public @interface AwtColorSpace {}
286
```
287

288
### GUI Thread Safety
289

290
Annotations for ensuring GUI operations occur on appropriate threads.
291

292
```java { .api }
293
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
294
public @interface UI {}
295

296
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
297
public @interface AlwaysSafe {}
298

299
@Target(ElementType.METHOD)
300
public @interface UIEffect {}
301
```
302

303
### Taint Analysis
304

305
Annotations for tracking untrusted data flow and preventing injection attacks.
306

307
```java { .api }
308
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
309
public @interface Tainted {}
310

311
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
312
public @interface Untainted {}
313

314
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
315
public @interface PolyTainted {}
316
```
317

318
### Numeric Signedness
319

320
Annotations for distinguishing signed and unsigned integer interpretations.
321

322
```java { .api }
323
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
324
public @interface Signed {}
325

326
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER}) 
327
public @interface Unsigned {}
328

329
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
330
public @interface SignedPositive {}
331
```
332

333
[Signedness Checker](./signedness.md)
334

335
### Constant Value Tracking
336

337
Annotations for tracking compile-time constant values and ranges of expressions.
338

339
```java { .api }
340
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
341
public @interface IntVal {
342
    long[] value();
343
}
344

345
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
346
public @interface StringVal {
347
    String[] value();
348
}
349

350
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
351
public @interface IntRange {
352
    long from() default Long.MIN_VALUE;
353
    long to() default Long.MAX_VALUE;
354
}
355

356
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
357
public @interface ArrayLen {
358
    int[] value();
359
}
360
```
361

362
[Constant Value Checker](./constant-value.md)
363

364
## Type Definitions
365

366
```java { .api }
367
// Core enums used throughout the framework
368
public enum TypeKind {
369
    PACKAGE, INT, BOOLEAN, CHAR, DOUBLE, FLOAT, LONG, SHORT, BYTE
370
}
371

372
public enum LiteralKind {
373
    ALL, BOOLEAN, CHAR, DOUBLE, FLOAT, INT, LONG, NULL, STRING, PRIMITIVE
374
}
375

376
// Common annotation patterns
377
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
378
@Retention(RetentionPolicy.RUNTIME)
379
@Documented
380
public @interface AnnotationTemplate {}
381
```