accept Iterable<? extends HttpHeader> in Java API header parameters

http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMessage.java

@@ -136,10 +136,10 @@ interface MessageTransformations<Self> {
     Self addHeader(HttpHeader header);
 
     /** Returns a copy of this message with the given headers added to the list of headers. */
-    Self addHeaders(Iterable<HttpHeader> headers);
+    Self addHeaders(Iterable<? extends HttpHeader> headers);
 
     /** Returns a copy of this message with new headers. */
-    Self withHeaders(Iterable<HttpHeader> headers);
+    Self withHeaders(Iterable<? extends HttpHeader> headers);
 
     <T> Self addAttribute(AttributeKey<T> key, T value);
 

http-core/src/main/mima-filters/2.0.x.backwards.excludes/java-iterable-http-header-wildcard.excludes

@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Java API collection parameters accept Iterable<? extends HttpHeader>; only the generic signature changes, the erased signature is unchanged.
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.model.HttpMessage#MessageTransformations.addHeaders(java.lang.Iterable)java.lang.Object")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.model.HttpMessage#MessageTransformations.withHeaders(java.lang.Iterable)java.lang.Object")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.scaladsl.model.HttpMessage.addHeaders(java.lang.Iterable)org.apache.pekko.http.scaladsl.model.HttpMessage")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.scaladsl.model.HttpMessage.withHeaders(java.lang.Iterable)org.apache.pekko.http.scaladsl.model.HttpMessage")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.scaladsl.model.HttpRequest.addHeaders(java.lang.Iterable)org.apache.pekko.http.scaladsl.model.HttpMessage")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.scaladsl.model.HttpRequest.withHeaders(java.lang.Iterable)org.apache.pekko.http.scaladsl.model.HttpMessage")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.scaladsl.model.HttpResponse.addHeaders(java.lang.Iterable)org.apache.pekko.http.scaladsl.model.HttpMessage")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.scaladsl.model.HttpResponse.withHeaders(java.lang.Iterable)org.apache.pekko.http.scaladsl.model.HttpMessage")

http-core/src/main/scala/org/apache/pekko/http/scaladsl/model/HttpMessage.scala

@@ -234,12 +234,12 @@ sealed trait HttpMessage extends jm.HttpMessage {
   }
 
   /** Java API */
-  def addHeaders(headers: JIterable[jm.HttpHeader]): Self =
+  def addHeaders(headers: JIterable[? <: jm.HttpHeader]): Self =
     withHeaders(this.headers ++ headers.asScala.asInstanceOf[Iterable[HttpHeader]])
 
   /** Java API */
-  def withHeaders(headers: JIterable[jm.HttpHeader]): Self =
-    withHeaders(headers.asScala.toVector.map(x => JavaMapping.toScala(x)))
+  def withHeaders(headers: JIterable[? <: jm.HttpHeader]): Self =
+    withHeaders(headers.asScala.toVector.map(x => JavaMapping.toScala(x: jm.HttpHeader)))
 
   /** Java API */
   def getAttribute[T](attributeKey: jm.AttributeKey[T]): Optional[T] =

http-core/src/test/java/org/apache/pekko/http/javadsl/model/HttpMessageTest.java

@@ -17,8 +17,18 @@
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicBoolean;
 import javax.net.ssl.SSLContext;
 import javax.net.ssl.SSLSession;
+import org.apache.pekko.http.javadsl.model.headers.Location;
+import org.apache.pekko.http.javadsl.model.headers.RawHeader;
 import org.junit.jupiter.api.Test;
 
 public class HttpMessageTest {
@@ -72,4 +82,100 @@ public void testSslAttribute() throws Exception {
 
     assertTrue(request.getAttribute(AttributeKeys.sslSession).get().getSession() == session);
   }
+
+  @Test
+  public void testAddAndWithHeadersAcceptIterableOfHeaderSubtype() {
+    List<RawHeader> headers = List.of(RawHeader.create("x-b", "2"), RawHeader.create("x-c", "3"));
+
+    HttpRequest added =
+        HttpRequest.create().addHeader(RawHeader.create("x-a", "1")).addHeaders(headers);
+    HttpResponse replaced =
+        HttpResponse.create().addHeader(RawHeader.create("x-a", "1")).withHeaders(headers);
+
+    assertEquals(
+        List.of(
+            RawHeader.create("x-a", "1"),
+            RawHeader.create("x-b", "2"),
+            RawHeader.create("x-c", "3")),
+        added.getHeaders());
+    assertEquals(headers, replaced.getHeaders());
+  }
+
+  @Test
+  public void testAddAndWithHeadersAcceptAnyIterable() {
+    RawHeader a = RawHeader.create("x-a", "1");
+    List<RawHeader> headers = List.of(RawHeader.create("x-b", "2"), RawHeader.create("x-c", "3"));
+
+    iterablesOf(headers)
+        .forEach(
+            (shape, iterable) -> {
+              HttpRequest addedToRequest = HttpRequest.create().addHeader(a).addHeaders(iterable);
+              HttpResponse addedToResponse =
+                  HttpResponse.create().addHeader(a).addHeaders(iterable);
+              HttpRequest replacedOnRequest =
+                  HttpRequest.create().addHeader(a).withHeaders(iterable);
+              HttpResponse replacedOnResponse =
+                  HttpResponse.create().addHeader(a).withHeaders(iterable);
+
+              List<HttpHeader> expectedAdded = List.of(a, headers.get(0), headers.get(1));
+              assertEquals(expectedAdded, addedToRequest.getHeaders(), "addHeaders(" + shape + ")");
+              assertEquals(
+                  expectedAdded, addedToResponse.getHeaders(), "addHeaders(" + shape + ")");
+              assertEquals(headers, replacedOnRequest.getHeaders(), "withHeaders(" + shape + ")");
+              assertEquals(headers, replacedOnResponse.getHeaders(), "withHeaders(" + shape + ")");
+            });
+  }
+
+  @Test
+  public void testAddAndWithHeadersTraverseTheIterableOnce() {
+    List<RawHeader> headers = List.of(RawHeader.create("x-a", "1"));
+
+    assertEquals(headers, HttpRequest.create().addHeaders(oneShot(headers)).getHeaders());
+    assertEquals(headers, HttpRequest.create().withHeaders(oneShot(headers)).getHeaders());
+  }
+
+  @Test
+  public void testWithHeadersOfEmptyIterableRemovesAllHeaders() {
+    HttpRequest request =
+        HttpRequest.create()
+            .addHeader(RawHeader.create("x-a", "1"))
+            .withHeaders(Collections.<RawHeader>emptySet());
+
+    assertEquals(List.of(), request.getHeaders());
+  }
+
+  @Test
+  public void testAddHeadersKeepsDifferentHeaderTypesInOrder() {
+    Location location = Location.create("/elsewhere");
+    RawHeader raw = RawHeader.create("x-a", "1");
+    Iterable<HttpHeader> mixed = new LinkedHashSet<>(List.of(location, raw));
+
+    HttpResponse response = HttpResponse.create().addHeaders(mixed);
+
+    assertEquals(List.of(location, raw), response.getHeaders());
+    assertEquals(location, response.getHeader(Location.class).get());
+  }
+
+  /** The same elements as different kinds of {@link Iterable}, keyed by a description. */
+  private static <T> Map<String, Iterable<T>> iterablesOf(List<T> items) {
+    Map<String, Iterable<T>> shapes = new LinkedHashMap<>();
+    shapes.put("ArrayList", new ArrayList<>(items));
+    shapes.put("LinkedHashSet", new LinkedHashSet<>(items));
+    shapes.put("ArrayDeque", new ArrayDeque<>(items));
+    shapes.put("unmodifiable Collection", Collections.unmodifiableCollection(items));
+    // not a java.util.Collection at all, only an Iterable
+    shapes.put("non-Collection Iterable", items::iterator);
+    return shapes;
+  }
+
+  /** An {@link Iterable} that fails if it is traversed more than once. */
+  private static <T> Iterable<T> oneShot(List<T> items) {
+    AtomicBoolean traversed = new AtomicBoolean();
+    return () -> {
+      if (traversed.getAndSet(true)) {
+        throw new IllegalStateException("Iterable traversed more than once");
+      }
+      return items.iterator();
+    };
+  }
 }

http-tests/src/test/java/org/apache/pekko/http/javadsl/server/directives/RouteDirectivesTest.java

@@ -13,9 +13,20 @@
 
 package org.apache.pekko.http.javadsl.server.directives;
 
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import org.apache.pekko.http.javadsl.model.*;
+import org.apache.pekko.http.javadsl.marshalling.Marshaller;
 import org.apache.pekko.http.javadsl.model.headers.Location;
+import org.apache.pekko.http.javadsl.model.headers.RawHeader;
 import org.apache.pekko.http.javadsl.server.Directives;
 import org.apache.pekko.http.javadsl.testkit.JUnitJupiterRouteTest;
 import org.apache.pekko.http.javadsl.testkit.TestRoute;
@@ -147,4 +158,90 @@ public void testRouteWhenLambdaThrows() {
 
     route.run(HttpRequest.create("/foo")).assertEntity("There was an internal server error.");
   }
+
+  @Test
+  public void testCompleteAcceptsAnyIterableOfHeaderSubtype() {
+    List<RawHeader> headers = List.of(RawHeader.create("x-a", "1"), RawHeader.create("x-b", "2"));
+
+    iterablesOf(headers)
+        .forEach(
+            (shape, iterable) ->
+                assertDoesNotThrow(
+                    () -> assertCompleteOverloadsRespondWithHeaders(iterable),
+                    "complete/entityToResponse with " + shape));
+  }
+
+  @Test
+  public void testCompleteWithDifferentHeaderTypes() {
+    Location location = Location.create("/elsewhere");
+    List<HttpHeader> headers = List.of(location, RawHeader.create("x-a", "1"));
+
+    testRoute(complete(StatusCodes.CREATED, headers, HttpEntities.create("created")))
+        .run(HttpRequest.GET("/"))
+        .assertStatusCode(StatusCodes.CREATED)
+        .assertHeaderExists(location)
+        .assertHeaderExists("x-a", "1")
+        .assertEntity("created");
+  }
+
+  private void assertCompleteOverloadsRespondWithHeaders(Iterable<? extends HttpHeader> headers) {
+    ResponseEntity responseEntity = HttpEntities.create("response");
+    RequestEntity requestEntity = HttpEntities.create("request");
+
+    TestRoute route =
+        testRoute(
+            path(
+                "status-value",
+                () ->
+                    complete(StatusCodes.ACCEPTED, headers, "value", Marshaller.stringToEntity())),
+            path("status-response", () -> complete(StatusCodes.ACCEPTED, headers, responseEntity)),
+            path("status-request", () -> complete(StatusCodes.ACCEPTED, headers, requestEntity)),
+            path("value", () -> complete(headers, "value", Marshaller.stringToEntity())),
+            path("response", () -> complete(headers, responseEntity)),
+            path("request", () -> complete(headers, requestEntity)),
+            path(
+                "marshaller",
+                () ->
+                    complete(
+                        "value",
+                        Marshaller.entityToResponse(
+                            StatusCodes.ACCEPTED, headers, Marshaller.stringToEntity()))),
+            path(
+                "ok-marshaller",
+                () ->
+                    complete(
+                        "value",
+                        Marshaller.entityToOKResponse(headers, Marshaller.stringToEntity()))));
+
+    String[][] expectations = {
+      {"status-value", "202", "value"},
+      {"status-response", "202", "response"},
+      {"status-request", "202", "request"},
+      {"value", "200", "value"},
+      {"response", "200", "response"},
+      {"request", "200", "request"},
+      {"marshaller", "202", "value"},
+      {"ok-marshaller", "200", "value"}
+    };
+    for (String[] e : expectations) {
+      route
+          .run(HttpRequest.GET("/" + e[0]))
+          .assertStatusCode(Integer.parseInt(e[1]))
+          .assertHeaderExists("x-a", "1")
+          .assertHeaderExists("x-b", "2")
+          .assertEntity(e[2]);
+    }
+  }
+
+  /** The same elements as different kinds of {@link Iterable}, keyed by a description. */
+  private static <T> Map<String, Iterable<T>> iterablesOf(List<T> items) {
+    Map<String, Iterable<T>> shapes = new LinkedHashMap<>();
+    shapes.put("ArrayList", new ArrayList<>(items));
+    shapes.put("LinkedHashSet", new LinkedHashSet<>(items));
+    shapes.put("ArrayDeque", new ArrayDeque<>(items));
+    shapes.put("unmodifiable Collection", Collections.unmodifiableCollection(items));
+    // not a java.util.Collection at all, only an Iterable
+    shapes.put("non-Collection Iterable", items::iterator);
+    return shapes;
+  }
 }

