Allow option for adding Iterable<String> header values

[klustria]

Description

Allow option for adding Iterable header values

Documentation

If enhancement: provide description with example code/config snippet or pointer to issue with the description

2 additional APIs were added in HeaderValues:

1. create(HeaderName name, Iterable values)
2. create(String name, Iterable values)

example:

final String[] ordinalNumbers = {"First", "Second", "Third"};
Iterable<String> ordinals = Arrays.asList(ordinalNumbers);

Header header  = HeaderValues.create("ordinals", o);

If feature: summarize feature and provide pointer to doc issue
Currently no documentation for HeaderValues usage, but if one exist, add the above example.

If no doc impact: None

[tomas-langer]

We already have methods for a Collection, why is Iterable needed? Please describe the use case.

[tjquinno]

We already have methods for a Collection, why is Iterable needed? Please describe the use case.

See the linked issue description which mentions gRPC's Metadata type as a specific example that makes header values available this way. I have edited the description to add a link to the Javadoc.

Given that dealing with headers can be in performance-critical sections of code, it could be useful to be able to avoid creating a throw-away collection from an Iterable.

[tjquinno]

Some general comments. Possible changes.

[tjquinno]

Another change, in the handling of the size this time.

[tjquinno]

Given the outcome of the discussion of what behavior we should implement, would it make sense to just have

public static Header create(HeaderName name, Iterable<String> values) {
    return create(name, StreamSupport.stream(values.spliterator(), false).toList());
}

and not even have a separate implementation for HeaderValueIterable?

This provides the convenience of the added factory method and therefore saves developera from having to create a list or array explicitly themselves, but the resulting Header still exhibits the snapshot behavior we want.

Although this would not create the list lazily upon first need, and doing that might have saved a little performance, there would be real savings only if the header values were never accessed which seems unlikely.

[klustria]

Given the outcome of the discussion of what behavior we should implement, would it make sense to just have

public static Header create(HeaderName name, Iterable<String> values) {
    return create(name, StreamSupport.stream(values.spliterator(), false).toList());
}

and not even have a separate implementation for HeaderValueIterable?

This provides the convenience of the added factory method and therefore saves developera from having to create a list or array explicitly themselves, but the resulting Header still exhibits the snapshot behavior we want.

Although this would not create the list lazily upon first need, and doing that might have saved a little performance, there would be real savings only if the header values were never accessed which seems unlikely.

Yes, the code would be something like that. I'm casting if it is a collection so conversion is not needed, but otherwise, I'll use that same statement to convert non-collection type Iterables.

[tjquinno]

Yes, the code would be something like that. I'm casting if it is a collection so conversion is not needed, but otherwise, I'll use that same statement to convert non-collection type Iterables.

Ah, yes, of course. Sounds good.

[klustria]

@tomas-langer @tjquinno , I have finalized the changes. Can you please review?