Adding new annotation, InternalExtensionOnly (#34)

garrettjonesgoogle · web-flow · commit 3bab74a560c3 · 2017-11-03T15:01:52.000-07:00
Also fixing a warning.
diff --git a/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/ApiFutures.java b/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/ApiFutures.java
@@ -105,9 +105,9 @@ public static <V> ApiFuture<List<V>> allAsList(
     return new ListenableFutureToApiFuture<>(
         Futures.allAsList(
             Iterables.transform(
-                (Iterable<ApiFuture<V>>) futures,
-                new Function<ApiFuture<V>, ListenableFuture<V>>() {
-                  public ListenableFuture<V> apply(ApiFuture<V> apiFuture) {
+                futures,
+                new Function<ApiFuture<? extends V>, ListenableFuture<? extends V>>() {
+                  public ListenableFuture<? extends V> apply(ApiFuture<? extends V> apiFuture) {
                     return listenableFutureForApiFuture(apiFuture);
                   }
                 })));
diff --git a/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/BetaApi.java b/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/BetaApi.java
@@ -47,7 +47,9 @@
  * use it.</li>
  * <li>This annotation should only be added to new APIs. Adding it to an existing API is considered
  * API-breaking.</li>
- * <li>Removing this annotation from an API gives it stable status.</li>
+ * <li>Removing this annotation from an API gives it stable status, assuming the API doesn't have
+ * other annotations denoting instability (such as {@link InternalApi} or
+ * {@link InternalExtensionOnly}).</li>
  * </ol>
  */
 @BetaApi
diff --git a/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/InternalApi.java b/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/InternalApi.java
@@ -40,8 +40,12 @@
  * Annotates a program element (class, method, package etc) which is internal to its containing
  * library, not part of the public API, and should not be used by users of the library.
  *
+ * <p>
  * This annotation only makes sense on APIs that are not private. Its existence is necessary because
  * Java does not have a visibility level for code within a compilation unit.
+ *
+ * <p>
+ * Adding this annotation to an API is considered API-breaking.
  */
 @BetaApi
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/InternalExtensionOnly.java b/sdk-platform-java/api-common-java/src/main/java/com/google/api/core/InternalExtensionOnly.java
@@ -0,0 +1,74 @@
+/*
+ * Copyright 2017, Google Inc.
+ * All rights reserved.
+ *
+ * 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 that is stable for callers to use, but has no guarantee of stability for
+ * extension. Consequently, the API should only be extended within the package containing the API.
+ *
+ * <p>
+ * For example:
+ * <ul>
+ * <li>An interface marked with this annotation can have new methods added to it.</li>
+ * <li>A non-final class with this annotation can be marked final.</li>
+ * <li>A class with this annotation can have new abstract methods added.</li>
+ * <li>a non-final method with this annotation can be marked final.</li>
+ * </ul>
+ *
+ * <p>
+ * The list above is just for illustration purposes and is not exhaustive.
+ *
+ * <p>
+ * Adding this annotation to an API is considered API-breaking.
+ */
+@BetaApi
+@Retention(RetentionPolicy.RUNTIME)
+@Target({
+  ElementType.ANNOTATION_TYPE,
+  ElementType.CONSTRUCTOR,
+  ElementType.FIELD,
+  ElementType.METHOD,
+  ElementType.PACKAGE,
+  ElementType.TYPE
+})
+@Documented
+public @interface InternalExtensionOnly {
+  /**
+   * Context information on why the interface/class is annotated with InternalExtensionOnly.
+   */
+  String value() default "";
+}
