Class Encoder



  • public class Encoder
    extends java.lang.Object
    Encodes headers to their binary representation.

    Typical lifecycle looks like this:

    new Encoder (setMaxCapacity? encode)*

    Suppose headers are represented by Map<String, List<String>>. A supplier and a consumer of ByteBuffers in forms of Supplier<ByteBuffer> and Consumer<ByteBuffer> respectively. Then to encode headers, the following approach might be used:

    
         for (Map.Entry<String, List<String>> h : headers.entrySet()) {
             String name = h.getKey();
             for (String value : h.getValue()) {
                 encoder.header(name, value);        // Set up header
                 boolean encoded;
                 do {
                     ByteBuffer b = buffersSupplier.get();
                     encoded = encoder.encode(b);    // Encode the header
                     buffersConsumer.accept(b);
                 } while (!encoded);
             }
         }
     

    Though the specification does not define how an encoder is to be implemented, a default implementation is provided by the method header(CharSequence, CharSequence, boolean).

    To provide a custom encoding implementation, Encoder has to be extended. A subclass then can access methods for encoding using specific representations (e.g. literal, indexed, etc.)

    Since:
    9
    • Constructor Summary

      Constructors 
      Constructor Description
      Encoder(int maxCapacity)
      Constructs an Encoder with the specified maximum capacity of the header table.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected int calculateCapacity(int maxCapacity)  
      protected void checkEncoding()  
      boolean encode(java.nio.ByteBuffer headerBlock)
      Encodes the set up header into the given buffer.
      protected jdk.incubator.http.internal.hpack.HeaderTable getHeaderTable()  
      protected int getMaxCapacity()  
      void header(java.lang.CharSequence name, java.lang.CharSequence value)
      Sets up the given header (name, value).
      void header(java.lang.CharSequence name, java.lang.CharSequence value, boolean sensitive)
      Sets up the given header (name, value) with possibly sensitive value.
      protected void indexed(int index)  
      protected void literal(int index, java.lang.CharSequence value, boolean useHuffman)  
      protected void literal(java.lang.CharSequence name, boolean nameHuffman, java.lang.CharSequence value, boolean valueHuffman)  
      protected void literalNeverIndexed(int index, java.lang.CharSequence value, boolean valueHuffman)  
      protected void literalNeverIndexed(java.lang.CharSequence name, boolean nameHuffman, java.lang.CharSequence value, boolean valueHuffman)  
      protected void literalWithIndexing(int index, java.lang.CharSequence value, boolean valueHuffman)  
      protected void literalWithIndexing(java.lang.CharSequence name, boolean nameHuffman, java.lang.CharSequence value, boolean valueHuffman)  
      void setMaxCapacity(int capacity)
      Sets a maximum capacity of the header table.
      protected void sizeUpdate(int capacity)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Encoder

        public Encoder(int maxCapacity)
        Constructs an Encoder with the specified 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:
        maxCapacity - a non-negative integer
        Throws:
        java.lang.IllegalArgumentException - if maxCapacity is negative
    • Method Detail

      • header

        public void header(java.lang.CharSequence name,
                           java.lang.CharSequence value)
                    throws java.lang.IllegalStateException
        Sets up the given header (name, value).

        Fixates name and value for the duration of encoding.

        Parameters:
        name - the name
        value - the value
        Throws:
        java.lang.NullPointerException - if any of the arguments are null
        java.lang.IllegalStateException - if the encoder hasn't fully encoded the previous header, or hasn't yet started to encode it
        See Also:
        header(CharSequence, CharSequence, boolean)
      • header

        public void header(java.lang.CharSequence name,
                           java.lang.CharSequence value,
                           boolean sensitive)
                    throws java.lang.IllegalStateException
        Sets up the given header (name, value) with possibly sensitive value.

        Fixates name and value for the duration of encoding.

        Parameters:
        name - the name
        value - the value
        sensitive - whether or not the value is sensitive
        Throws:
        java.lang.NullPointerException - if any of the arguments are null
        java.lang.IllegalStateException - if the encoder hasn't fully encoded the previous header, or hasn't yet started to encode it
        See Also:
        header(CharSequence, CharSequence), DecodingCallback.onDecoded(CharSequence, CharSequence, boolean)
      • 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).

        May be called any number of times after or before a complete header has been encoded.

        If the encoder decides to change the actual capacity, an update will be encoded before a new encoding operation starts.

        Parameters:
        capacity - a non-negative integer
        Throws:
        java.lang.IllegalArgumentException - if capacity is negative
        java.lang.IllegalStateException - if the encoder hasn't fully encoded the previous header, or hasn't yet started to encode it
      • calculateCapacity

        protected int calculateCapacity(int maxCapacity)
      • encode

        public final boolean encode(java.nio.ByteBuffer headerBlock)
        Encodes the set up header into the given buffer.

        The encoder writes as much as possible of the header's binary representation into the given buffer, starting at the buffer's position, and increments its position to reflect the bytes written. The buffer's mark and limit will not be modified.

        Once the method has returned true, the current header is deemed encoded. A new header may be set up.

        Parameters:
        headerBlock - the buffer to encode the header into, may be empty
        Returns:
        true if the current header has been fully encoded, false otherwise
        Throws:
        java.lang.NullPointerException - if the buffer is null
        java.nio.ReadOnlyBufferException - if this buffer is read-only
        java.lang.IllegalStateException - if there is no set up header
      • indexed

        protected final void indexed(int index)
                              throws java.lang.IndexOutOfBoundsException
        Throws:
        java.lang.IndexOutOfBoundsException
      • literal

        protected final void literal(int index,
                                     java.lang.CharSequence value,
                                     boolean useHuffman)
                              throws java.lang.IndexOutOfBoundsException
        Throws:
        java.lang.IndexOutOfBoundsException
      • literal

        protected final void literal(java.lang.CharSequence name,
                                     boolean nameHuffman,
                                     java.lang.CharSequence value,
                                     boolean valueHuffman)
      • literalNeverIndexed

        protected final void literalNeverIndexed(int index,
                                                 java.lang.CharSequence value,
                                                 boolean valueHuffman)
                                          throws java.lang.IndexOutOfBoundsException
        Throws:
        java.lang.IndexOutOfBoundsException
      • literalNeverIndexed

        protected final void literalNeverIndexed(java.lang.CharSequence name,
                                                 boolean nameHuffman,
                                                 java.lang.CharSequence value,
                                                 boolean valueHuffman)
      • literalWithIndexing

        protected final void literalWithIndexing(int index,
                                                 java.lang.CharSequence value,
                                                 boolean valueHuffman)
                                          throws java.lang.IndexOutOfBoundsException
        Throws:
        java.lang.IndexOutOfBoundsException
      • literalWithIndexing

        protected final void literalWithIndexing(java.lang.CharSequence name,
                                                 boolean nameHuffman,
                                                 java.lang.CharSequence value,
                                                 boolean valueHuffman)
      • sizeUpdate

        protected final void sizeUpdate(int capacity)
                                 throws java.lang.IllegalArgumentException
        Throws:
        java.lang.IllegalArgumentException
      • getMaxCapacity

        protected final int getMaxCapacity()
      • getHeaderTable

        protected final jdk.incubator.http.internal.hpack.HeaderTable getHeaderTable()
      • checkEncoding

        protected final void checkEncoding()