Methods of the callback are never called by a decoder with any of the * arguments being {@code null}. * * @apiNote * *
The callback provides methods for all possible * * field line representations. * *
Names and values are {@link CharSequence}s rather than {@link String}s in * order to allow users to decide whether they need to create objects. A * {@code CharSequence} might be used in-place, for example, to be appended to * an {@link Appendable} (e.g. {@link StringBuilder}) and then discarded. * *
That said, if a passed {@code CharSequence} needs to outlast the method * call, it needs to be copied. * */ public interface DecodingCallback { /** * A method the more specific methods of the callback forward their calls * to. * * @param name * header name * @param value * header value */ void onDecoded(CharSequence name, CharSequence value); /** * A header fields decoding is completed. */ void onComplete(); /** * A connection-level error observed during the decoding process. * * @param throwable a {@code Throwable} instance * @param http3Error a HTTP3 error code */ void onConnectionError(Throwable throwable, Http3Error http3Error); /** * A stream-level error observed during the decoding process. * * @param throwable a {@code Throwable} instance * @param http3Error a HTTP3 error code */ default void onStreamError(Throwable throwable, Http3Error http3Error) { onConnectionError(throwable, http3Error); } /** * Reports if {@linkplain #onConnectionError(Throwable, Http3Error) a connection} * or {@linkplain #onStreamError(Throwable, Http3Error) a stream} error has been * observed during the decoding process * @return true - if error was observed; false - otherwise */ default boolean hasError() { return false; } /** * Returns request/response stream id or push stream id associated with a decoding callback. */ long streamId(); /** * A more finer-grained version of {@link #onDecoded(CharSequence, * CharSequence)} that also reports on value sensitivity. * *
Value sensitivity must be considered, for example, when implementing * an intermediary. A {@code value} is sensitive if it was represented as Literal Header * Field Never Indexed. * * @implSpec * *
The default implementation invokes {@code onDecoded(name, value)}. * * @param name * header name * @param value * header value * @param sensitive * whether the value is sensitive */ default void onDecoded(CharSequence name, CharSequence value, boolean sensitive) { onDecoded(name, value); } /** * An Indexed * Field Line decoded. * * @implSpec * *
The default implementation invokes * {@code onDecoded(name, value, false)}. * * @param index * index of a name/value pair in static or dynamic table * @param name * header name * @param value * header value */ default void onIndexed(long index, CharSequence name, CharSequence value) { onDecoded(name, value, false); } /** * A Literal * Field Line with Name Reference decoded, where a {@code name} was * referred by an {@code index}. * * @implSpec * *
The default implementation invokes * {@code onDecoded(name, value, false)}. * * @param index * index of an entry in the table * @param value * header value * @param valueHuffman * if the {@code value} was Huffman encoded * @param hideIntermediary * if the header field should be written to intermediary nodes */ default void onLiteralWithNameReference(long index, CharSequence name, CharSequence value, boolean valueHuffman, boolean hideIntermediary) { onDecoded(name, value, hideIntermediary); } /** * A Literal Field * Line with Literal Name decoded, where both a {@code name} and a {@code value} * were literal. * * @implSpec * *
The default implementation invokes * {@code onDecoded(name, value, false)}. * * @param name * header name * @param nameHuffman * if the {@code name} was Huffman encoded * @param value * header value * @param valueHuffman * if the {@code value} was Huffman encoded */ default void onLiteralWithLiteralName(CharSequence name, boolean nameHuffman, CharSequence value, boolean valueHuffman, boolean hideIntermediary) { onDecoded(name, value, hideIntermediary); } }