APIdia Launch Partner
Top Description Inners Fields Constructors Methods
jdk.internal.net.http.hpack

public final Class Decoder

extends Object
Class Inheritance
Imports
jdk.internal.net.http.hpack.HPACK.Logger, java.io.IOException, java.net.ProtocolException, java.nio.ByteBuffer, java.util.List, java.util.concurrent.atomic.AtomicLong
Decodes headers from their binary representation.

Typical lifecycle looks like this:

new Decoder (setMaxCapacity? decode)*

API Note

The design intentions behind Decoder were to facilitate flexible and incremental style of processing.

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 a freedom to decide how headers are processed. The callback does not limit the number of headers decoded during single decoding operation.

Since
9

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static enum
Decoder.State

Field Summary

Modifier and TypeField and Description
private int
capacity

private static final AtomicLong
DECODERS_IDS

private boolean
firstValueIndex

private boolean
firstValueRead

private final long
id

private int
indexed

private final IntegerReader
integerReader

private int
intValue

private final HPACK.Logger
logger

private final int
maxHeaderListSize

private final int
maxIndexed

private final StringBuilder
name

private boolean
nameHuffmanEncoded

private long
size

private Decoder.State
state

private static final List<Decoder.State>
states

private final StringReader
stringReader

private final SimpleHeaderTable
table

private final StringBuilder
value

private boolean
valueHuffmanEncoded

Constructor Summary

AccessConstructor and Description
public
Decoder(int
a non-negative integer
capacity)

Constructs a Decoder with the specified initial capacity of the header table.

public
Decoder(int
a non-negative integer
capacity, int
a maximum value for the header list size. This is the uncompressed names size + uncompressed values size + 32 bytes per field line
maxHeaderListSize, int
the maximum number of literal with indexing we're prepared to handle for a header field section
maxIndexed)

Constructs a Decoder with the specified initial capacity of the header table, a max header list size, and a maximum number of literals with indexing per header section.

Method Summary

Modifier and TypeMethod and Description
private void
checkMaxHeaderListSize(long sz, DecodingCallback consumer)

private void
cleanUpAfterReading()

private boolean
completeReading(ByteBuffer input, DecodingCallback action)

public void
decode(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, DecodingCallback
the callback
consumer)

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

private SimpleHeaderTable.HeaderField
getHeaderFieldAt(int index)

pack-priv SimpleHeaderTable
getTable()

private void
proceed(ByteBuffer input, DecodingCallback action)

private void
resumeIndexed(ByteBuffer input, DecodingCallback action)

private void
resumeLiteral(ByteBuffer input, DecodingCallback action)

private void
resumeLiteralNeverIndexed(ByteBuffer input, DecodingCallback action)

private void
resumeLiteralWithIndexing(ByteBuffer input, DecodingCallback action)

private void
resumeReady(ByteBuffer input, DecodingCallback action)

private void
resumeSizeUpdate(ByteBuffer input, DecodingCallback action)

public void
setMaxCapacity(int
a non-negative integer
capacity)

Sets a maximum capacity of the header table.

private void
setMaxCapacity0(int capacity)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

capacityback to summary
private int capacity
DECODERS_IDSback to summary
private static final AtomicLong DECODERS_IDS
firstValueIndexback to summary
private boolean firstValueIndex
firstValueReadback to summary
private boolean firstValueRead
idback to summary
private final long id
indexedback to summary
private int indexed
integerReaderback to summary
private final IntegerReader integerReader
intValueback to summary
private int intValue
loggerback to summary
private final HPACK.Logger logger
maxHeaderListSizeback to summary
private final int maxHeaderListSize
maxIndexedback to summary
private final int maxIndexed
nameback to summary
private final StringBuilder name
nameHuffmanEncodedback to summary
private boolean nameHuffmanEncoded
sizeback to summary
private long size
stateback to summary
private Decoder.State state
statesback to summary
private static final List<Decoder.State> states
stringReaderback to summary
private final StringReader stringReader
tableback to summary
private final SimpleHeaderTable table
valueback to summary
private final StringBuilder value
valueHuffmanEncodedback to summary
private boolean valueHuffmanEncoded

Constructor Detail

Decoderback to summary
public Decoder(int capacity)

Constructs a Decoder with the specified initial capacity of the header table.

The value has to be agreed between decoder and encoder out-of-band, e.g. by a protocol that uses HPACK (see 4.2. Maximum Table Size).

Parameters
capacity:int

a non-negative integer

Exceptions
IllegalArgumentException:
if capacity is negative
Decoderback to summary
public Decoder(int capacity, int maxHeaderListSize, int maxIndexed)

