OpenJDK 27 · jdk.internal.net.http.qpack.Decoder · APIdia, the JavaDoc alternative

Decodes headers from their binary representation.

Typical lifecycle looks like this:

new Decoder (configure(ConnectionSettings) called once from our HTTP/3 settings decodeHeader

Decoder does not require a complete header block in a single ByteBuffer. The header block can be spread across many buffers of any size and decoded one-by-one the way it makes most sense for the user. This way also allows not to limit the size of the header block.

Headers are delivered to the callback as soon as they become decoded. Using the callback also gives the user freedom to decide how headers are processed. The callback does not limit the number of headers decoded during single decoding operation.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private class	Decoder.DecoderTableCallback

Field Summary

Modifier and Type	Field and Description
private final ReentrantLock	ackInsertCountLock
private long	acknowledgedInsertsCount
private final AtomicLong	blockedStreamsCounter
private final AtomicLong	concurrentDynamicTableInsertions
private static final AtomicLong	DECODERS_IDS
private final QueuingStreamPair	decoderStreamPair
private final DynamicTable	dynamicTable
private final EncoderInstructionsReader	encoderInstructionsReader
private final QPACK.Logger	logger
private static final long	MAX_LITERAL_WITH_INDEXING
private volatile long	maxBlockedStreams
private volatile long	maxFieldSectionSize
private final QPACK.QPACKErrorHandler	qpackErrorHandler

Constructor Summary

Access	Constructor and Description
public	Decoder(QPACK.StreamPairSupplier streams, QPACK.QPACKErrorHandler errorHandler) Constructs a `Decoder` with zero initial capacity of the dynamic table.

Method Summary

Modifier and Type	Method and Description
public void	ackSection(long stream ID associated with the field section's streamId, HeaderFrameReader header frame reader used to read the field line section headerFrameReader) Submit "Section Acknowledgment" instruction to the decoder stream.
public void	ackTableInsertions()
public void	cancelStream(long streamId)
public void	configure(ConnectionSettings connection settings ourSettings) Configures maximum capacity of the decoder's dynamic table based on connection settings of the HTTP client, also configures the number of allowed blocked streams.
public void	decodeHeader(ByteBuffer the chunk of the header block, may be empty headerBlock, boolean true if the chunk is the final (or the only one) in the sequence endOfHeaderBlock, HeaderFrameReader the stateful header frame reader headerFrameReader) Decodes a header block from the given buffer to the given callback.
public QueuingStreamPair	decoderStreams()
pack-priv void	incrementAndCheckDynamicTableInsertsCount()
public HeaderFrameReader	Returns: a new `HeaderFrameReader` that will hold the decoding state for a new request/response stream newHeaderFrameReader(DecodingCallback decodingCallback) Returns a new `HeaderFrameReader` that will hold the decoding state for a new request/response stream.
private void	processEncoderInstruction(ByteBuffer buffer) This method is invoked when the decoder's stream reader has data available for reading.
public void	resetInsertionsCounter()
private void	submitDecoderInstruction(DecoderInstructionsWriter decoderInstructionsWriter, int size)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

ackInsertCountLock	back to summary
private final ReentrantLock ackInsertCountLock

acknowledgedInsertsCount	back to summary
private long acknowledgedInsertsCount

blockedStreamsCounter	back to summary
private final AtomicLong blockedStreamsCounter

concurrentDynamicTableInsertions	back to summary
private final AtomicLong concurrentDynamicTableInsertions

DECODERS_IDS	back to summary
private static final AtomicLong DECODERS_IDS

decoderStreamPair	back to summary
private final QueuingStreamPair decoderStreamPair

dynamicTable	back to summary
private final DynamicTable dynamicTable

encoderInstructionsReader	back to summary
private final EncoderInstructionsReader encoderInstructionsReader

logger	back to summary
private final QPACK.Logger logger

MAX_LITERAL_WITH_INDEXING	back to summary
private static final long MAX_LITERAL_WITH_INDEXING

maxBlockedStreams	back to summary
private volatile long maxBlockedStreams

maxFieldSectionSize	back to summary
private volatile long maxFieldSectionSize

qpackErrorHandler	back to summary
private final QPACK.QPACKErrorHandler qpackErrorHandler

Constructor Detail

Decoder back to summary

Decoder	back to summary
public Decoder(QPACK.StreamPairSupplier streams, QPACK.QPACKErrorHandler errorHandler) Constructs a `Decoder` with zero initial capacity of the dynamic table. Dynamic table capacity values has to be agreed between decoder and encoder out-of-band, e.g. by a protocol that uses QPACK. Maximum dynamic table capacity is determined by the value of SETTINGS_QPACK_MAX_TABLE_CAPACITY HTTP/3 setting sent by the decoder side (see 3.2.3. Maximum Dynamic Table Capacity). An encoder informs the decoder of a change to the dynamic table capacity using the "Set Dynamic Table Capacity" instruction (see 4.3.1. Set Dynamic Table Capacity) See Also `Decoder#configure(ConnectionSettings)`

public Decoder(QPACK.StreamPairSupplier streams, QPACK.QPACKErrorHandler errorHandler)

Constructs a Decoder with zero initial capacity of the dynamic table.

Dynamic table capacity values has to be agreed between decoder and encoder out-of-band, e.g. by a protocol that uses QPACK.

Maximum dynamic table capacity is determined by the value of SETTINGS_QPACK_MAX_TABLE_CAPACITY HTTP/3 setting sent by the decoder side (see 3.2.3. Maximum Dynamic Table Capacity).

An encoder informs the decoder of a change to the dynamic table capacity using the "Set Dynamic Table Capacity" instruction (see 4.3.1. Set Dynamic Table Capacity)

See Also: Decoder#configure(ConnectionSettings)

Method Detail

ackSection	back to summary
public void ackSection(long streamId, HeaderFrameReader headerFrameReader) Submit "Section Acknowledgment" instruction to the decoder stream. A field line section needs to be acknowledged after completion of section decoding. Parameters streamId:long stream ID associated with the field section's headerFrameReader:HeaderFrameReader header frame reader used to read the field line section

ackSection

back to summary

public void ackSection(long streamId, HeaderFrameReader headerFrameReader)

Submit "Section Acknowledgment" instruction to the decoder stream. A field line section needs to be acknowledged after completion of section decoding.

Parameters

streamId:long: stream ID associated with the field section's
headerFrameReader:HeaderFrameReader: header frame reader used to read the field line section

ackTableInsertions	back to summary
public void ackTableInsertions()

cancelStream	back to summary
public void cancelStream(long streamId)

configure	back to summary
public void configure(ConnectionSettings ourSettings) Configures maximum capacity of the decoder's dynamic table based on connection settings of the HTTP client, also configures the number of allowed blocked streams. The decoder's dynamic table capacity can only be changed via encoder instructions callback. Parameters ourSettings:ConnectionSettings connection settings

configure

back to summary

public void configure(ConnectionSettings ourSettings)

Configures maximum capacity of the decoder's dynamic table based on connection settings of the HTTP client, also configures the number of allowed blocked streams. The decoder's dynamic table capacity can only be changed via encoder instructions callback.

Parameters

ourSettings:ConnectionSettings: connection settings

decodeHeader back to summary

decodeHeader	back to summary
public void decodeHeader(ByteBuffer headerBlock, boolean endOfHeaderBlock, HeaderFrameReader headerFrameReader) Decodes a header block from the given buffer to the given callback. Suppose a header block is represented by a sequence of `ByteBuffer`s in the form of `Iterator<ByteBuffer>`. And the consumer of decoded headers is represented by the callback registered within the provided `headerFrameReader`. Then to decode the header block, the following approach might be used: `HeaderFrameReader headerFrameReader = newHeaderFrameReader(decodingCallback); while (buffers.hasNext()) { ByteBuffer input = buffers.next(); decoder.decodeHeader(input, !buffers.hasNext(), headerFrameReader); }` HeaderFrameReader headerFrameReader = newHeaderFrameReader(decodingCallback); while (buffers.hasNext()) { ByteBuffer input = buffers.next(); decoder.decodeHeader(input, !buffers.hasNext(), headerFrameReader); } The decoder reads as much as possible of the header block from the given buffer, starting at the buffer's position, and increments its position to reflect the bytes read. The buffer's mark and limit will not be modified. Once the method is invoked with `endOfHeaderBlock == true`, the current header block is deemed ended, and inconsistencies, if any, are reported immediately via a callback registered within the `headerFrameReader` instance. Each callback method is called only after the implementation has processed the corresponding bytes. If the bytes revealed a decoding error it is reported via a callback registered within the `headerFrameReader` instance. API Note The method asks for `endOfHeaderBlock` flag instead of returning it for two reasons. The first one is that the user of the decoder always knows which chunk is the last. The second one is to throw the most detailed exception possible, which might be useful for diagnosing issues. Implementation Note This implementation is not atomic in respect to decoding errors. In other words, if the decoding operation has thrown a decoding error, the decoder is no longer usable. Parameters headerBlock:ByteBuffer the chunk of the header block, may be empty endOfHeaderBlock:boolean true if the chunk is the final (or the only one) in the sequence headerFrameReader:HeaderFrameReader the stateful header frame reader Exceptions NullPointerException: if either `headerBlock` or `headerFrameReader` are null

public void decodeHeader(ByteBuffer headerBlock, boolean endOfHeaderBlock, HeaderFrameReader headerFrameReader)

Decodes a header block from the given buffer to the given callback.

Suppose a header block is represented by a sequence of ByteBuffers in the form of Iterator<ByteBuffer>. And the consumer of decoded headers is represented by the callback registered within the provided headerFrameReader. Then to decode the header block, the following approach might be used:

HeaderFrameReader headerFrameReader =
     newHeaderFrameReader(decodingCallback);
while (buffers.hasNext()) {
    ByteBuffer input = buffers.next();
    decoder.decodeHeader(input, !buffers.hasNext(), headerFrameReader);
}

The decoder reads as much as possible of the header block from the given buffer, starting at the buffer's position, and increments its position to reflect the bytes read. The buffer's mark and limit will not be modified.

Once the method is invoked with endOfHeaderBlock == true, the current header block is deemed ended, and inconsistencies, if any, are reported immediately via a callback registered within the headerFrameReader instance.

Each callback method is called only after the implementation has processed the corresponding bytes. If the bytes revealed a decoding error it is reported via a callback registered within the headerFrameReader instance.

API Note

The method asks for endOfHeaderBlock flag instead of returning it for two reasons. The first one is that the user of the decoder always knows which chunk is the last. The second one is to throw the most detailed exception possible, which might be useful for diagnosing issues.

Implementation Note

This implementation is not atomic in respect to decoding errors. In other words, if the decoding operation has thrown a decoding error, the decoder is no longer usable.

Parameters

headerBlock:ByteBuffer: the chunk of the header block, may be empty
endOfHeaderBlock:boolean: true if the chunk is the final (or the only one) in the sequence
headerFrameReader:HeaderFrameReader: the stateful header frame reader

Exceptions

NullPointerException:: if either headerBlock or headerFrameReader are null

decoderStreams	back to summary
public QueuingStreamPair decoderStreams()

incrementAndCheckDynamicTableInsertsCount	back to summary
pack-priv void incrementAndCheckDynamicTableInsertsCount()

newHeaderFrameReader back to summary

newHeaderFrameReader	back to summary
public HeaderFrameReader newHeaderFrameReader(DecodingCallback decodingCallback) Returns a new `HeaderFrameReader` that will hold the decoding state for a new request/response stream. Returns:HeaderFrameReader a new `HeaderFrameReader` that will hold the decoding state for a new request/response stream

public HeaderFrameReader newHeaderFrameReader(DecodingCallback decodingCallback)

Returns a new HeaderFrameReader that will hold the decoding state for a new request/response stream.

Returns:HeaderFrameReader: a new HeaderFrameReader that will hold the decoding state for a new request/response stream

processEncoderInstruction	back to summary
private void processEncoderInstruction(ByteBuffer buffer) This method is invoked when the decoder's stream reader has data available for reading.

resetInsertionsCounter	back to summary
public void resetInsertionsCounter()

submitDecoderInstruction	back to summary
private void submitDecoderInstruction(DecoderInstructionsWriter decoderInstructionsWriter, int size)

public final Class Decoder

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class Decoder.DecoderTableCallback

Constructor Summary

Method Summary

Constructor Detail

Method Detail

Modifier and Type	Method and Description
private void	ensureInstructionsAllowed()
public void	onCapacityUpdate(long capacity) Implements jdk.internal.net.http.qpack.readers.EncoderInstructionsReader.Callback.onCapacityUpdate.
public void	onDuplicate(long l) Implements jdk.internal.net.http.qpack.readers.EncoderInstructionsReader.Callback.onDuplicate.
public void	onInsert(String name, String value) Implements jdk.internal.net.http.qpack.readers.EncoderInstructionsReader.Callback.onInsert.
public void	onInsertIndexedName(boolean indexInStaticTable, long nameIndex, String valueString) Implements jdk.internal.net.http.qpack.readers.EncoderInstructionsReader.Callback.onInsertIndexedName.