1 /*

     2  * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 package java.net.http.internal.hpack;

    26 

    27 import java.nio.ByteBuffer;

    28 

    29 /**

    30  * Delivers results of the {@link Decoder#decode(ByteBuffer, boolean,

    31  * DecodingCallback) decoding operation}.

    32  *

    33  * <p> Methods of the callback are never called by a decoder with any of the

    34  * arguments being {@code null}.

    35  *

    36  * @apiNote

    37  *

    38  * <p> The callback provides methods for all possible

    39  * <a href="https://tools.ietf.org/html/rfc7541#section-6">binary representations</a>.

    40  * This could be useful for implementing an intermediary, logging, debugging,

    41  * etc.

    42  *

    43  * <p> The callback is an interface in order to interoperate with lambdas (in

    44  * the most common use case):

    45  * <pre>{@code

    46  *     DecodingCallback callback = (name, value) -> System.out.println(name + ", " + value);

    47  * }</pre>

    48  *

    49  * <p> Names and values are {@link CharSequence}s rather than {@link String}s in

    50  * order to allow users to decide whether or not they need to create objects. A

    51  * {@code CharSequence} might be used in-place, for example, to be appended to

    52  * an {@link Appendable} (e.g. {@link StringBuilder}) and then discarded.

    53  *

    54  * <p> That said, if a passed {@code CharSequence} needs to outlast the method

    55  * call, it needs to be copied.

    56  *

    57  * @since 9

    58  */

    59 @FunctionalInterface

    60 public interface DecodingCallback {

    61 

    62     /**

    63      * A method the more specific methods of the callback forward their calls

    64      * to.

    65      *

    66      * @param name

    67      *         header name

    68      * @param value

    69      *         header value

    70      */

    71     void onDecoded(CharSequence name, CharSequence value);

    72 

    73     /**

    74      * A more finer-grained version of {@link #onDecoded(CharSequence,

    75      * CharSequence)} that also reports on value sensitivity.

    76      *

    77      * <p> Value sensitivity must be considered, for example, when implementing

    78      * an intermediary. A {@code value} is sensitive if it was represented as <a

    79      * href="https://tools.ietf.org/html/rfc7541#section-6.2.3">Literal Header

    80      * Field Never Indexed</a>.

    81      *

    82      * <p> It is required that intermediaries MUST use the {@linkplain

    83      * Encoder#header(CharSequence, CharSequence, boolean) same representation}

    84      * for encoding this header field in order to protect its value which is not

    85      * to be put at risk by compressing it.

    86      *

    87      * @implSpec

    88      *

    89      * <p> The default implementation invokes {@code onDecoded(name, value)}.

    90      *

    91      * @param name

    92      *         header name

    93      * @param value

    94      *         header value

    95      * @param sensitive

    96      *         whether or not the value is sensitive

    97      *

    98      * @see #onLiteralNeverIndexed(int, CharSequence, CharSequence, boolean)

    99      * @see #onLiteralNeverIndexed(CharSequence, boolean, CharSequence, boolean)

   100      */

   101     default void onDecoded(CharSequence name,

   102                            CharSequence value,

   103                            boolean sensitive) {

   104         onDecoded(name, value);

   105     }

   106 

   107     /**

   108      * An <a href="https://tools.ietf.org/html/rfc7541#section-6.1">Indexed

   109      * Header Field</a> decoded.

   110      *

   111      * @implSpec

   112      *

   113      * <p> The default implementation invokes

   114      * {@code onDecoded(name, value, false)}.

   115      *

   116      * @param index

   117      *         index of an entry in the table

   118      * @param name

   119      *         header name

   120      * @param value

   121      *         header value

   122      */

   123     default void onIndexed(int index, CharSequence name, CharSequence value) {

   124         onDecoded(name, value, false);

   125     }

   126 

   127     /**

   128      * A <a href="https://tools.ietf.org/html/rfc7541#section-6.2.2">Literal

   129      * Header Field without Indexing</a> decoded, where a {@code name} was

   130      * referred by an {@code index}.

   131      *

   132      * @implSpec

   133      *

   134      * <p> The default implementation invokes

   135      * {@code onDecoded(name, value, false)}.

   136      *

   137      * @param index

   138      *         index of an entry in the table

   139      * @param name

   140      *         header name

   141      * @param value

   142      *         header value

   143      * @param valueHuffman

   144      *         if the {@code value} was Huffman encoded

   145      */

   146     default void onLiteral(int index,

   147                            CharSequence name,

   148                            CharSequence value,

   149                            boolean valueHuffman) {

   150         onDecoded(name, value, false);

   151     }

   152 

   153     /**

   154      * A <a href="https://tools.ietf.org/html/rfc7541#section-6.2.2">Literal

   155      * Header Field without Indexing</a> decoded, where both a {@code name} and

   156      * a {@code value} were literal.

   157      *

   158      * @implSpec

   159      *

   160      * <p> The default implementation invokes

   161      * {@code onDecoded(name, value, false)}.

   162      *

   163      * @param name

   164      *         header name

   165      * @param nameHuffman

   166      *         if the {@code name} was Huffman encoded

   167      * @param value

   168      *         header value

   169      * @param valueHuffman

   170      *         if the {@code value} was Huffman encoded

   171      */

   172     default void onLiteral(CharSequence name,

   173                            boolean nameHuffman,

   174                            CharSequence value,

   175                            boolean valueHuffman) {

   176         onDecoded(name, value, false);

   177     }

   178 

   179     /**

   180      * A <a href="https://tools.ietf.org/html/rfc7541#section-6.2.3">Literal

   181      * Header Field Never Indexed</a> decoded, where a {@code name}

   182      * was referred by an {@code index}.

   183      *

   184      * @implSpec

   185      *

   186      * <p> The default implementation invokes

   187      * {@code onDecoded(name, value, true)}.

   188      *

   189      * @param index

   190      *         index of an entry in the table

   191      * @param name

   192      *         header name

   193      * @param value

   194      *         header value

   195      * @param valueHuffman

   196      *         if the {@code value} was Huffman encoded

   197      */

   198     default void onLiteralNeverIndexed(int index,

   199                                        CharSequence name,

   200                                        CharSequence value,

   201                                        boolean valueHuffman) {

   202         onDecoded(name, value, true);

   203     }

   204 

   205     /**

   206      * A <a href="https://tools.ietf.org/html/rfc7541#section-6.2.3">Literal

   207      * Header Field Never Indexed</a> decoded, where both a {@code

   208      * name} and a {@code value} were literal.

   209      *

   210      * @implSpec

   211      *

   212      * <p> The default implementation invokes

   213      * {@code onDecoded(name, value, true)}.

   214      *

   215      * @param name

   216      *         header name

   217      * @param nameHuffman

   218      *         if the {@code name} was Huffman encoded

   219      * @param value

   220      *         header value

   221      * @param valueHuffman

   222      *         if the {@code value} was Huffman encoded

   223      */

   224     default void onLiteralNeverIndexed(CharSequence name,

   225                                        boolean nameHuffman,

   226                                        CharSequence value,

   227                                        boolean valueHuffman) {

   228         onDecoded(name, value, true);

   229     }

   230 

   231     /**

   232      * A <a href="https://tools.ietf.org/html/rfc7541#section-6.2.1">Literal

   233      * Header Field with Incremental Indexing</a> decoded, where a {@code name}

   234      * was referred by an {@code index}.

   235      *

   236      * @implSpec

   237      *

   238      * <p> The default implementation invokes

   239      * {@code onDecoded(name, value, false)}.

   240      *

   241      * @param index

   242      *         index of an entry in the table

   243      * @param name

   244      *         header name

   245      * @param value

   246      *         header value

   247      * @param valueHuffman

   248      *         if the {@code value} was Huffman encoded

   249      */

   250     default void onLiteralWithIndexing(int index,

   251                                        CharSequence name,

   252                                        CharSequence value,

   253                                        boolean valueHuffman) {

   254         onDecoded(name, value, false);

   255     }

   256 

   257     /**

   258      * A <a href="https://tools.ietf.org/html/rfc7541#section-6.2.1">Literal

   259      * Header Field with Incremental Indexing</a> decoded, where both a {@code

   260      * name} and a {@code value} were literal.

   261      *

   262      * @implSpec

   263      *

   264      * <p> The default implementation invokes

   265      * {@code onDecoded(name, value, false)}.

   266      *

   267      * @param name

   268      *         header name

   269      * @param nameHuffman

   270      *         if the {@code name} was Huffman encoded

   271      * @param value

   272      *         header value

   273      * @param valueHuffman

   274      *         if the {@code value} was Huffman encoded

   275      */

   276     default void onLiteralWithIndexing(CharSequence name,

   277                                        boolean nameHuffman,

   278                                        CharSequence value,

   279                                        boolean valueHuffman) {

   280         onDecoded(name, value, false);

   281     }

   282 

   283     /**

   284      * A <a href="https://tools.ietf.org/html/rfc7541#section-6.3">Dynamic Table

   285      * Size Update</a> decoded.

   286      *

   287      * @implSpec

   288      *

   289      * <p> The default implementation does nothing.

   290      *

   291      * @param capacity

   292      *         new capacity of the header table

   293      */

   294     default void onSizeUpdate(int capacity) { }

   295 }