Constructs a Decoder with the specified initial capacity of the header table, a max header list size, and a maximum number of literals with indexing per header section.

The value of the capacity has to be agreed between decoder and encoder out-of-band, e.g. by a protocol that uses HPACK (see 4.2. Maximum Table Size).

Parameters
capacity:int

a non-negative integer

maxHeaderListSize:int

a maximum value for the header list size. This is the uncompressed names size + uncompressed values size + 32 bytes per field line

maxIndexed:int

the maximum number of literal with indexing we're prepared to handle for a header field section

Exceptions
IllegalArgumentException:
if capacity is negative

Method Detail

checkMaxHeaderListSizeback to summary
private void checkMaxHeaderListSize(long sz, DecodingCallback consumer) throws ProtocolException
cleanUpAfterReadingback to summary
private void cleanUpAfterReading()
completeReadingback to summary
private boolean completeReading(ByteBuffer input, DecodingCallback action) throws IOException
decodeback to summary
public void decode(ByteBuffer headerBlock, boolean endOfHeaderBlock, DecodingCallback consumer) throws IOException

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. Then to decode the header block, the following approach might be used: 

while (buffers.hasNext()) {
    ByteBuffer input = buffers.next();
    decoder.decode(input, callback, !buffers.hasNext());
}

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 by throwing an IOException.

Each callback method is called only after the implementation has processed the corresponding bytes. If the bytes revealed a decoding error, the callback method is not called.

In addition to exceptions thrown directly by the method, any exceptions thrown from the callback will bubble up.

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

consumer:DecodingCallback

the callback

Exceptions
IOException:
in case of a decoding error
NullPointerException:
if either headerBlock or consumer are null
getHeaderFieldAtback to summary
private SimpleHeaderTable.HeaderField getHeaderFieldAt(int index) throws IOException
getTableback to summary
pack-priv SimpleHeaderTable getTable()
proceedback to summary
private void proceed(ByteBuffer input, DecodingCallback action) throws IOException
resumeIndexedback to summary
private void resumeIndexed(ByteBuffer input, DecodingCallback action) throws IOException
resumeLiteralback to summary
private void resumeLiteral(ByteBuffer input, DecodingCallback action) throws IOException
resumeLiteralNeverIndexedback to summary
private void resumeLiteralNeverIndexed(ByteBuffer input, DecodingCallback action) throws IOException
resumeLiteralWithIndexingback to summary
private void resumeLiteralWithIndexing(ByteBuffer input, DecodingCallback action) throws IOException
resumeReadyback to summary
private void resumeReady(ByteBuffer input, DecodingCallback action) throws IOException
resumeSizeUpdateback to summary
private void resumeSizeUpdate(ByteBuffer input, DecodingCallback action) throws IOException
setMaxCapacityback to summary
public void setMaxCapacity(int capacity)

Sets a maximum capacity of the header table.

The value has to be agreed between decoder and encoder out-of-band, e.g. by a protocol that uses HPACK (see 4.2. Maximum Table Size).

Parameters
capacity:int

a non-negative integer

Exceptions
IllegalArgumentException:
if capacity is negative
setMaxCapacity0back to summary
private void setMaxCapacity0(int capacity)
jdk.internal.net.http.hpack back to summary

private final Enum Decoder.State

extends Enum<Decoder.State>
Class Inheritance

Field Summary

Modifier and TypeField and Description
public static final Decoder.State
INDEXED

public static final Decoder.State
LITERAL

public static final Decoder.State
LITERAL_NEVER_INDEXED

public static final Decoder.State
LITERAL_WITH_INDEXING

public static final Decoder.State
READY

public static final Decoder.State
SIZE_UPDATE

Constructor Summary

AccessConstructor and Description
private
State()

Method Summary

Modifier and TypeMethod and Description
public static Decoder.State
valueOf(String name)

public static Decoder.State[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

INDEXEDback to summary
public static final Decoder.State INDEXED
LITERALback to summary
public static final Decoder.State LITERAL
LITERAL_NEVER_INDEXEDback to summary
public static final Decoder.State LITERAL_NEVER_INDEXED
LITERAL_WITH_INDEXINGback to summary
public static final Decoder.State LITERAL_WITH_INDEXING
READYback to summary
public static final Decoder.State READY
SIZE_UPDATEback to summary
public static final Decoder.State SIZE_UPDATE

Constructor Detail

Stateback to summary
private State()

Method Detail

valueOfback to summary
public static Decoder.State valueOf(String name)
valuesback to summary
public static Decoder.State[] values()