I'm late to reviewing this, but it was brought to my attention due to micrometer-metrics/tracing#1032. Iterator as a return type here is not typical in Java APIs. Iterable would be idiomatic if going for the lowest level of abstraction. An Iterator is a stateful iteration of an Iterable. In theory, the Iterator returned may not be at the first element of the Iterable. I'm not sure what the maintainers want to do given this has been released, but in my opinion, the API should not be left using Iterator.

I see there was previous discussion on this in #6852 (comment), with the motivation being to avoid copying from the Enumeration that Servlet spec returns for headers. I think that could be achieved even with the API using Iterable with one more layer compared to what's there in the Java instrumentation now with EnumerationUtil, like in this Stackoverflow answer. That would make the API nicer for implementations that don't need to deal with the Jakarta Servlet API returning an Enumeration. I'd also point out the keys method in this same interface returns Iterable<String> for the header names, and the Jakarta Servlet implementation in the instrumentation repo is copying to a list.

I understand the feedback here - but yeah unfortunately it's too late given this is now stable, it will be very difficult to change.

Thanks for the response.

Please open a new issue to discuss. Hard to stay on top of comments of closed PRs

You could add something like

  default Iterator<String> getAll(@Nullable C carrier, String key) {
    return getAllValues(carrier, key).iterator();
  }

  default Iterable<String> getAllValues(@Nullable C carrier, String key) {
    String first = get(carrier, key);
    if (first == null) {
      return Collections.emptyList();
    }
    return Collections.singleton(first);
  }

and deprecate the old method if you so wish.