I will settle for any API really, but just wanted to point out that as it stands right now the API targets the most "advanced" (hence obscure and rare) use cases, at the expense of the simple and common ones. i'd suggest (as the minimal set):
Header header(String key) - returns JUST ONE (the very last) value given a key Iterable<Header> headers(String key) - returns ALL under a key Iterable<Header> headers() - returns all, period. maybe allow null as key to prev method instead? void add(Header header) - appends a header (key inside). void remove(String key) - removes ALL HEADERS under a key. this way naive get/set semantics map to header(key)/add(Header) cleanly and simply while preserving the ability to handle more advanced use cases. we can always add more convenience methods (like those dealing with lists - addAll etc) but i think the 5 (potentially 4) above are sufficient for basically everything. On Tue, Feb 28, 2017 at 4:08 AM, Ismael Juma <ism...@juma.me.uk> wrote: > Hi Becket, > > Comments inline. > > On Sat, Feb 25, 2017 at 10:33 PM, Becket Qin <becket....@gmail.com> wrote: > > > > 1. Regarding the mutability. > > > > I think it would be a big convenience to have headers mutable during > > certain stage in the message life cycle for the use cases you mentioned. > I > > agree there is a material benefit especially given that we may have to > > modify the headers for each message. > > > > That said, I also think it is fair to say that in the producer, in order > to > > guarantee the correctness of the entire logic, it is necessary that at > some > > point we need to make producer record immutable. For example we probably > > don't want to see that users accidentally updated the headers when the > > producer is doing the serialization or compression. > > > > Given that, would it be possible to make Headers to be able to switch > from > > mutable to immutable? We have done this for the Batch in the producer. > For > > example, initially the headers are mutable, but after it has gone through > > all the interceptors, we can call Headers.close() to make it immutable > > afterwards. > > > > The difference is that the batch is an internal class that is not exposed > to users. Can you please explain what happens if a user tries to send the > same ProducerRecord twice? Would an interceptor fail when trying to mutate > the header that is now closed? Or did you have something else in mind? > > Thanks, > Ismael >
