Is there a way to declare a class/method as experimental in Java?

Question

During development I sometimes write classes or methods that still have experimental status. I'd like to declare these classes so that I can see them directly in the code. The whole thing should work like @Deprecated. Only with the opposite meaning.

As far as I know, there is no such declaration in Java. Or is it? If not: How could I realize this functionality?

Answer 1

For Java 1.6+ (not sure about 1.5) you can use your own custom annotation, here is a functional template you can use :

package com.mycompany.annotations;

import java.lang.annotation.*;

/**
 *
 * This element has an experimental maturity.  Use with caution.
 *
 *
 * NOTE: The developers of this element is not responsible for the issues created,
 * using it is not suggested for production environment. If you see this annotation do this, do not do that etc
 * Enjoy responsibly....
 */


@Documented //this annotation maybe helpful for your custom annotation
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER,
        ElementType.CONSTRUCTOR, ElementType.LOCAL_VARIABLE, ElementType.PACKAGE, 
        ElementType.ANNOTATION_TYPE, ElementType.TYPE_USE, ElementType.TYPE_PARAMETER
})
public @interface Experimental {}

Here is the source code of ElementType, so everyone may not want to use the elements ElementType.TYPE_USE, ElementType.TYPE_PARAMETER

    /*
    ....
        * @since 1.5
        * @jls 9.6.4.1 @Target
        * @jls 4.1 The Kinds of Types and Values
        */
public enum ElementType {
/** Class, interface (including annotation type), or enum declaration */
TYPE,

/** Field declaration (includes enum constants) */
FIELD,

/** Method declaration */
METHOD,

/** Formal parameter declaration */
PARAMETER,

/** Constructor declaration */
CONSTRUCTOR,

/** Local variable declaration */
LOCAL_VARIABLE,

/** Annotation type declaration */
ANNOTATION_TYPE,

/** Package declaration */
PACKAGE,

/**
 * Type parameter declaration
 *
 * @since 1.8
 */
TYPE_PARAMETER,

/**
 * Use of a type
 *
 * @since 1.8
 */
   TYPE_USE
}

By the way this is what I see from my IntelliJ when I search for libraries probably implemented Experimental

There is an Experimental annotation defined with Java 9. But be aware that it is in Oracle JDK, not the OpenJDK one. At the time of this post, you need to install jdk-11 from the official site to see/use it. I would not use it for this purpose, because of the facts Stephen C. listed.

You can not use it for methods anyway. since its source code is

... 
package jdk.jfr;

/*
 ...
 *
 * @since 9
 */
@MetadataDefinition
@Label("Experimental")
@Description("Element is not to be shown to a user by default")
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.FIELD, ElementType.TYPE })
public @interface Experimental {
}

Answer 2

You are best off either implementing your own annotation or finding a suitable 3rd-party equivalent ... with appropriate scoping.

In JDK 9+ there is an annotation called jdk.jfr.Experimental. However:

• It is not included prior to Java 9.
• It may only exist for Oracle Java implementations that support Java Flight Recorder.

• The javadoc for the annotation implies that it has a JFR specific meaning:

  Annotation that specifies that an element is experimental and may change without notice.

  Clients that visualize Flight Recorder events should not show the events or fields annotated with the Experimental annotation by default. This annotation allows event producers the freedom to try out new events without committing to them.

Therefore ... reusing @jdk.jfr.Experimental in a non-JFR context with a non-JFR meaning is inadvisable. It is unlikely that any core Java tools (apart from JFR itself) or 3rd-party tools will pay special attention to this annotation¹.

Also, the author of @jdk.jfr.Experimental has commented:

"I agree. The annotation is meant for Flight Recorder, it should not be used outside that context. (I'm the author of the class)" – Kire Haglin

---

^{1 - .... but I might be wrong.}