diff --git a/src/main/java/com/google/api/core/ApiFutures.java b/src/main/java/com/google/api/core/ApiFutures.java index b3f3a97d0..c9caee980 100644 --- a/src/main/java/com/google/api/core/ApiFutures.java +++ b/src/main/java/com/google/api/core/ApiFutures.java @@ -105,9 +105,9 @@ public static ApiFuture> allAsList( return new ListenableFutureToApiFuture<>( Futures.allAsList( Iterables.transform( - (Iterable>) futures, - new Function, ListenableFuture>() { - public ListenableFuture apply(ApiFuture apiFuture) { + futures, + new Function, ListenableFuture>() { + public ListenableFuture apply(ApiFuture apiFuture) { return listenableFutureForApiFuture(apiFuture); } }))); diff --git a/src/main/java/com/google/api/core/BetaApi.java b/src/main/java/com/google/api/core/BetaApi.java index 8cd4c601b..f35cab81b 100644 --- a/src/main/java/com/google/api/core/BetaApi.java +++ b/src/main/java/com/google/api/core/BetaApi.java @@ -47,7 +47,9 @@ * use it. *
  • This annotation should only be added to new APIs. Adding it to an existing API is considered * API-breaking.
  • - *
  • Removing this annotation from an API gives it stable status.
  • + *
  • 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}).
  • * */ @BetaApi diff --git a/src/main/java/com/google/api/core/InternalApi.java b/src/main/java/com/google/api/core/InternalApi.java index ba24c7245..f0777f97a 100644 --- a/src/main/java/com/google/api/core/InternalApi.java +++ b/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. * + *

    * 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. + * + *

    + * Adding this annotation to an API is considered API-breaking. */ @BetaApi @Retention(RetentionPolicy.RUNTIME) diff --git a/src/main/java/com/google/api/core/InternalExtensionOnly.java b/src/main/java/com/google/api/core/InternalExtensionOnly.java new file mode 100644 index 000000000..ad78d3bfd --- /dev/null +++ b/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. + * + *

    + * For example: + *

      + *
    • An interface marked with this annotation can have new methods added to it.
    • + *
    • A non-final class with this annotation can be marked final.
    • + *
    • A class with this annotation can have new abstract methods added.
    • + *
    • a non-final method with this annotation can be marked final.
    • + *
    + * + *

    + * The list above is just for illustration purposes and is not exhaustive. + * + *

    + * 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 ""; +}