or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

default-annotations.mdindex.mdnull-safety.mdresource-management.mdreturn-value-checking.mdtesting-annotations.mdwarning-suppression.md
tile.json

tessl/maven-com-github-spotbugs--spotbugs-annotations

Annotations the SpotBugs tool supports for static analysis control and null safety

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.github.spotbugs/spotbugs-annotations@4.9.x

To install, run

npx @tessl/cli install tessl/maven-com-github-spotbugs--spotbugs-annotations@4.9.0

index.mddocs/

SpotBugs Annotations

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.

Package Information

  • Package Name: com.github.spotbugs:spotbugs-annotations
  • Package Type: Maven
  • Language: Java
  • Installation: Add to your Maven or Gradle project 
    <dependency>
  <groupId>com.github.spotbugs</groupId>
  <artifactId>spotbugs-annotations</artifactId>
  <version>4.9.3</version>
</dependency>
    implementation 'com.github.spotbugs:spotbugs-annotations:4.9.3'

Core Imports

import edu.umd.cs.findbugs.annotations.*;

Individual annotation imports:

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import edu.umd.cs.findbugs.annotations.CheckReturnValue;

Basic Usage

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import edu.umd.cs.findbugs.annotations.CheckReturnValue;

public class ExampleService {
    
    // Suppress specific SpotBugs warnings with justification
    @SuppressFBWarnings(value = "EI_EXPOSE_REP", 
                        justification = "Deliberate exposure for performance")
    public Date[] getDates() {
        return dates;
    }
    
    // Null safety annotations
    public void processUser(@NonNull String name, @Nullable String email) {
        System.out.println(name); // Safe to use without null check
        if (email != null) {     // Must check nullable parameters
            System.out.println(email);
        }
    }
    
    // Enforce return value checking
    @CheckReturnValue(explanation = "Connection status must be verified")
    public boolean connect() {
        return connectionEstablished;
    }
}

Architecture

SpotBugs Annotations is organized around several core functionality areas:

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

Capabilities

Warning Suppression

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

@interface SuppressFBWarnings {
    String[] value() default {};
    String justification() default "";
    SuppressMatchType matchType() default SuppressMatchType.DEFAULT;
}

enum SuppressMatchType {
    DEFAULT, EXACT, REGEX
}

Warning Suppression

Null Safety Annotations

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

@interface NonNull {}
@interface Nullable {}
@interface CheckForNull {}
@interface UnknownNullness {}
@Deprecated @interface PossiblyNull {}

Null Safety

Return Value Checking

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

@interface CheckReturnValue {
    @Deprecated Priority priority() default Priority.MEDIUM;
    Confidence confidence() default Confidence.MEDIUM;
    String explanation() default "";
}

Return Value Checking

Default Annotations

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

@interface DefaultAnnotation {
    Class<? extends Annotation>[] value();
    @Deprecated Priority priority() default Priority.MEDIUM;
    Confidence confidence() default Confidence.MEDIUM;
}

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

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

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

@interface ReturnValuesAreNonnullByDefault {}

Default Annotations

Resource Management

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

@interface CleanupObligation {}
@interface CreatesObligation {}
@interface DischargesObligation {}
@interface OverrideMustInvoke {
    When value() default When.ANYTIME;
}

Resource Management

Testing and Analysis Control

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

@interface ExpectWarning {
    String[] value() default {};
    int num() default 1;
}

@interface NoWarning {
    String[] value() default {};
}

@interface DesireWarning {
    String[] value() default {};
    int num() default 1;
}

@interface DesireNoWarning {
    String[] value() default {};
}

Testing Annotations

Supporting Types

enum Confidence {
    HIGH(1), MEDIUM(2), LOW(3), IGNORE(5);
    
    static Confidence getConfidence(int prio);
    int getConfidenceValue();
}

@Deprecated
enum Priority {
    HIGH(1), MEDIUM(2), LOW(3), IGNORE(5);
    
    int getPriorityValue();
}

@Deprecated
enum When {
    FIRST, ANYTIME, LAST
}

Dependencies

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