android.annotation.UnsupportedAppUsage Maven / Gradle / Ivy
Show all versions of androidstub Show documentation
/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.annotation;
import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.CLASS;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
/**
* Indicates that this non-SDK interface is used by apps. A non-SDK interface is a
* class member (field or method) that is not part of the public SDK. Since the
* member is not part of the SDK, usage by apps is not supported.
*
* If you are an Android App developer
*
* This annotation indicates that you may be able to access the member, but that
* this access is discouraged and not supported by Android. If there is a value
* for {@link #maxTargetSdk()} on the annotation, access will be restricted based
* on the {@code targetSdkVersion} value set in your manifest.
*
* Fields and methods annotated with this are likely to be restricted, changed
* or removed in future Android releases. If you rely on these members for
* functionality that is not otherwise supported by Android, consider filing a
* feature request.
*
*
If you are an Android OS developer
*
* This annotation acts as a heads up that changing a given method or field
* may affect apps, potentially breaking them when the next Android version is
* released. In some cases, for members that are heavily used, this annotation
* may imply restrictions on changes to the member.
*
* This annotation also results in access to the member being permitted by the
* runtime, with a warning being generated in debug builds. Which apps can access
* the member is determined by the value of {@link #maxTargetSdk()}.
*
*
For more details, see go/UnsupportedAppUsage.
*
* {@hide}
*/
@Retention(CLASS)
@Target({CONSTRUCTOR, METHOD, FIELD, TYPE})
@Repeatable(UnsupportedAppUsage.Container.class)
public @interface UnsupportedAppUsage {
/**
* Associates a bug tracking the work to add a public alternative to this API. Optional.
*
* @return ID of the associated tracking bug
*/
long trackingBug() default 0;
/**
* Indicates that usage of this API is limited to apps based on their target SDK version.
*
*
Access to the API is allowed if the targetSdkVersion in the apps manifest is no greater
* than this value. Access checks are performed at runtime.
*
*
This is used to give app developers a grace period to migrate off a non-SDK interface.
* When making Android version N, existing APIs can have a maxTargetSdk of N-1 added to them.
* Developers must then migrate off the API when their app is updated in future, but it will
* continue working in the meantime.
*
*
Possible values are:
*
* -
* {@link android.os.Build.VERSION_CODES#O} or {@link android.os.Build.VERSION_CODES#P},
* to limit access to apps targeting these SDKs (or earlier).
*
* -
* absent (default value) - All apps can access this API, but doing so may result in
* warnings in the log, UI warnings (on developer builds) and/or strictmode violations.
* The API is likely to be further restricted in future.
*
*
*
*
* Note, if this is set to {@link android.os.Build.VERSION_CODES#O}, apps targeting O
* maintenance releases will also be allowed to use the API, and similarly for any future
* maintenance releases of P.
*
* @return The maximum value for an apps targetSdkVersion in order to access this API.
*/
int maxTargetSdk() default Integer.MAX_VALUE;
/**
* For debug use only. The expected dex signature to be generated for this API, used to verify
* parts of the build process.
*
* @return A dex API signature.
*/
String expectedSignature() default "";
/**
* The signature of an implicit (not present in the source) member that forms part of the
* hiddenapi.
*
* Allows access to non-SDK API elements that are not represented in the input source to be
* managed.
*
*
This must only be used when applying the annotation to a type, using it in any other
* situation is an error.
*
* @return A dex API signature.
*/
String implicitMember() default "";
/**
* Public API alternatives to this API.
*
*
If non-empty, the string must be a description of the public API alternative(s) to this
* API. The explanation must contain at least one Javadoc link tag to public API methods or
* fields. e.g.:
* {@literal @UnsupportedAppUsage(publicAlternatives="Use {@link foo.bar.Baz#bat()} instead.")}
*
*
Any elements that can be deduced can be omitted, e.g.:
*
* -
* the class, if it's the same as for the annotated element.
*
* -
* the package name, if it's the same as for the annotated element.
*
* -
* the method parameters, if there is only one method with that name in the given
* package and class.
*
*
* @return A Javadoc-formatted string.
*/
@SuppressWarnings("JavadocReference")
String publicAlternatives() default "";
/**
* Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types.
*/
@Retention(CLASS)
@Target(TYPE)
@interface Container {
UnsupportedAppUsage[] value();
}
}