Annotation Type SdkAdvancedApi

@Documented @Target({TYPE,METHOD,CONSTRUCTOR,FIELD}) @Retention(CLASS) @SdkProtectedApi public @interface SdkAdvancedApi
Marks an API that is error-prone to use: implementing, overriding, or calling it incorrectly, or configuring it with an unsafe value, compiles cleanly but can fail or misbehave at runtime rather than reporting a clear error.

The annotation records the risk information on the API in a structured form: cautionWhen() classifies which kind of use is error-prone, guidance() explains the contract that must be upheld, saferAlternative() points to a lower-risk approach, and link() points to further documentation.

This is an advisory marker: it does not gate compilation and imposes no runtime behavior.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    SdkAdvancedApi.Usage
     

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    SdkAdvancedApi.Usage
    cautionWhen
    Which kind of use of this API is error-prone: IMPLEMENTED if the risk is in implementing or extending the annotated type, OVERRIDDEN if it is in overriding the annotated method, CONFIGURED if it is in setting the annotated field or option, and CALLED if it is in calling the annotated method (for example a factory that accepts an object you supply and does not shield you from that object's contract).
    String
    guidance
    Explains why this API is error-prone and what you must uphold to use it safely: the parts of the contract that are easy to get wrong and the failure that results if they are not met.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    link
    An optional link to documentation explaining the risk and correct usage in more depth.
    String
    saferAlternative
    An optional pointer to the recommended safer approach that satisfies the same need without the risk (for example, a factory method that implements the contract correctly).

  • Element Details

    • cautionWhen

      SdkAdvancedApi.Usage cautionWhen
      Which kind of use of this API is error-prone: IMPLEMENTED if the risk is in implementing or extending the annotated type, OVERRIDDEN if it is in overriding the annotated method, CONFIGURED if it is in setting the annotated field or option, and CALLED if it is in calling the annotated method (for example a factory that accepts an object you supply and does not shield you from that object's contract). Required.

    • guidance

      String guidance
      Explains why this API is error-prone and what you must uphold to use it safely: the parts of the contract that are easy to get wrong and the failure that results if they are not met.

    • saferAlternative

      String saferAlternative
      An optional pointer to the recommended safer approach that satisfies the same need without the risk (for example, a factory method that implements the contract correctly). Empty when there is no direct alternative.
      Default:
      ""

    • link

      String link
      An optional link to documentation explaining the risk and correct usage in more depth. Empty when there is no dedicated page.
      Default:
      ""