http/src/main/mima-filters/2.0.x.backwards.excludes/java-iterable-http-header-wildcard.excludes

@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Java API collection parameters accept Iterable<? extends HttpHeader>; only the generic signature changes, the erased signature is unchanged.
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.marshalling.Marshaller.entityToOKResponse(java.lang.Iterable,org.apache.pekko.http.javadsl.marshalling.Marshaller)org.apache.pekko.http.javadsl.marshalling.Marshaller")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.marshalling.Marshaller.entityToResponse(org.apache.pekko.http.javadsl.model.StatusCode,java.lang.Iterable,org.apache.pekko.http.javadsl.marshalling.Marshaller)org.apache.pekko.http.javadsl.marshalling.Marshaller")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.server.directives.RouteDirectives.complete(java.lang.Iterable,java.lang.Object,org.apache.pekko.http.javadsl.marshalling.Marshaller)org.apache.pekko.http.javadsl.server.directives.RouteAdapter")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.server.directives.RouteDirectives.complete(java.lang.Iterable,org.apache.pekko.http.javadsl.model.RequestEntity)org.apache.pekko.http.javadsl.server.directives.RouteAdapter")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.server.directives.RouteDirectives.complete(java.lang.Iterable,org.apache.pekko.http.javadsl.model.ResponseEntity)org.apache.pekko.http.javadsl.server.directives.RouteAdapter")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.server.directives.RouteDirectives.complete(org.apache.pekko.http.javadsl.model.StatusCode,java.lang.Iterable,java.lang.Object,org.apache.pekko.http.javadsl.marshalling.Marshaller)org.apache.pekko.http.javadsl.server.directives.RouteAdapter")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.server.directives.RouteDirectives.complete(org.apache.pekko.http.javadsl.model.StatusCode,java.lang.Iterable,org.apache.pekko.http.javadsl.model.RequestEntity)org.apache.pekko.http.javadsl.server.directives.RouteAdapter")
+ProblemFilters.exclude[IncompatibleSignatureProblem]("org.apache.pekko.http.javadsl.server.directives.RouteDirectives.complete(org.apache.pekko.http.javadsl.model.StatusCode,java.lang.Iterable,org.apache.pekko.http.javadsl.model.ResponseEntity)org.apache.pekko.http.javadsl.server.directives.RouteAdapter")

