feat: Introduce @ObsoleteApi (#1887)

Author: blakeli0

api-common-java/src/main/java/com/google/api/core/ObsoleteApi.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2023, Google Inc.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.google.api.core;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates a public API is obsolete, and will be deprecated in a future version.
+ *
+ * <p>Usage guidelines:
+ *
+ * <ol>
+ *   <li>This annotation must be used only on APIs with non-private visibility.
+ *   <li>This annotation should only be added if either an alternative API is provided and/or we
+ *       plan to stop supporting the API in a future version.
+ *   <li>This annotation must be used with a description.
+ *   <li>Alternative APIs must be referenced in Javadoc and/or description if possible.
+ * </ol>
+ */
+@BetaApi
+@Retention(RetentionPolicy.RUNTIME)
+@Target({
+  ElementType.ANNOTATION_TYPE,
+  ElementType.CONSTRUCTOR,
+  ElementType.FIELD,
+  ElementType.METHOD,
+  ElementType.PACKAGE,
+  ElementType.TYPE
+})
+@Documented
+public @interface ObsoleteApi {
+  /** Context information such as links to a discussion thread, tracking issue, etc. */
+  String value();
+}

gax-java/README.md

@@ -109,6 +109,8 @@ additional qualifications:
    with this annotation, but methods can be added, thus breaking any
    code implementing the interface. See the javadocs for more details on other
    consequences of this annotation.
+1. Components marked with `@ObsoleteApi` are stable for usage in the current major version, 
+   but will be marked with `@Deprecated` in a future major version.
 
 ### Submodule notes