0
# SpotBugs Annotations
1

2
SpotBugs Annotations provides a comprehensive set of annotations for the SpotBugs static analysis tool, enabling developers to suppress false positive warnings, mark code expectations, and control static analysis behavior. The annotations include warning suppression, null safety annotations, resource management, and testing annotations for fine-grained static analysis control.
3

4
## Package Information
5

6
- **Package Name**: com.github.spotbugs:spotbugs-annotations
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven or Gradle project
10
  ```xml
11
  <dependency>
12
    <groupId>com.github.spotbugs</groupId>
13
    <artifactId>spotbugs-annotations</artifactId>
14
    <version>4.9.3</version>
15
  </dependency>
16
  ```
17
  ```gradle
18
  implementation 'com.github.spotbugs:spotbugs-annotations:4.9.3'
19
  ```
20

21
## Core Imports
22

23
```java
24
import edu.umd.cs.findbugs.annotations.*;
25
```
26

27
Individual annotation imports:
28
```java
29
import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
30
import edu.umd.cs.findbugs.annotations.NonNull;
31
import edu.umd.cs.findbugs.annotations.Nullable;
32
import edu.umd.cs.findbugs.annotations.CheckReturnValue;
33
```
34

35
## Basic Usage
36

37
```java
38
import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
39
import edu.umd.cs.findbugs.annotations.NonNull;
40
import edu.umd.cs.findbugs.annotations.Nullable;
41
import edu.umd.cs.findbugs.annotations.CheckReturnValue;
42

43
public class ExampleService {
44
    
45
    // Suppress specific SpotBugs warnings with justification
46
    @SuppressFBWarnings(value = "EI_EXPOSE_REP", 
47
                        justification = "Deliberate exposure for performance")
48
    public Date[] getDates() {
49
        return dates;
50
    }
51
    
52
    // Null safety annotations
53
    public void processUser(@NonNull String name, @Nullable String email) {
54
        System.out.println(name); // Safe to use without null check
55
        if (email != null) {     // Must check nullable parameters
56
            System.out.println(email);
57
        }
58
    }
59
    
60
    // Enforce return value checking
61
    @CheckReturnValue(explanation = "Connection status must be verified")
62
    public boolean connect() {
63
        return connectionEstablished;
64
    }
65
}
66
```
67

68
## Architecture
69

70
SpotBugs Annotations is organized around several core functionality areas:
71

72
- **Warning Suppression**: Control SpotBugs warning generation with precise matching
73
- **Null Safety**: Comprehensive null safety type system for safer code
74
- **Default Annotations**: Apply annotations by default to scopes (classes, packages)
75
- **Resource Management**: Track resource creation, cleanup, and lifecycle obligations
76
- **Testing Annotations**: Control expected warnings for testing static analysis rules
77

78
## Capabilities
79

80
### Warning Suppression
81

82
Control SpotBugs warning generation with flexible matching strategies including exact matching, prefix matching, and regular expressions.
83

84
```java { .api }
85
@interface SuppressFBWarnings {
86
    String[] value() default {};
87
    String justification() default "";
88
    SuppressMatchType matchType() default SuppressMatchType.DEFAULT;
89
}
90

91
enum SuppressMatchType {
92
    DEFAULT, EXACT, REGEX
93
}
94
```
95

96
[Warning Suppression](./warning-suppression.md)
97

98
### Null Safety Annotations
99

100
Complete null safety annotation system for expressing nullability constraints and enabling safer code through static analysis.
101

102
```java { .api }
103
@interface NonNull {}
104
@interface Nullable {}
105
@interface CheckForNull {}
106
@interface UnknownNullness {}
107
@Deprecated @interface PossiblyNull {}
108
```
109

110
[Null Safety](./null-safety.md)
111

112
### Return Value Checking
113

114
Enforce that method return values are checked by callers to prevent ignored error conditions and resource leaks.
115

116
```java { .api }
117
@interface CheckReturnValue {
118
    @Deprecated Priority priority() default Priority.MEDIUM;
119
    Confidence confidence() default Confidence.MEDIUM;
120
    String explanation() default "";
121
}
122
```
123

124
[Return Value Checking](./return-value-checking.md)
125

126
### Default Annotations
127

128
Apply annotations by default to all members of a class or package, reducing annotation verbosity while maintaining safety.
129

130
```java { .api }
131
@interface DefaultAnnotation {
132
    Class<? extends Annotation>[] value();
133
    @Deprecated Priority priority() default Priority.MEDIUM;
134
    Confidence confidence() default Confidence.MEDIUM;
135
}
136

137
@interface DefaultAnnotationForFields {
138
    Class<? extends Annotation>[] value();
139
    @Deprecated Priority priority() default Priority.MEDIUM;
140
    Confidence confidence() default Confidence.MEDIUM;
141
}
142

143
@interface DefaultAnnotationForMethods {
144
    Class<? extends Annotation>[] value();
145
    @Deprecated Priority priority() default Priority.MEDIUM;
146
    Confidence confidence() default Confidence.MEDIUM;
147
}
148

149
@interface DefaultAnnotationForParameters {
150
    Class<? extends Annotation>[] value();
151
    @Deprecated Priority priority() default Priority.MEDIUM;
152
    Confidence confidence() default Confidence.MEDIUM;
153
}
154

155
@interface ReturnValuesAreNonnullByDefault {}
156
```
157

158
[Default Annotations](./default-annotations.md)
159

160
### Resource Management
161

162
Track resource creation, cleanup obligations, and lifecycle management for preventing resource leaks.
163

164
```java { .api }
165
@interface CleanupObligation {}
166
@interface CreatesObligation {}
167
@interface DischargesObligation {}
168
@interface OverrideMustInvoke {
169
    When value() default When.ANYTIME;
170
}
171
```
172

173
[Resource Management](./resource-management.md)
174

175
### Testing and Analysis Control
176

177
Control expected warnings and analysis behavior for testing static analysis rules and validation.
178

179
```java { .api }
180
@interface ExpectWarning {
181
    String[] value() default {};
182
    int num() default 1;
183
}
184

185
@interface NoWarning {
186
    String[] value() default {};
187
}
188

189
@interface DesireWarning {
190
    String[] value() default {};
191
    int num() default 1;
192
}
193

194
@interface DesireNoWarning {
195
    String[] value() default {};
196
}
197
```
198

199
[Testing Annotations](./testing-annotations.md)
200

201
## Supporting Types
202

203
```java { .api }
204
enum Confidence {
205
    HIGH(1), MEDIUM(2), LOW(3), IGNORE(5);
206
    
207
    static Confidence getConfidence(int prio);
208
    int getConfidenceValue();
209
}
210

211
@Deprecated
212
enum Priority {
213
    HIGH(1), MEDIUM(2), LOW(3), IGNORE(5);
214
    
215
    int getPriorityValue();
216
}
217

218
@Deprecated
219
enum When {
220
    FIRST, ANYTIME, LAST
221
}
222
```
223

224
## Dependencies
225

226
This library depends on JSR-305 annotations (`javax.annotation.*`) for null safety type qualifiers, specifically for meta-annotations like `@TypeQualifierNickname` and `@When`.