JarCasting
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-pomdependency - utils: added
appendintoArrayUtils - annotations: added
UiThreadandCriticalannotations - annotations: updated shaded findbugs annotations up to 3.0.2 version
- plugin: added
check-jargoal
1.1.2 (03-apr-2016)
- annotations : added annotations to describe time and memory complexity :
@TimeComplexityand@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
@Nullableor@NonNullableon non-object return type - plugin : added check for max allowed levels for
@Weight,@TimeComplexityand@MemoryComplexityand 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
@MayContainNulland@MustNotContainNullfor fields - little improvement in JCL check in @Constraint
- added
GetUtils#ensureNonNullAndNonEmptyandGetUtils#ensureNonNullStrfor 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
@Nullableand@NotNullannotations 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>