Introduction

It is a small general-purpose library includes:

• set of run-time annotations to mark code
• set of utility classes
• shaded com.google.code.findbugs:jsr305 annotation library
• maven plugin to log info about some annotations and check java class version

Change log

1.1.3 (06-jan-2019)

• updated the uber-pom dependency
• utils: added append into ArrayUtils
• annotations: added UiThread and Critical annotations
• annotations: updated shaded findbugs annotations up to 3.0.2 version
• plugin: added check-jar goal

1.1.2 (03-apr-2016)

• annotations : added annotations to describe time and memory complexity : @TimeComplexity and @MemoryComplexity
• plugin : fixed false positive for constructors of nested classes
• plugin : fixed successful completion with non-zero error counter
• plugin : fixed nested class name extraction for log
• plugin : added check for placing of @Nullable or @NonNullable on non-object return type
• plugin : added check for max allowed levels for @Weight, @TimeComplexity and @MemoryComplexity and it throws error if rule is violated
• utils : added StrUtils

1.1.1 (31-mar-2016)

• added Assertions#assertEquals
• fixed issue #1
• fixed checking of @MayContainNull and @MustNotContainNull for fields
• little improvement in JCL check in @Constraint
• added GetUtils#ensureNonNullAndNonEmpty and GetUtils#ensureNonNullStr for String

1.1.0 (19-mar-2016)

• utilities and auxiliary classes extracted as separated module meta-utils
• meta-common module renamed to meta-annotations
• annotation classes compiled in JVM 1.5 format
• improved maven plugin to check marks for method arguments, NB! It also supports @Nullable and @NotNull annotations from IDEA annotation pack.
• changed retention policy for annotations to CLASS, but shaded annotations from JR-305 have retention policy RUNTIME
• extended scope for many annotations
• improved utility methods and assertions
• added annotations @Experimental, @ThrowsRuntimeException, @ThrowsRuntimeExceptions
• bugfixing and refactoring, also fixed NPE in the maven plugin for missing class format option

1.0.2 (06-mar-2016)

• added Assertions.assertIsValid method
• improved logging in meta-checker plugin
• added empty arrays for primitives into Arrays class
• fixed KeepCreationPointTemplate, also added thread id info
• added ImplementationNote annotation
• improved the meta-check plugin, added support to check java class version

1.0.1 (12-feb-2016)

• Bug fixing

1.0 (10-feb-2016)

• Initial version

Annotations

It contains number annotations to mark code, plus JSR-305 annotations provided by the shaded findbugs annotation library.

• ImplementationNote
• UiThread
• Critical
• Constraint
• Determined
• NonDetermined
• LazyInited
• Link
• MayContainNull
• MustNotContainNull
• NeedsRefactoring
• OneWayChange
• ReturnsOriginal
• Risky
• ToDo
• Warning
• Weight
• ThrowsRuntimeException
• ThrowsRuntimeExceptions
• Experimental
• TimeComplexity
• MemoryComplexity

How to add the annotation library into maven project

To use annotations just add dependency to the library

<dependency>
    <groupId>com.igormaznitsa</groupId>
    <artifactId>meta-annotations</artifactId>
    <version>1.1.3</version>
</dependency>

It shades JSR-305 annotations from the FindBugs library so that they also will be available for usage automatically.

Utilities

Since 1.1.0 utility classes extracted into separated module which is available in maven central Just add the lines below into build section.

<dependency>
    <groupId>com.igormaznitsa</groupId>
    <artifactId>meta-utils</artifactId>
    <version>1.1.3</version>
</dependency>

com.igormaznitsa.meta.common.utils.Deferrers

It allows to defer some operations, like it works in Go but unfortunately the call to process all deferred operations must be placed into try...finally block to ensure the call. It checks stack frames and all deferred operations will be processed by Deferrers.processDeferredActions() only for actual stack depth, it means that deferred operations added on higher stack levels will be ignored.

    try {
      // it processes runnable, the code will be executed
      Deferrers.defer(new Runnable() {public void run() { System.out.println("Hello world");}});
      final InputStream is = new FileInputStream("/home/test/nonexistfile.txt");
      // it processes closeable, registered closeable object will be closed automatically
      Deferrers.defer(is);
    }
    finally {
      Deferrers.processDeferredActions();
    }

com.igormaznitsa.meta.common.utils.TimeGuard

    final TimeGuard.TimeAlertListener listener = new TimeGuard.TimeAlertListener() {
      @Override
      public void onTimeAlert(long l, TimeGuard.TimeData td) {
        System.out.println("Too long delay for " + td.getAlertMessage());
      }
    };

    try {
      TimeGuard.addGuard("Checkpoint1", 100L, listener);
      Thread.sleep(200L);
    }
    finally {
      TimeGuard.check();
    }

How to use the maven plugin

I have also published some maven plugin which allows to check compiled classes for the annotations and print some information and check that methods marked by nullable and nonnull annotations. Also the plugin allows to fail build process if detected some annotations, it allows to avoid publishing of project with to-do or experimental stuff.

<plugin>
    <groupId>com.igormaznitsa</groupId>
    <artifactId>meta-checker</artifactId>
    <version>1.1.3</version>
    <configuration>
        <restrictClassFormat>7</restrictClassFormat>
        <failForAnnotations>
            <param>risky</param>
        </failForAnnotations>
    </configuration>
    <executions>
        <execution>
            <goals>
              <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>