Create a @Stub annotation that acts as a @Deprecated in Java

Question

I'd like to create a @Stub, @Example or @Mock annotations in Java to indicate that some classes are just for testing. Also I like to make those classes as deprecated to discourage users of my library from using them. I like to make something similar to @Nullable and other annotation in JSR305.

I came up with this:

import javax.annotation.meta.TypeQualifierNickname;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.*;

@Deprecated
@Retention(RetentionPolicy.RUNTIME)
@TypeQualifierNickname
@Target(value=TYPE)
public @interface Stub {
}

And the use case:

@Stub
public final class SuperAwesome implements Feature {
}

Unfortunately, dispite of using @TypeQualifierNickname, it seams like my @Stub annotation being marked as deprecated by Intellij and javac compiler instead of target annotated class.

Is there a way, this may work without a need for changes in javac or IDE?

Answer 1

You will need to write a custom annotation processor as the

@Deprecated

annotation applies to the Stub interface, and not to where it is used. I did a quick search, but most examples just print stuff on the console. This may help

https://deors.wordpress.com/2011/10/08/annotation-processors/

Answer 2

You will need to write some logic to enforce your programming rule, which is "don't call methods with the @Stub annotation". Two frameworks that you could use for doing so are the Checker Framework and error-prone.

The downside is that users of your library will need to run your tool every time they compile your code. You will need to write instructions telling them howto adjust their build process to run the tool that checks your programming rule.