diff --git a/core/annotations/src/main/java/software/amazon/awssdk/annotations/ReviewBeforeRelease.java b/core/annotations/src/main/java/software/amazon/awssdk/annotations/ReviewBeforeRelease.java deleted file mode 100644 index 8c14f26a8fea..000000000000 --- a/core/annotations/src/main/java/software/amazon/awssdk/annotations/ReviewBeforeRelease.java +++ /dev/null @@ -1,34 +0,0 @@ -/* - * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"). - * You may not use this file except in compliance with the License. - * A copy of the License is located at - * - * http://aws.amazon.com/apache2.0 - * - * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.annotations; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Target; - -/** - * An annotation applied during SDK 2.0 developer preview. This makes note of something we know will change before GA or are - * unsure about. By applying this annotation and making sure all instances of it are removed before GA, we will make sure not to - * miss anything we intended to review. - */ -@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD}) -@SdkProtectedApi -public @interface ReviewBeforeRelease { - /** - * An explanation of why we should review this before general availability. Will it definitely change? Are we just testing - * something? - */ - String value(); -} diff --git a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkInternalApi.java b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkInternalApi.java index fe14c2146895..475af6d0f6e7 100644 --- a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkInternalApi.java +++ b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkInternalApi.java @@ -15,15 +15,23 @@ package software.amazon.awssdk.annotations; +import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Target; /** - * Marker interface for 'internal' APIs that should not be used outside the same module. Breaking - * changes can and will be introduced to elements marked as {@link SdkInternalApi}. Users of the SDK - * and the generated clients themselves should not depend on any packages, types, fields, - * constructors, or methods with this annotation. + * Marks APIs that should not be used by SDK users and are internal to the AWS SDK for Java v2, subject to change without notice. + * + *

WARNING: Elements annotated with {@code @SdkInternalApi} are not part of the public API. + * They may be modified or removed in any release without warning, including minor and patch releases. + * + *

Intended for: Internal SDK implementation only. This annotation indicates that the + * marked element should not be used outside its defining module. + * + * @see SdkProtectedApi + * @see SdkPublicApi */ +@Documented @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD}) @SdkProtectedApi public @interface SdkInternalApi { diff --git a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPreviewApi.java b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPreviewApi.java index 7fb713f735f8..e07edb2fc5ed 100644 --- a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPreviewApi.java +++ b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPreviewApi.java @@ -19,10 +19,26 @@ import java.lang.annotation.Target; /** - * Marker interface for preview and experimental APIs. Breaking changes may be - * introduced to elements marked as {@link SdkPreviewApi}. Users of the SDK - * should assume that anything annotated as preview will change or break, and - * should not use them in production. + * Marks APIs as preview or experimental features that may change or be removed. + * + *

WARNING: Elements annotated with {@code @SdkPreviewApi} are not stable and may + * introduce breaking changes in any release, including minor and patch versions. Do not use + * preview APIs in production environments. + * + *

Use with caution: + *

+ * + *

Intended for: Early adopters and developers who want to experiment with new features + * and provide feedback before they become stable public APIs. + * + * @see SdkPublicApi + * @see SdkProtectedApi + * @see SdkInternalApi */ @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD}) @SdkProtectedApi diff --git a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkProtectedApi.java b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkProtectedApi.java index edf0580666fe..3c9f7458fdb0 100644 --- a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkProtectedApi.java +++ b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkProtectedApi.java @@ -15,17 +15,26 @@ package software.amazon.awssdk.annotations; +import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Target; /** - * Marker for elements that should only be accessed by the generated clients and not users of the - * SDK. Do not make breaking changes to these APIs - they won't directly break customers, but - * they'll break old versions of generated clients. - *

- * TODO: Write a linter that makes sure generated code only depends on public or - * {@code @InternalApi} classes. + * Marks APIs that should not be used by SDK users and are intended for SDK internal classes shared across different modules. + * + *

IMPORTANT: Elements annotated with {@code @SdkProtectedApi} must maintain backward + * compatibility. Breaking changes will break older versions of generated clients, even if they don't directly impact SDK users. + * + *

Intended for: Generated service clients and internal SDK modules that support them. + * These APIs form the contract between the SDK core and generated code. + * + *

Stability guarantee: Protected APIs should not introduce breaking changes, as this + * would require regenerating and redeploying all service clients. + * + * @see SdkInternalApi + * @see SdkPublicApi */ +@Documented @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD}) @SdkProtectedApi public @interface SdkProtectedApi { diff --git a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPublicApi.java b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPublicApi.java index 9a8104527f7a..f478555c3614 100644 --- a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPublicApi.java +++ b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPublicApi.java @@ -15,12 +15,30 @@ package software.amazon.awssdk.annotations; +import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Target; /** - * Marker interface for 'public' APIs. + * Marks APIs as public and stable for use by SDK users building applications. + * + *

Stability guarantee: Elements annotated with {@code @SdkPublicApi} are backward + * compatible. + * + *

Safe to use for: + *

+ * + *

Intended for: SDK users and external developers. These APIs form the official public + * interface of the AWS SDK for Java v2. + * + * @see SdkProtectedApi + * @see SdkInternalApi */ +@Documented @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD}) @SdkProtectedApi public @interface SdkPublicApi { diff --git a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkTestInternalApi.java b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkTestInternalApi.java index 7cc8d4dea5b7..af88226bbe97 100644 --- a/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkTestInternalApi.java +++ b/core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkTestInternalApi.java @@ -15,6 +15,7 @@ package software.amazon.awssdk.annotations; +import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Target; @@ -27,6 +28,7 @@ * TODO: Write a linter that makes sure only test code depends on methods or constructors annotated * with this method */ +@Documented @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE}) @SdkProtectedApi public @interface SdkTestInternalApi { diff --git a/pom.xml b/pom.xml index d8f7d4d1c888..1bfe5c4de031 100644 --- a/pom.xml +++ b/pom.xml @@ -687,10 +687,10 @@ *.internal.* + + software.amazon.awssdk.annotations.ReviewBeforeRelease software.amazon.awssdk.thirdparty.* software.amazon.awssdk.regions.* - - software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor true