Repository: apache/kafka
File: clients/src/main/java/org/apache/kafka/common/header/Headers.java (Java)

Code before:
     * @return this instance of the Headers, once the header is added.
     * @throws IllegalStateException is thrown if headers are in a read-only state.
     */
    Headers add(String key, byte[] value) throws IllegalStateException;

    /**
     * Removes all headers for the given key returning if the operation succeeded,
     * while preserving the insertion order of the remaining headers.
     * 
     * @param key to remove all headers for; must not be null.
     * @return this instance of the Headers, once the header is removed.
     * @throws IllegalStateException is thrown if headers are in a read-only state.
     */
    Headers remove(String key) throws IllegalStateException;

    /**
     * Returns just one (the very last) header for the given key, if present.
     * 
     * @param key to get the last header for; must not be null.
     * @return this last header matching the given key, returns null if not present.
     */
    Header lastHeader(String key);

    /**
     * Returns all headers for the given key, in the order they were added in, if present.
     * The returned iterators {@link org.apache.kafka.common.utils.AbstractIterator#remove()} always throws {@link UnsupportedOperationException}.
     *
     * @param key to return the headers for; must not be null.
     * @return all headers for the given key, in the order they were added in, if NO headers are present an empty iterable is returned.
     */
    Iterable<Header> headers(String key);

    /**
     * Returns all headers as an array, in the order they were added in.
     *
     * @return the headers as a Header[], mutating this array will not affect the Headers, if NO headers are present an empty array is returned.
     */
    Header[] toArray();

}


Review comment (refactor):
`AbstractIterator` is not a public API. Perhaps we could just state the `Iterable#remove` is unsupported?

Code after:
     * @return this instance of the Headers, once the header is added.
     * @throws IllegalStateException is thrown if headers are in a read-only state.
     */
    Headers add(String key, byte[] value) throws IllegalStateException;

    /**
     * Removes all headers for the given key returning if the operation succeeded,
     * while preserving the insertion order of the remaining headers.
     * 
     * @param key to remove all headers for; must not be null.
     * @return this instance of the Headers, once the header is removed.
     * @throws IllegalStateException is thrown if headers are in a read-only state.
     */
    Headers remove(String key) throws IllegalStateException;

    /**
     * Returns just one (the very last) header for the given key, if present.
     * 
     * @param key to get the last header for; must not be null.
     * @return this last header matching the given key, returns null if not present.
     */
    Header lastHeader(String key);

    /**
     * Returns all headers for the given key, in the order they were added in, if present.
     * The iterator does not support {@link java.util.Iterator#remove()}.
     *
     * @param key to return the headers for; must not be null.
     * @return all headers for the given key, in the order they were added in, if NO headers are present an empty iterable is returned.
     */
    Iterable<Header> headers(String key);

    /**
     * Returns all headers as an array, in the order they were added in.
     *
     * @return the headers as a Header[], mutating this array will not affect the Headers, if NO headers are present an empty array is returned.
     */
    Header[] toArray();

}