Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Experimental

@Target([AnnotationTarget.ANNOTATION_CLASS]) class Experimental
androidx.annotation.experimental.Experimental

Denotes that the annotated element is a marker of an experimental API. Any declaration annotated with this marker is considered part of an unstable API surface and its call sites should accept the experimental aspect of it either by using UseExperimental, or by being annotated with that marker themselves, effectively causing further propagation of that experimental aspect. Example:

<code>
  // Library code
  @Retention(CLASS)
  @Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE})
  @Experimental(level = Level.ERROR)
  public @interface ExperimentalDateTime {}
 
  @ExperimentalDateTime
  public class DateProvider {
      // ...
  }
  </code>
<code>
  // Client code
  int getYear() {
      DateProvider provider; // Error: DateProvider is experimental
      // ...
  }
 
  @ExperimentalDateTime
  Date getDate() {
      DateProvider provider; // OK: the function is marked as experimental
      // ...
  }
 
  void displayDate() {
      System.out.println(getDate()); // Error: getDate() is experimental, acceptance is required
  }
  </code>

Summary

Nested classes

Severity of the diagnostic that should be reported on usages of experimental API which did not explicitly accept the experimental aspect of that API either by using UseExperimental or by being annotated with the corresponding marker annotation.

Public constructors

Denotes that the annotated element is a marker of an experimental API.

Properties

Experimental.Level

Defines the reporting level for incorrect usages of this experimental API.

Public constructors

<init>

Experimental(level: Experimental.Level)

Denotes that the annotated element is a marker of an experimental API. Any declaration annotated with this marker is considered part of an unstable API surface and its call sites should accept the experimental aspect of it either by using UseExperimental, or by being annotated with that marker themselves, effectively causing further propagation of that experimental aspect. Example:

<code>
  // Library code
  @Retention(CLASS)
  @Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE})
  @Experimental(level = Level.ERROR)
  public @interface ExperimentalDateTime {}
 
  @ExperimentalDateTime
  public class DateProvider {
      // ...
  }
  </code>
<code>
  // Client code
  int getYear() {
      DateProvider provider; // Error: DateProvider is experimental
      // ...
  }
 
  @ExperimentalDateTime
  Date getDate() {
      DateProvider provider; // OK: the function is marked as experimental
      // ...
  }
 
  void displayDate() {
      System.out.println(getDate()); // Error: getDate() is experimental, acceptance is required
  }
  </code>

Properties

level

val level: Experimental.Level

Defines the reporting level for incorrect usages of this experimental API.