Package org.glassfish.grizzly.http2.hpack

Class Decoder

java.lang.Object
org.glassfish.grizzly.http2.hpack.Decoder
public final class Decoder extends Object
Decodes headers from their binary representation.

Typical lifecycle looks like this:

new Decoder (setMaxCapacity? decode)*

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.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Decoder(int capacity)
    Constructs a Decoder with the specified initial capacity of the header table.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    decode(Buffer headerBlockChunk, boolean finalChunk, DecodingCallback consumer)
    Decodes a header block from the given buffer to the given callback.
    void
    setMaxCapacity(int capacity)
    Sets a maximum capacity of the header table.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Decoder

      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 - a non-negative integer
      Throws:
      IllegalArgumentException - if capacity is negative

  • Method Details

    • setMaxCapacity

      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 - a non-negative integer
      Throws:
      IllegalArgumentException - if capacity is negative

    • decode

      public void decode(Buffer headerBlockChunk, boolean finalChunk, DecodingCallback consumer)
      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 UncheckedIOException.

      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. 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. 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:
      headerBlockChunk - the chunk of the header block, may be empty
      finalChunk - true if the chunk is the final (or the only one) in the sequence
      consumer - the callback
      Throws:
      RuntimeException - in case of a decoding error
      NullPointerException - if either headerBlock or consumer are null