Add default implementations for deprecated methods (#2235)

Motivation:

Without providing a `default` implementation for methods that are
deprecated, users can not avoid using those in the codebase.

Modifications:

- Enhance gRPC code generator to add `default` impl for deprecated
client methods;
- Add all missed `default` implementations for deprecated methods of
`HttpMetaData` and its subclasses;

Result:

Users can avoid depending on deprecated methods in their codebase and
prepare for the next version.

servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/Generator.java

@@ -889,7 +889,7 @@ private TypeSpec.Builder addClientInterfaces(final State state, final TypeSpec.B
                     .addMethod(newRpcMethodSpec(clientMetaData.methodProto, EnumSet.of(INTERFACE, CLIENT),
                             printJavaDocs, (methodName, b) -> {
                                 ClassName inClass = messageTypesMap.get(clientMetaData.methodProto.getInputType());
-                                b.addModifiers(ABSTRACT).addParameter(clientMetaData.className, metadata)
+                                b.addModifiers(DEFAULT).addParameter(clientMetaData.className, metadata)
                                 .addAnnotation(Deprecated.class);
                                 if (printJavaDocs) {
                                     extractJavaDocComments(state, methodIndex, b);
@@ -899,7 +899,9 @@ private TypeSpec.Builder addClientInterfaces(final State state, final TypeSpec.B
                                     .addJavadoc(JAVADOC_PARAM + metadata +
                                             " the metadata associated with this client call." + lineSeparator());
                                 }
-                                return b;
+                                return b.addStatement("throw new UnsupportedOperationException(\"This method is not " +
+                                        "implemented by \" + getClass() + \". Consider migrating to an alternative " +
+                                        "method or implement this method if it's required temporarily.\")");
                             }))
                     .addMethod(newRpcMethodSpec(clientMetaData.methodProto, EnumSet.of(INTERFACE, CLIENT),
                             printJavaDocs, (methodName, b) -> {
@@ -925,7 +927,7 @@ private TypeSpec.Builder addClientInterfaces(final State state, final TypeSpec.B
                     .addMethod(newRpcMethodSpec(clientMetaData.methodProto, EnumSet.of(BLOCKING, INTERFACE, CLIENT),
                             printJavaDocs, (methodName, b) -> {
                                 ClassName inClass = messageTypesMap.get(clientMetaData.methodProto.getInputType());
-                                b.addModifiers(ABSTRACT).addParameter(clientMetaData.className, metadata)
+                                b.addModifiers(DEFAULT).addParameter(clientMetaData.className, metadata)
                                 .addAnnotation(Deprecated.class);
                                 if (printJavaDocs) {
                                     extractJavaDocComments(state, methodIndex, b);
@@ -935,7 +937,9 @@ private TypeSpec.Builder addClientInterfaces(final State state, final TypeSpec.B
                                     .addJavadoc(JAVADOC_PARAM + metadata +
                                             " the metadata associated with this client call." + lineSeparator());
                                 }
-                                return b;
+                                return b.addStatement("throw new UnsupportedOperationException(\"This method is not " +
+                                        "implemented by \" + getClass() + \". Consider migrating to an alternative " +
+                                        "method or implement this method if it's required temporarily.\")");
                             }))
                     .addMethod(newRpcMethodSpec(clientMetaData.methodProto, EnumSet.of(BLOCKING, INTERFACE, CLIENT),
                             printJavaDocs, (methodName, b) -> {

servicetalk-http-api/gradle/spotbugs/main-exclusions.xml

@@ -52,6 +52,13 @@
     <Bug pattern="NP_PARAMETER_MUST_BE_NONNULL_BUT_MARKED_AS_NULLABLE"/>
   </Match>
 
+  <!-- False positive -->
+  <Match>
+    <Class name="io.servicetalk.http.api.ContentCodingHttpServiceFilter"/>
+    <Method name="codingForResponse"/>
+    <Bug pattern="RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE"/>
+  </Match>
+
   <!-- Intentional reference comparison to avoid re-parsing if no value -->
   <Match>
     <Class name="io.servicetalk.http.api.Uri3986"/>

servicetalk-http-api/src/main/java/io/servicetalk/http/api/BlockingStreamingHttpRequest.java

@@ -133,7 +133,12 @@ default <T> BlockingIterable<T> payloadBody(HttpDeserializer<T> deserializer) {
      * @deprecated Use {@link #payloadBody(Iterable, HttpStreamingSerializer)}.
      */
     @Deprecated
-    <T> BlockingStreamingHttpRequest payloadBody(Iterable<T> payloadBody, HttpSerializer<T> serializer);
+    default <T> BlockingStreamingHttpRequest payloadBody(Iterable<T> payloadBody, HttpSerializer<T> serializer) {
+        throw new UnsupportedOperationException("BlockingStreamingHttpRequest#payloadBody(Iterable, HttpSerializer) " +
+                "is not supported by " + getClass() + ". This method is deprecated, consider migrating to " +
+                "BlockingStreamingHttpRequest#payloadBody(Iterable, HttpStreamingSerializer) or implement this " +
+                "method if it's required temporarily.");
+    }
 
     /**
      * Returns a {@link BlockingStreamingHttpRequest} with its underlying payload set to the result of serialization.
@@ -174,8 +179,13 @@ <T> BlockingStreamingHttpRequest messageBody(HttpMessageBodyIterable<T> messageB
      * {@link #payloadBody(Iterable, HttpStreamingSerializer)}.
      */
     @Deprecated
-    <T> BlockingStreamingHttpRequest transformPayloadBody(
-            Function<BlockingIterable<Buffer>, BlockingIterable<T>> transformer, HttpSerializer<T> serializer);
+    default <T> BlockingStreamingHttpRequest transformPayloadBody(
+            Function<BlockingIterable<Buffer>, BlockingIterable<T>> transformer, HttpSerializer<T> serializer) {
+        throw new UnsupportedOperationException(
+                "BlockingStreamingHttpRequest#transformPayloadBody(Function, HttpSerializer) is not supported by " +
+                        getClass() + ". This method is deprecated, consider migrating to alternative methods or " +
+                        "implement this method if it's required temporarily.");
+    }
 
     /**
      * Returns a {@link BlockingStreamingHttpRequest} with its underlying payload transformed to the result of
@@ -208,7 +218,12 @@ default <T, R> BlockingStreamingHttpRequest transformPayloadBody(
      * @deprecated Use {@link #payloadBody()} and {@link #payloadBody(Iterable)}.
      */
     @Deprecated
-    BlockingStreamingHttpRequest transformPayloadBody(UnaryOperator<BlockingIterable<Buffer>> transformer);
+    default BlockingStreamingHttpRequest transformPayloadBody(UnaryOperator<BlockingIterable<Buffer>> transformer) {
+        throw new UnsupportedOperationException(
+                "BlockingStreamingHttpRequest#transformPayloadBody(UnaryOperator) is not supported by " + getClass() +
+                        ". This method is deprecated, consider migrating to alternative methods or implement this " +
+                        "method if it's required temporarily.");
+    }
 
     /**
      * Returns a {@link BlockingStreamingHttpRequest} with its underlying payload transformed to {@link Buffer}s,
@@ -219,7 +234,12 @@ default <T, R> BlockingStreamingHttpRequest transformPayloadBody(
      * @deprecated Use {@link #messageBody()} and {@link #messageBody(HttpMessageBodyIterable)}.
      */
     @Deprecated
-    <T> BlockingStreamingHttpRequest transform(TrailersTransformer<T, Buffer> trailersTransformer);
+    default <T> BlockingStreamingHttpRequest transform(TrailersTransformer<T, Buffer> trailersTransformer) {
+        throw new UnsupportedOperationException(
+                "BlockingStreamingHttpRequest#transform(TrailersTransformer) is not supported by " + getClass() +
+                        ". This method is deprecated, consider migrating to alternative methods or implement this " +
+                        "method if it's required temporarily.");
+    }
 
     /**
      * Translates this {@link BlockingStreamingHttpRequest} to a {@link HttpRequest}.
@@ -272,7 +292,11 @@ default <T, R> BlockingStreamingHttpRequest transformPayloadBody(
 
     @Deprecated
     @Override
-    BlockingStreamingHttpRequest encoding(ContentCodec encoding);
+    default BlockingStreamingHttpRequest encoding(ContentCodec encoding) {
+        throw new UnsupportedOperationException("BlockingStreamingHttpRequest#encoding(ContentCodec) is not " +
+                "supported by " + getClass() + ". This method is deprecated, consider migrating to provided " +
+                "alternatives or implement this method if it's required temporarily.");
+    }
 
     @Override
     BlockingStreamingHttpRequest contentEncoding(@Nullable BufferEncoder encoder);

servicetalk-http-api/src/main/java/io/servicetalk/http/api/BlockingStreamingHttpResponse.java

@@ -21,6 +21,7 @@
 import io.servicetalk.concurrent.api.Single;
 import io.servicetalk.concurrent.api.internal.CloseableIteratorBufferAsInputStream;
 import io.servicetalk.context.api.ContextMap;
+import io.servicetalk.encoding.api.ContentCodec;
 
 import java.io.InputStream;
 import java.util.function.Function;
@@ -129,7 +130,12 @@ default <T> BlockingIterable<T> payloadBody(HttpDeserializer<T> deserializer) {
      * @deprecated Use {@link #payloadBody(Iterable, HttpStreamingSerializer)}.
      */
     @Deprecated
-    <T> BlockingStreamingHttpResponse payloadBody(Iterable<T> payloadBody, HttpSerializer<T> serializer);
+    default <T> BlockingStreamingHttpResponse payloadBody(Iterable<T> payloadBody, HttpSerializer<T> serializer) {
+        throw new UnsupportedOperationException("BlockingStreamingHttpResponse#payloadBody(Iterable, HttpSerializer) " +
+                "is not supported by " + getClass() + ". This method is deprecated, consider migrating to " +
+                "BlockingStreamingHttpResponse#payloadBody(Iterable, HttpStreamingSerializer) or implement this " +
+                "method if it's required temporarily.");
+    }
 
     /**
      * Returns a {@link BlockingStreamingHttpResponse} with its underlying payload set to the result of serialization.
@@ -170,8 +176,13 @@ <T> BlockingStreamingHttpResponse messageBody(HttpMessageBodyIterable<T> message
      * {@link #payloadBody(Iterable, HttpStreamingSerializer)}.
      */
     @Deprecated
-    <T> BlockingStreamingHttpResponse transformPayloadBody(
-            Function<BlockingIterable<Buffer>, BlockingIterable<T>> transformer, HttpSerializer<T> serializer);
+    default <T> BlockingStreamingHttpResponse transformPayloadBody(
+            Function<BlockingIterable<Buffer>, BlockingIterable<T>> transformer, HttpSerializer<T> serializer) {
+        throw new UnsupportedOperationException(
+                "BlockingStreamingHttpResponse#transformPayloadBody(Function, HttpSerializer) is not supported by " +
+                        getClass() + ". This method is deprecated, consider migrating to alternative methods or " +
+                        "implement this method if it's required temporarily.");
+    }
 
     /**
      * Returns a {@link BlockingStreamingHttpResponse} with its underlying payload transformed to the result of
@@ -204,7 +215,12 @@ default <T, R> BlockingStreamingHttpResponse transformPayloadBody(
      * @deprecated Use {@link #payloadBody()} and {@link #payloadBody(Iterable)}.
      */
     @Deprecated
-    BlockingStreamingHttpResponse transformPayloadBody(UnaryOperator<BlockingIterable<Buffer>> transformer);
+    default BlockingStreamingHttpResponse transformPayloadBody(UnaryOperator<BlockingIterable<Buffer>> transformer) {
+        throw new UnsupportedOperationException(
+                "BlockingStreamingHttpResponse#transformPayloadBody(UnaryOperator) is not supported by " + getClass() +
+                        ". This method is deprecated, consider migrating to alternative methods or implement this " +
+                        "method if it's required temporarily.");
+    }
 
     /**
      * Returns a {@link BlockingStreamingHttpResponse} with its underlying payload transformed to {@link Buffer}s,
@@ -215,7 +231,12 @@ default <T, R> BlockingStreamingHttpResponse transformPayloadBody(
      * @deprecated Use {@link #messageBody()} and {@link #messageBody(HttpMessageBodyIterable)}.
      */
     @Deprecated
-    <T> BlockingStreamingHttpResponse transform(TrailersTransformer<T, Buffer> trailersTransformer);
+    default <T> BlockingStreamingHttpResponse transform(TrailersTransformer<T, Buffer> trailersTransformer) {
+        throw new UnsupportedOperationException(
+                "BlockingStreamingHttpResponse#transform(TrailersTransformer) is not supported by " + getClass() +
+                        ". This method is deprecated, consider migrating to alternative methods or implement this " +
+                        "method if it's required temporarily.");
+    }
 
     /**
      * Translates this {@link BlockingStreamingHttpResponse} to a {@link HttpResponse}.
@@ -236,6 +257,14 @@ default <T, R> BlockingStreamingHttpResponse transformPayloadBody(
     @Override
     BlockingStreamingHttpResponse status(HttpResponseStatus status);
 
+    @Deprecated
+    @Override
+    default BlockingStreamingHttpResponse encoding(ContentCodec encoding) {
+        throw new UnsupportedOperationException("BlockingStreamingHttpResponse#encoding(ContentCodec) is not " +
+                "supported by " + getClass() + ". This method is deprecated, consider migrating to provided " +
+                "alternatives or implement this method if it's required temporarily.");
+    }
+
     @Override
     default BlockingStreamingHttpResponse addHeader(final CharSequence name, final CharSequence value) {
         HttpResponseMetaData.super.addHeader(name, value);

servicetalk-http-api/src/main/java/io/servicetalk/http/api/BlockingStreamingHttpServerResponse.java

@@ -17,6 +17,7 @@
 
 import io.servicetalk.buffer.api.Buffer;
 import io.servicetalk.context.api.ContextMap;
+import io.servicetalk.encoding.api.ContentCodec;
 
 import java.io.OutputStream;
 
@@ -49,7 +50,12 @@ public interface BlockingStreamingHttpServerResponse extends HttpResponseMetaDat
      * @deprecated Use {@link #sendMetaData(HttpStreamingSerializer)}.
      */
     @Deprecated
-    <T> HttpPayloadWriter<T> sendMetaData(HttpSerializer<T> serializer);
+    default <T> HttpPayloadWriter<T> sendMetaData(HttpSerializer<T> serializer) {
+        throw new UnsupportedOperationException("BlockingStreamingHttpServerResponse#sendMetaData(HttpSerializer) " +
+                "is not supported by " + getClass() + ". This method is deprecated, consider migrating to " +
+                "BlockingStreamingHttpServerResponse#sendMetaData(HttpStreamingSerializer) or implement this " +
+                "method if it's required temporarily.");
+    }
 
     /**
      * Sends the {@link HttpResponseMetaData} to the client and returns an {@link HttpPayloadWriter} of type {@link T}
@@ -81,6 +87,13 @@ public interface BlockingStreamingHttpServerResponse extends HttpResponseMetaDat
     @Override
     BlockingStreamingHttpServerResponse status(HttpResponseStatus status);
 
+    @Override
+    default BlockingStreamingHttpServerResponse encoding(ContentCodec encoding) {
+        throw new UnsupportedOperationException("BlockingStreamingHttpServerResponse#encoding(ContentCodec) is not " +
+                "supported by " + getClass() + ". This method is deprecated, consider migrating to provided " +
+                "alternatives or implement this method if it's required temporarily.");
+    }
+
     @Override
     default BlockingStreamingHttpServerResponse addHeader(final CharSequence name, final CharSequence value) {
         HttpResponseMetaData.super.addHeader(name, value);

servicetalk-http-api/src/main/java/io/servicetalk/http/api/DefaultBlockingStreamingHttpRequest.java

@@ -233,6 +233,7 @@ public <T> BlockingStreamingHttpRequest transformPayloadBody(
         return this;
     }
 
+    @Deprecated
     @Override
     public BlockingStreamingHttpRequest transformPayloadBody(
             final UnaryOperator<BlockingIterable<Buffer>> transformer) {

servicetalk-http-api/src/main/java/io/servicetalk/http/api/DefaultBlockingStreamingHttpResponse.java

@@ -120,6 +120,7 @@ public <T> BlockingStreamingHttpResponse transformPayloadBody(final Function<Blo
         return this;
     }
 
+    @Deprecated
     @Override
     public BlockingStreamingHttpResponse transformPayloadBody(
             final UnaryOperator<BlockingIterable<Buffer>> transformer) {

servicetalk-http-api/src/main/java/io/servicetalk/http/api/DefaultBlockingStreamingHttpServerResponse.java

@@ -18,6 +18,7 @@
 import io.servicetalk.buffer.api.Buffer;
 import io.servicetalk.buffer.api.BufferAllocator;
 import io.servicetalk.context.api.ContextMap;
+import io.servicetalk.encoding.api.ContentCodec;
 
 import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
 import java.util.function.Consumer;
@@ -60,6 +61,14 @@ public BlockingStreamingHttpServerResponse status(final HttpResponseStatus statu
         return this;
     }
 
+    @Deprecated
+    @Override
+    public BlockingStreamingHttpServerResponse encoding(final ContentCodec encoding) {
+        checkSent();
+        super.encoding(encoding);
+        return this;
+    }
+
     @Override
     public BlockingStreamingHttpServerResponse addHeader(final CharSequence name, final CharSequence value) {
         checkSent();

servicetalk-http-api/src/main/java/io/servicetalk/http/api/DefaultHttpRequestMetaData.java

@@ -77,7 +77,7 @@ public HttpRequestMetaData version(final HttpProtocolVersion version) {
 
     @Deprecated
     @Override
-    public HttpMetaData encoding(final ContentCodec encoding) {
+    public HttpRequestMetaData encoding(final ContentCodec encoding) {
         super.encoding(encoding);
         return this;
     }

servicetalk-http-api/src/main/java/io/servicetalk/http/api/DefaultHttpResponseMetaData.java

@@ -16,6 +16,7 @@
 package io.servicetalk.http.api;
 
 import io.servicetalk.context.api.ContextMap;
+import io.servicetalk.encoding.api.ContentCodec;
 
 import javax.annotation.Nullable;
 
@@ -48,6 +49,13 @@ public HttpResponseMetaData status(final HttpResponseStatus status) {
         return this;
     }
 
+    @Deprecated
+    @Override
+    public HttpResponseMetaData encoding(final ContentCodec encoding) {
+        super.encoding(encoding);
+        return this;
+    }
+
     @Override
     public HttpResponseMetaData context(final ContextMap context) {
         super.context(context);

servicetalk-http-api/src/main/java/io/servicetalk/http/api/HttpMetaData.java

@@ -64,20 +64,32 @@ public interface HttpMetaData extends ContextMapHolder {
      * @param encoding The {@link ContentCodec} used for the encoding of the payload.
      * @return {@code this}.
      * @see <a href="https://tools.ietf.org/html/rfc7231#section-3.1.2.2">Content-Encoding</a>
-     * @deprecated Use {@link HttpRequestMetaData#contentEncoding(BufferEncoder)}.
+     * @deprecated Use {@link HttpRequestMetaData#contentEncoding(BufferEncoder)} for requests and
+     * {@link ContentEncodingHttpServiceFilter} for responses. An example can be found
+     * <a href="https://apple.github.io/servicetalk//servicetalk-examples/0.42/http/index.html#Compression">here</a>.
      */
     @Deprecated
-    HttpMetaData encoding(ContentCodec encoding);
+    default HttpMetaData encoding(ContentCodec encoding) {
+        throw new UnsupportedOperationException("HttpMetaData#encoding(ContentCodec) is not supported by " +
+                getClass() + ". This method is deprecated, consider migrating to provided alternatives or implement " +
+                "this method if it's required temporarily.");
+    }
 
     /**
      * Returns the {@link ContentCodec} used to encode the payload of a request or a response.
      * @return The {@link ContentCodec} used for the encoding of the payload.
      * @see <a href="https://tools.ietf.org/html/rfc7231#section-3.1.2.2">Content-Encoding</a>
-     * @deprecated Use {@link HttpRequestMetaData#contentEncoding()}.
+     * @deprecated Use {@link HttpRequestMetaData#contentEncoding()} for requests and
+     * {@link ContentEncodingHttpServiceFilter} for responses. An example can be found
+     * <a href="https://apple.github.io/servicetalk//servicetalk-examples/0.42/http/index.html#Compression">here</a>.
      */
     @Deprecated
     @Nullable
-    ContentCodec encoding();
+    default ContentCodec encoding() {
+        throw new UnsupportedOperationException("HttpMetaData#encoding() is not supported by " + getClass() +
+                ". This method is deprecated, consider migrating to provided alternatives or implement " +
+                "this method if it's required temporarily.");
+    }
 
     /**
      * Adds a new header with the specified {@code name} and {@code value}.