From 0eb98621ed4b7a4d287ad971525c4d0ed306ca12 Mon Sep 17 00:00:00 2001 From: Kun Zhang Date: Tue, 11 Aug 2015 11:06:50 -0700 Subject: [PATCH] Annotations for unstable and internal interfaces. - Add `@Internal` and `@ExperimentalApi`, both are annotated `@Internal` - Annotate `@Internal` to `package io.grpc.internal` - AbstractChannelBuilder.ChannelEssentials is annotated `@Internal` - ChannelImpl.ping() is annotated `@ExperimentalApi` - Context is annotated `@ExperimentalApi` - Add `package-info.java` to `io.grpc.inprocess` and `io.grpc.internal`. --- .../java/io/grpc/AbstractChannelBuilder.java | 3 + core/src/main/java/io/grpc/ChannelImpl.java | 2 + core/src/main/java/io/grpc/Context.java | 2 + .../java/io/grpc/inprocess/package-info.java | 35 +++++++++++ .../io/grpc/internal/ExperimentalApi.java | 62 +++++++++++++++++++ .../main/java/io/grpc/internal/Internal.java | 54 ++++++++++++++++ .../java/io/grpc/internal/package-info.java | 38 ++++++++++++ core/src/main/java/io/grpc/package-info.java | 35 +++++++++++ 8 files changed, 231 insertions(+) create mode 100644 core/src/main/java/io/grpc/inprocess/package-info.java create mode 100644 core/src/main/java/io/grpc/internal/ExperimentalApi.java create mode 100644 core/src/main/java/io/grpc/internal/Internal.java create mode 100644 core/src/main/java/io/grpc/internal/package-info.java create mode 100644 core/src/main/java/io/grpc/package-info.java diff --git a/core/src/main/java/io/grpc/AbstractChannelBuilder.java b/core/src/main/java/io/grpc/AbstractChannelBuilder.java index c9662027e07..ad9e5079a04 100644 --- a/core/src/main/java/io/grpc/AbstractChannelBuilder.java +++ b/core/src/main/java/io/grpc/AbstractChannelBuilder.java @@ -35,6 +35,7 @@ import com.google.common.util.concurrent.ThreadFactoryBuilder; import io.grpc.internal.ClientTransportFactory; +import io.grpc.internal.Internal; import io.grpc.internal.SharedResourceHolder; import io.grpc.internal.SharedResourceHolder.Resource; @@ -164,6 +165,7 @@ public void run() { /** * The essentials required for creating a channel. */ + @Internal protected static class ChannelEssentials { final ClientTransportFactory transportFactory; @Nullable final Runnable terminationRunnable; @@ -186,5 +188,6 @@ public ChannelEssentials(ClientTransportFactory transportFactory, * information for the channel. This method is mean for Transport implementors and should not be * used by normal users. */ + @Internal protected abstract ChannelEssentials buildEssentials(); } diff --git a/core/src/main/java/io/grpc/ChannelImpl.java b/core/src/main/java/io/grpc/ChannelImpl.java index 11ae2494557..4691fc829f1 100644 --- a/core/src/main/java/io/grpc/ChannelImpl.java +++ b/core/src/main/java/io/grpc/ChannelImpl.java @@ -41,6 +41,7 @@ import io.grpc.internal.ClientTransport; import io.grpc.internal.ClientTransport.PingCallback; import io.grpc.internal.ClientTransportFactory; +import io.grpc.internal.ExperimentalApi; import io.grpc.internal.HttpUtil; import io.grpc.internal.SerializingExecutor; import io.grpc.internal.SharedResourceHolder; @@ -220,6 +221,7 @@ public boolean isTerminated() { * * @see ClientTransport#ping(PingCallback, Executor) */ + @ExperimentalApi public void ping(final PingCallback callback, final Executor executor) { try { obtainActiveTransport().ping(callback, executor); diff --git a/core/src/main/java/io/grpc/Context.java b/core/src/main/java/io/grpc/Context.java index 873adff6e8d..d7fe619572b 100644 --- a/core/src/main/java/io/grpc/Context.java +++ b/core/src/main/java/io/grpc/Context.java @@ -35,6 +35,7 @@ import com.google.common.util.concurrent.MoreExecutors; import com.google.common.util.concurrent.ThreadFactoryBuilder; +import io.grpc.internal.ExperimentalApi; import io.grpc.internal.SharedResourceHolder; import java.io.Closeable; @@ -110,6 +111,7 @@ * responsibility of the application to ensure that all contexts are properly cancelled. * */ +@ExperimentalApi public class Context { private static final Logger LOG = Logger.getLogger(Context.class.getName()); diff --git a/core/src/main/java/io/grpc/inprocess/package-info.java b/core/src/main/java/io/grpc/inprocess/package-info.java new file mode 100644 index 00000000000..7deb8e5b36b --- /dev/null +++ b/core/src/main/java/io/grpc/inprocess/package-info.java @@ -0,0 +1,35 @@ +/* + * Copyright 2015, 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. + */ + +/** + * The in-process transport which is for when a server is in the same process as the client. + */ +package io.grpc.inprocess; diff --git a/core/src/main/java/io/grpc/internal/ExperimentalApi.java b/core/src/main/java/io/grpc/internal/ExperimentalApi.java new file mode 100644 index 00000000000..22578388ac7 --- /dev/null +++ b/core/src/main/java/io/grpc/internal/ExperimentalApi.java @@ -0,0 +1,62 @@ +/* + * Copyright 2015, 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 io.grpc.internal; + +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 can change at any time, and has no guarantee of API stability and + * backward-compatibility. + * + *

Usage guidelines: + *

    + *
  1. This annotation is used only on public API. Internal interfaces should not use it.
    2. + *
  2. After gRPC has gained API stability, this annotation can only be added to new API. Adding it + * to an existing API is considered API-breaking.
    3. + *
  3. Removing this annotation from an API gives it stable status.
    4. + *
+ */ +@Retention(RetentionPolicy.SOURCE) +@Target({ + ElementType.ANNOTATION_TYPE, + ElementType.CONSTRUCTOR, + ElementType.FIELD, + ElementType.METHOD, + ElementType.PACKAGE, + ElementType.TYPE}) +@Documented +public @interface ExperimentalApi { +} diff --git a/core/src/main/java/io/grpc/internal/Internal.java b/core/src/main/java/io/grpc/internal/Internal.java new file mode 100644 index 00000000000..8081c26aef5 --- /dev/null +++ b/core/src/main/java/io/grpc/internal/Internal.java @@ -0,0 +1,54 @@ +/* + * Copyright 2015, 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 io.grpc.internal; + +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; + +/** + * Annotates a program element which is internal to gRPC, not part of the public API, and should not + * be used outside of gRPC codebase. + */ +@Retention(RetentionPolicy.SOURCE) +@Target({ + ElementType.ANNOTATION_TYPE, + ElementType.CONSTRUCTOR, + ElementType.FIELD, + ElementType.METHOD, + ElementType.PACKAGE, + ElementType.TYPE}) +@Documented +public @interface Internal { +} diff --git a/core/src/main/java/io/grpc/internal/package-info.java b/core/src/main/java/io/grpc/internal/package-info.java new file mode 100644 index 00000000000..1d2f8a1a2fb --- /dev/null +++ b/core/src/main/java/io/grpc/internal/package-info.java @@ -0,0 +1,38 @@ +/* + * Copyright 2015, 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. + */ + +/** + * Interfaces and implementations that are used inside gRPC. + * + *

All interfaces under this package are not public API, and should not be used outside of gRPC. + */ +@Internal +package io.grpc.internal; diff --git a/core/src/main/java/io/grpc/package-info.java b/core/src/main/java/io/grpc/package-info.java new file mode 100644 index 00000000000..cd37e20e7f7 --- /dev/null +++ b/core/src/main/java/io/grpc/package-info.java @@ -0,0 +1,35 @@ +/* + * Copyright 2015, 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. + */ + +/** + * The gRPC core public API. + */ +package io.grpc;