http/src/main/scala/org/apache/pekko/http/javadsl/marshalling/Marshaller.scala

@@ -32,6 +32,10 @@ object Marshaller {
 
   import JavaMapping.Implicits._
 
+  // java.lang.Iterable is read-only, so widening the element type is safe
+  private def headersAsScala(headers: java.lang.Iterable[? <: HttpHeader]) =
+    headers.asInstanceOf[java.lang.Iterable[HttpHeader]].asScala
+
   def fromScala[A, B](scalaMarshaller: marshalling.Marshaller[A, B]): Marshaller[A, B] =
     new Marshaller()(scalaMarshaller)
 
@@ -97,14 +101,16 @@ object Marshaller {
     fromScala(marshalling.Marshaller.fromToEntityMarshaller[A](status.asScala)(m.asScalaCastOutput))
   }
 
-  def entityToResponse[A](status: StatusCode, headers: java.lang.Iterable[HttpHeader],
+  def entityToResponse[A](status: StatusCode, headers: java.lang.Iterable[? <: HttpHeader],
       m: Marshaller[A, ? <: RequestEntity]): Marshaller[A, HttpResponse] = {
-    fromScala(marshalling.Marshaller.fromToEntityMarshaller[A](status.asScala, headers.asScala)(m.asScalaCastOutput))
+    fromScala(marshalling.Marshaller.fromToEntityMarshaller[A](status.asScala, headersAsScala(headers))(
+      m.asScalaCastOutput))
   }
 
   def entityToOKResponse[A](
-      headers: java.lang.Iterable[HttpHeader], m: Marshaller[A, ? <: RequestEntity]): Marshaller[A, HttpResponse] = {
-    fromScala(marshalling.Marshaller.fromToEntityMarshaller[A](headers = headers.asScala)(m.asScalaCastOutput))
+      headers: java.lang.Iterable[? <: HttpHeader], m: Marshaller[A, ? <: RequestEntity])
+      : Marshaller[A, HttpResponse] = {
+    fromScala(marshalling.Marshaller.fromToEntityMarshaller[A](headers = headersAsScala(headers))(m.asScalaCastOutput))
   }
 
   // these are methods not varargs to avoid call site warning about unchecked type params