View Javadoc
1   /*
2    * Copyright 2014 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License, version 2.0 (the
5    * "License"); you may not use this file except in compliance with the License. You may obtain a
6    * copy of the License at:
7    *
8    * https://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software distributed under the License
11   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
12   * or implied. See the License for the specific language governing permissions and limitations under
13   * the License.
14   */
15  package io.netty5.handler.codec;
16  
17  import java.util.Iterator;
18  import java.util.List;
19  import java.util.Map.Entry;
20  import java.util.Set;
21  
22  /**
23   * Common interface for {@link Headers} which represents a mapping of key to value.
24   * Duplicate keys may be allowed by implementations.
25   *
26   * @param <K> the type of the header name.
27   * @param <V> the type of the header value.
28   * @param <T> the type to use for return values when the intention is to return {@code this} object.
29   */
30  public interface Headers<K, V, T extends Headers<K, V, T>> extends Iterable<Entry<K, V>> {
31      /**
32       * Returns the value of a header with the specified name. If there is more than one value for the specified name,
33       * the first value in insertion order is returned.
34       *
35       * @param name the name of the header to retrieve
36       * @return the first header value if the header is found. {@code null} if there's no such header
37       */
38      V get(K name);
39  
40      /**
41       * Returns the value of a header with the specified name. If there is more than one value for the specified name,
42       * the first value in insertion order is returned.
43       *
44       * @param name the name of the header to retrieve
45       * @param defaultValue the default value
46       * @return the first header value or {@code defaultValue} if there is no such header
47       */
48      V get(K name, V defaultValue);
49  
50      /**
51       * Returns the value of a header with the specified name and removes it from this object. If there is more than
52       * one value for the specified name, the first value in insertion order is returned.
53       *
54       * @param name the name of the header to retrieve
55       * @return the first header value or {@code null} if there is no such header
56       */
57      V getAndRemove(K name);
58  
59      /**
60       * Returns the value of a header with the specified name and removes it from this object. If there is more than
61       * one value for the specified name, the first value in insertion order is returned.
62       *
63       * @param name the name of the header to retrieve
64       * @param defaultValue the default value
65       * @return the first header value or {@code defaultValue} if there is no such header
66       */
67      V getAndRemove(K name, V defaultValue);
68  
69      /**
70       * Returns all values for the header with the specified name. The returned {@link List} can't be modified.
71       *
72       * @param name the name of the header to retrieve
73       * @return a {@link List} of header values or an empty {@link List} if no values are found.
74       */
75      List<V> getAll(K name);
76  
77      /**
78       * Returns all values for the header with the specified name and removes them from this object.
79       * The returned {@link List} can't be modified.
80       *
81       * @param name the name of the header to retrieve
82       * @return a {@link List} of header values or an empty {@link List} if no values are found.
83       */
84      List<V> getAllAndRemove(K name);
85  
86      /**
87       * Returns the {@code boolean} value of a header with the specified name. If there is more than one value for the
88       * specified name, the first value in insertion order is returned.
89       *
90       * @param name the name of the header to retrieve
91       * @return the {@code boolean} value of the first value in insertion order or {@code null} if there is no such
92       *         value or it can't be converted to {@code boolean}.
93       */
94      Boolean getBoolean(K name);
95  
96      /**
97       * Returns the {@code boolean} value of a header with the specified name. If there is more than one value for the
98       * specified name, the first value in insertion order is returned.
99       *
100      * @param name the name of the header to retrieve
101      * @param defaultValue the default value
102      * @return the {@code boolean} value of the first value in insertion order or {@code defaultValue} if there is no
103      *         such value or it can't be converted to {@code boolean}.
104      */
105     boolean getBoolean(K name, boolean defaultValue);
106 
107     /**
108      * Returns the {@code byte} value of a header with the specified name. If there is more than one value for the
109      * specified name, the first value in insertion order is returned.
110      *
111      * @param name the name of the header to retrieve
112      * @return the {@code byte} value of the first value in insertion order or {@code null} if there is no such
113      *         value or it can't be converted to {@code byte}.
114      */
115     Byte getByte(K name);
116 
117     /**
118      * Returns the {@code byte} value of a header with the specified name. If there is more than one value for the
119      * specified name, the first value in insertion order is returned.
120      *
121      * @param name the name of the header to retrieve
122      * @param defaultValue the default value
123      * @return the {@code byte} value of the first value in insertion order or {@code defaultValue} if there is no
124      *         such value or it can't be converted to {@code byte}.
125      */
126     byte getByte(K name, byte defaultValue);
127 
128     /**
129      * Returns the {@code char} value of a header with the specified name. If there is more than one value for the
130      * specified name, the first value in insertion order is returned.
131      *
132      * @param name the name of the header to retrieve
133      * @return the {@code char} value of the first value in insertion order or {@code null} if there is no such
134      *         value or it can't be converted to {@code char}.
135      */
136     Character getChar(K name);
137 
138     /**
139      * Returns the {@code char} value of a header with the specified name. If there is more than one value for the
140      * specified name, the first value in insertion order is returned.
141      *
142      * @param name the name of the header to retrieve
143      * @param defaultValue the default value
144      * @return the {@code char} value of the first value in insertion order or {@code defaultValue} if there is no
145      *         such value or it can't be converted to {@code char}.
146      */
147     char getChar(K name, char defaultValue);
148 
149     /**
150      * Returns the {@code short} value of a header with the specified name. If there is more than one value for the
151      * specified name, the first value in insertion order is returned.
152      *
153      * @param name the name of the header to retrieve
154      * @return the {@code short} value of the first value in insertion order or {@code null} if there is no such
155      *         value or it can't be converted to {@code short}.
156      */
157     Short getShort(K name);
158 
159     /**
160      * Returns the {@code short} value of a header with the specified name. If there is more than one value for the
161      * specified name, the first value in insertion order is returned.
162      *
163      * @param name the name of the header to retrieve
164      * @param defaultValue the default value
165      * @return the {@code short} value of the first value in insertion order or {@code defaultValue} if there is no
166      *         such value or it can't be converted to {@code short}.
167      */
168     short getShort(K name, short defaultValue);
169 
170     /**
171      * Returns the {@code int} value of a header with the specified name. If there is more than one value for the
172      * specified name, the first value in insertion order is returned.
173      *
174      * @param name the name of the header to retrieve
175      * @return the {@code int} value of the first value in insertion order or {@code null} if there is no such
176      *         value or it can't be converted to {@code int}.
177      */
178     Integer getInt(K name);
179 
180     /**
181      * Returns the {@code int} value of a header with the specified name. If there is more than one value for the
182      * specified name, the first value in insertion order is returned.
183      *
184      * @param name the name of the header to retrieve
185      * @param defaultValue the default value
186      * @return the {@code int} value of the first value in insertion order or {@code defaultValue} if there is no
187      *         such value or it can't be converted to {@code int}.
188      */
189     int getInt(K name, int defaultValue);
190 
191     /**
192      * Returns the {@code long} value of a header with the specified name. If there is more than one value for the
193      * specified name, the first value in insertion order is returned.
194      *
195      * @param name the name of the header to retrieve
196      * @return the {@code long} value of the first value in insertion order or {@code null} if there is no such
197      *         value or it can't be converted to {@code long}.
198      */
199     Long getLong(K name);
200 
201     /**
202      * Returns the {@code long} value of a header with the specified name. If there is more than one value for the
203      * specified name, the first value in insertion order is returned.
204      *
205      * @param name the name of the header to retrieve
206      * @param defaultValue the default value
207      * @return the {@code long} value of the first value in insertion order or {@code defaultValue} if there is no
208      *         such value or it can't be converted to {@code long}.
209      */
210     long getLong(K name, long defaultValue);
211 
212     /**
213      * Returns the {@code float} value of a header with the specified name. If there is more than one value for the
214      * specified name, the first value in insertion order is returned.
215      *
216      * @param name the name of the header to retrieve
217      * @return the {@code float} value of the first value in insertion order or {@code null} if there is no such
218      *         value or it can't be converted to {@code float}.
219      */
220     Float getFloat(K name);
221 
222     /**
223      * Returns the {@code float} value of a header with the specified name. If there is more than one value for the
224      * specified name, the first value in insertion order is returned.
225      *
226      * @param name the name of the header to retrieve
227      * @param defaultValue the default value
228      * @return the {@code float} value of the first value in insertion order or {@code defaultValue} if there is no
229      *         such value or it can't be converted to {@code float}.
230      */
231     float getFloat(K name, float defaultValue);
232 
233     /**
234      * Returns the {@code double} value of a header with the specified name. If there is more than one value for the
235      * specified name, the first value in insertion order is returned.
236      *
237      * @param name the name of the header to retrieve
238      * @return the {@code double} value of the first value in insertion order or {@code null} if there is no such
239      *         value or it can't be converted to {@code double}.
240      */
241     Double getDouble(K name);
242 
243     /**
244      * Returns the {@code double} value of a header with the specified name. If there is more than one value for the
245      * specified name, the first value in insertion order is returned.
246      *
247      * @param name the name of the header to retrieve
248      * @param defaultValue the default value
249      * @return the {@code double} value of the first value in insertion order or {@code defaultValue} if there is no
250      *         such value or it can't be converted to {@code double}.
251      */
252     double getDouble(K name, double defaultValue);
253 
254     /**
255      * Returns the value of a header with the specified name in milliseconds. If there is more than one value for the
256      * specified name, the first value in insertion order is returned.
257      *
258      * @param name the name of the header to retrieve
259      * @return the milliseconds value of the first value in insertion order or {@code null} if there is no such
260      *         value or it can't be converted to milliseconds.
261      */
262     Long getTimeMillis(K name);
263 
264     /**
265      * Returns the value of a header with the specified name in milliseconds. If there is more than one value for the
266      * specified name, the first value in insertion order is returned.
267      *
268      * @param name the name of the header to retrieve
269      * @param defaultValue the default value
270      * @return the milliseconds value of the first value in insertion order or {@code defaultValue} if there is no such
271      *         value or it can't be converted to milliseconds.
272      */
273     long getTimeMillis(K name, long defaultValue);
274 
275     /**
276      * Returns the {@code boolean} value of a header with the specified {@code name} and removes the header from this
277      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
278      * In any case all values for {@code name} are removed.
279      * <p>
280      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
281      * be removed.
282      * @param name the name of the header to retrieve
283      * @return the {@code boolean} value of the first value in insertion order or {@code null} if there is no
284      *         such value or it can't be converted to {@code boolean}.
285      */
286     Boolean getBooleanAndRemove(K name);
287 
288     /**
289      * Returns the {@code boolean} value of a header with the specified {@code name} and removes the header from this
290      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
291      * In any case all values for {@code name} are removed.
292      * <p>
293      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
294      * be removed.
295      * @param name the name of the header to search
296      * @param defaultValue the default value
297      * @return the {@code boolean} value of the first value in insertion order or {@code defaultValue} if there is no
298      *         such value or it can't be converted to {@code boolean}.
299      */
300     boolean getBooleanAndRemove(K name, boolean defaultValue);
301 
302     /**
303      * Returns the {@code byte} value of a header with the specified {@code name} and removes the header from this
304      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
305      * In any case all values for {@code name} are removed.
306      * <p>
307      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
308      * be removed.
309      * @param name the name of the header to search
310      * @return the {@code byte} value of the first value in insertion order or {@code null} if there is no
311      *         such value or it can't be converted to {@code byte}.
312      */
313     Byte getByteAndRemove(K name);
314 
315     /**
316      * Returns the {@code byte} value of a header with the specified {@code name} and removes the header from this
317      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
318      * In any case all values for {@code name} are removed.
319      * <p>
320      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
321      * be removed.
322      * @param name the name of the header to search
323      * @param defaultValue the default value
324      * @return the {@code byte} value of the first value in insertion order or {@code defaultValue} if there is no
325      *         such value or it can't be converted to {@code byte}.
326      */
327     byte getByteAndRemove(K name, byte defaultValue);
328 
329     /**
330      * Returns the {@code char} value of a header with the specified {@code name} and removes the header from this
331      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
332      * In any case all values for {@code name} are removed.
333      * <p>
334      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
335      * be removed.
336      * @param name the name of the header to search
337      * @return the {@code char} value of the first value in insertion order or {@code null} if there is no
338      *         such value or it can't be converted to {@code char}.
339      */
340     Character getCharAndRemove(K name);
341 
342     /**
343      * Returns the {@code char} value of a header with the specified {@code name} and removes the header from this
344      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
345      * In any case all values for {@code name} are removed.
346      * <p>
347      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
348      * be removed.
349      * @param name the name of the header to search
350      * @param defaultValue the default value
351      * @return the {@code char} value of the first value in insertion order or {@code defaultValue} if there is no
352      *         such value or it can't be converted to {@code char}.
353      */
354     char getCharAndRemove(K name, char defaultValue);
355 
356     /**
357      * Returns the {@code short} value of a header with the specified {@code name} and removes the header from this
358      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
359      * In any case all values for {@code name} are removed.
360      * <p>
361      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
362      * be removed.
363      * @param name the name of the header to search
364      * @return the {@code short} value of the first value in insertion order or {@code null} if there is no
365      *         such value or it can't be converted to {@code short}.
366      */
367     Short getShortAndRemove(K name);
368 
369     /**
370      * Returns the {@code short} value of a header with the specified {@code name} and removes the header from this
371      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
372      * In any case all values for {@code name} are removed.
373      * <p>
374      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
375      * be removed.
376      * @param name the name of the header to search
377      * @param defaultValue the default value
378      * @return the {@code short} value of the first value in insertion order or {@code defaultValue} if there is no
379      *         such value or it can't be converted to {@code short}.
380      */
381     short getShortAndRemove(K name, short defaultValue);
382 
383     /**
384      * Returns the {@code int} value of a header with the specified {@code name} and removes the header from this
385      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
386      * In any case all values for {@code name} are removed.
387      * <p>
388      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
389      * be removed.
390      * @param name the name of the header to search
391      * @return the {@code int} value of the first value in insertion order or {@code null} if there is no
392      *         such value or it can't be converted to {@code int}.
393      */
394     Integer getIntAndRemove(K name);
395 
396     /**
397      * Returns the {@code int} value of a header with the specified {@code name} and removes the header from this
398      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
399      * In any case all values for {@code name} are removed.
400      * <p>
401      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
402      * be removed.
403      * @param name the name of the header to search
404      * @param defaultValue the default value
405      * @return the {@code int} value of the first value in insertion order or {@code defaultValue} if there is no
406      *         such value or it can't be converted to {@code int}.
407      */
408     int getIntAndRemove(K name, int defaultValue);
409 
410     /**
411      * Returns the {@code long} value of a header with the specified {@code name} and removes the header from this
412      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
413      * In any case all values for {@code name} are removed.
414      * <p>
415      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
416      * be removed.
417      * @param name the name of the header to search
418      * @return the {@code long} value of the first value in insertion order or {@code null} if there is no
419      *         such value or it can't be converted to {@code long}.
420      */
421     Long getLongAndRemove(K name);
422 
423     /**
424      * Returns the {@code long} value of a header with the specified {@code name} and removes the header from this
425      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
426      * In any case all values for {@code name} are removed.
427      * <p>
428      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
429      * be removed.
430      * @param name the name of the header to search
431      * @param defaultValue the default value
432      * @return the {@code long} value of the first value in insertion order or {@code defaultValue} if there is no
433      *         such value or it can't be converted to {@code long}.
434      */
435     long getLongAndRemove(K name, long defaultValue);
436 
437     /**
438      * Returns the {@code float} value of a header with the specified {@code name} and removes the header from this
439      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
440      * In any case all values for {@code name} are removed.
441      * <p>
442      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
443      * be removed.
444      * @param name the name of the header to search
445      * @return the {@code float} value of the first value in insertion order or {@code null} if there is no
446      *         such value or it can't be converted to {@code float}.
447      */
448     Float getFloatAndRemove(K name);
449 
450     /**
451      * Returns the {@code float} value of a header with the specified {@code name} and removes the header from this
452      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
453      * In any case all values for {@code name} are removed.
454      * <p>
455      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
456      * be removed.
457      * @param name the name of the header to search
458      * @param defaultValue the default value
459      * @return the {@code float} value of the first value in insertion order or {@code defaultValue} if there is no
460      *         such value or it can't be converted to {@code float}.
461      */
462     float getFloatAndRemove(K name, float defaultValue);
463 
464     /**
465      * Returns the {@code double} value of a header with the specified {@code name} and removes the header from this
466      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
467      * In any case all values for {@code name} are removed.
468      * <p>
469      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
470      * be removed.
471      * @param name the name of the header to search
472      * @return the {@code double} value of the first value in insertion order or {@code null} if there is no
473      *         such value or it can't be converted to {@code double}.
474      */
475     Double getDoubleAndRemove(K name);
476 
477     /**
478      * Returns the {@code double} value of a header with the specified {@code name} and removes the header from this
479      * object. If there is more than one value for the specified name, the first value in insertion order is returned.
480      * In any case all values for {@code name} are removed.
481      * <p>
482      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
483      * be removed.
484      * @param name the name of the header to search
485      * @param defaultValue the default value
486      * @return the {@code double} value of the first value in insertion order or {@code defaultValue} if there is no
487      *         such value or it can't be converted to {@code double}.
488      */
489     double getDoubleAndRemove(K name, double defaultValue);
490 
491     /**
492      * Returns the value of a header with the specified {@code name} in milliseconds and removes the header from this
493      * object. If there is more than one value for the specified {@code name}, the first value in insertion order is
494      * returned. In any case all values for {@code name} are removed.
495      * <p>
496      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
497      * be removed.
498      * @param name the name of the header to retrieve
499      * @return the milliseconds value of the first value in insertion order or {@code null} if there is no such
500      *         value or it can't be converted to milliseconds.
501      */
502     Long getTimeMillisAndRemove(K name);
503 
504     /**
505      * Returns the value of a header with the specified {@code name} in milliseconds and removes the header from this
506      * object. If there is more than one value for the specified {@code name}, the first value in insertion order is
507      * returned. In any case all values for {@code name} are removed.
508      * <p>
509      * If an exception occurs during the translation from type {@code T} all entries with {@code name} may still
510      * be removed.
511      * @param name the name of the header to retrieve
512      * @param defaultValue the default value
513      * @return the milliseconds value of the first value in insertion order or {@code defaultValue} if there is no such
514      *         value or it can't be converted to milliseconds.
515      */
516     long getTimeMillisAndRemove(K name, long defaultValue);
517 
518     /**
519      * Returns {@code true} if a header with the {@code name} exists, {@code false} otherwise.
520      *
521      * @param name the header name
522      */
523     boolean contains(K name);
524 
525     /**
526      * Returns {@code true} if a header with the {@code name} and {@code value} exists, {@code false} otherwise.
527      * <p>
528      * The {@link Object#equals(Object)} method is used to test for equality of {@code value}.
529      * </p>
530      * @param name the header name
531      * @param value the header value of the header to find
532      */
533     boolean contains(K name, V value);
534 
535     /**
536      * Returns {@code true} if a header with the name and value exists.
537      *
538      * @param name the header name
539      * @param value the header value
540      * @return {@code true} if it contains it {@code false} otherwise
541      */
542     boolean containsObject(K name, Object value);
543 
544     /**
545      * Returns {@code true} if a header with the name and value exists.
546      *
547      * @param name the header name
548      * @param value the header value
549      * @return {@code true} if it contains it {@code false} otherwise
550      */
551     boolean containsBoolean(K name, boolean value);
552 
553     /**
554      * Returns {@code true} if a header with the name and value exists.
555      *
556      * @param name the header name
557      * @param value the header value
558      * @return {@code true} if it contains it {@code false} otherwise
559      */
560     boolean containsByte(K name, byte value);
561 
562     /**
563      * Returns {@code true} if a header with the name and value exists.
564      *
565      * @param name the header name
566      * @param value the header value
567      * @return {@code true} if it contains it {@code false} otherwise
568      */
569     boolean containsChar(K name, char value);
570 
571     /**
572      * Returns {@code true} if a header with the name and value exists.
573      *
574      * @param name the header name
575      * @param value the header value
576      * @return {@code true} if it contains it {@code false} otherwise
577      */
578     boolean containsShort(K name, short value);
579 
580     /**
581      * Returns {@code true} if a header with the name and value exists.
582      *
583      * @param name the header name
584      * @param value the header value
585      * @return {@code true} if it contains it {@code false} otherwise
586      */
587     boolean containsInt(K name, int value);
588 
589     /**
590      * Returns {@code true} if a header with the name and value exists.
591      *
592      * @param name the header name
593      * @param value the header value
594      * @return {@code true} if it contains it {@code false} otherwise
595      */
596     boolean containsLong(K name, long value);
597 
598     /**
599      * Returns {@code true} if a header with the name and value exists.
600      *
601      * @param name the header name
602      * @param value the header value
603      * @return {@code true} if it contains it {@code false} otherwise
604      */
605     boolean containsFloat(K name, float value);
606 
607     /**
608      * Returns {@code true} if a header with the name and value exists.
609      *
610      * @param name the header name
611      * @param value the header value
612      * @return {@code true} if it contains it {@code false} otherwise
613      */
614     boolean containsDouble(K name, double value);
615 
616     /**
617      * Returns {@code true} if a header with the name and value exists.
618      *
619      * @param name the header name
620      * @param value the header value
621      * @return {@code true} if it contains it {@code false} otherwise
622      */
623     boolean containsTimeMillis(K name, long value);
624 
625     /**
626      * Returns the number of headers in this object.
627      */
628     int size();
629 
630     /**
631      * Returns {@code true} if {@link #size()} equals {@code 0}.
632      */
633     boolean isEmpty();
634 
635     /**
636      * Returns a {@link Set} of all header names in this object. The returned {@link Set} cannot be modified.
637      */
638     Set<K> names();
639 
640     /**
641      * Adds a new header with the specified {@code name} and {@code value}.
642      *
643      * @param name the name of the header
644      * @param value the value of the header
645      * @return {@code this}
646      */
647     T add(K name, V value);
648 
649     /**
650      * Adds new headers with the specified {@code name} and {@code values}. This method is semantically equivalent to
651      *
652      * <pre>
653      * for (T value : values) {
654      *     headers.add(name, value);
655      * }
656      * </pre>
657      *
658      * @param name the header name
659      * @param values the values of the header
660      * @return {@code this}
661      */
662     T add(K name, Iterable<? extends V> values);
663 
664     /**
665      * Adds new headers with the specified {@code name} and {@code values}. This method is semantically equivalent to
666      *
667      * <pre>
668      * for (T value : values) {
669      *     headers.add(name, value);
670      * }
671      * </pre>
672      *
673      * @param name the header name
674      * @param values the values of the header
675      * @return {@code this}
676      */
677     T add(K name, V... values);
678 
679     /**
680      * Adds a new header. Before the {@code value} is added, it's converted to type {@code T}.
681      *
682      * @param name the header name
683      * @param value the value of the header
684      * @return {@code this}
685      */
686     T addObject(K name, Object value);
687 
688     /**
689      * Adds a new header with the specified name and values. This method is equivalent to
690      *
691      * <pre>
692      * for (Object v : values) {
693      *     headers.addObject(name, v);
694      * }
695      * </pre>
696      *
697      * @param name the header name
698      * @param values the value of the header
699      * @return {@code this}
700      */
701     T addObject(K name, Iterable<?> values);
702 
703     /**
704      * Adds a new header with the specified name and values. This method is equivalent to
705      *
706      * <pre>
707      * for (Object v : values) {
708      *     headers.addObject(name, v);
709      * }
710      * </pre>
711      *
712      * @param name the header name
713      * @param values the value of the header
714      * @return {@code this}
715      */
716     T addObject(K name, Object... values);
717 
718     /**
719      * Adds a new header.
720      *
721      * @param name the header name
722      * @param value the value of the header
723      * @return {@code this}
724      */
725     T addBoolean(K name, boolean value);
726 
727     /**
728      * Adds a new header.
729      *
730      * @param name the header name
731      * @param value the value of the header
732      * @return {@code this}
733      */
734     T addByte(K name, byte value);
735 
736     /**
737      * Adds a new header.
738      *
739      * @param name the header name
740      * @param value the value of the header
741      * @return {@code this}
742      */
743     T addChar(K name, char value);
744 
745     /**
746      * Adds a new header.
747      *
748      * @param name the header name
749      * @param value the value of the header
750      * @return {@code this}
751      */
752     T addShort(K name, short value);
753 
754     /**
755      * Adds a new header.
756      *
757      * @param name the header name
758      * @param value the value of the header
759      * @return {@code this}
760      */
761     T addInt(K name, int value);
762 
763     /**
764      * Adds a new header.
765      *
766      * @param name the header name
767      * @param value the value of the header
768      * @return {@code this}
769      */
770     T addLong(K name, long value);
771 
772     /**
773      * Adds a new header.
774      *
775      * @param name the header name
776      * @param value the value of the header
777      * @return {@code this}
778      */
779     T addFloat(K name, float value);
780 
781     /**
782      * Adds a new header.
783      *
784      * @param name the header name
785      * @param value the value of the header
786      * @return {@code this}
787      */
788     T addDouble(K name, double value);
789 
790     /**
791      * Adds a new header.
792      *
793      * @param name the header name
794      * @param value the value of the header
795      * @return {@code this}
796      */
797     T addTimeMillis(K name, long value);
798 
799     /**
800      * Adds all header names and values of {@code headers} to this object.
801      *
802      * @throws IllegalArgumentException if {@code headers == this}.
803      * @return {@code this}
804      */
805     T add(Headers<? extends K, ? extends V, ?> headers);
806 
807     /**
808      * Sets a header with the specified name and value. Any existing headers with the same name are overwritten.
809      *
810      * @param name the header name
811      * @param value the value of the header
812      * @return {@code this}
813      */
814     T set(K name, V value);
815 
816     /**
817      * Sets a new header with the specified name and values. This method is equivalent to
818      *
819      * <pre>
820      * for (T v : values) {
821      *     headers.addObject(name, v);
822      * }
823      * </pre>
824      *
825      * @param name the header name
826      * @param values the value of the header
827      * @return {@code this}
828      */
829     T set(K name, Iterable<? extends V> values);
830 
831     /**
832      * Sets a header with the specified name and values. Any existing headers with this name are removed. This method
833      * is equivalent to:
834      *
835      * <pre>
836      * headers.remove(name);
837      * for (T v : values) {
838      *     headers.add(name, v);
839      * }
840      * </pre>
841      *
842      * @param name the header name
843      * @param values the value of the header
844      * @return {@code this}
845      */
846     T set(K name, V... values);
847 
848     /**
849      * Sets a new header. Any existing headers with this name are removed. Before the {@code value} is add, it's
850      * converted to type {@code T}.
851      *
852      * @param name the header name
853      * @param value the value of the header
854      * @throws NullPointerException if either {@code name} or {@code value} before or after its conversion is
855      *                              {@code null}.
856      * @return {@code this}
857      */
858     T setObject(K name, Object value);
859 
860     /**
861      * Sets a header with the specified name and values. Any existing headers with this name are removed. This method
862      * is equivalent to:
863      *
864      * <pre>
865      * headers.remove(name);
866      * for (Object v : values) {
867      *     headers.addObject(name, v);
868      * }
869      * </pre>
870      *
871      * @param name the header name
872      * @param values the values of the header
873      * @return {@code this}
874      */
875     T setObject(K name, Iterable<?> values);
876 
877     /**
878      * Sets a header with the specified name and values. Any existing headers with this name are removed. This method
879      * is equivalent to:
880      *
881      * <pre>
882      * headers.remove(name);
883      * for (Object v : values) {
884      *     headers.addObject(name, v);
885      * }
886      * </pre>
887      *
888      * @param name the header name
889      * @param values the values of the header
890      * @return {@code this}
891      */
892     T setObject(K name, Object... values);
893 
894     /**
895      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
896      * @param name The name to modify
897      * @param value The value
898      * @return {@code this}
899      */
900     T setBoolean(K name, boolean value);
901 
902     /**
903      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
904      * @param name The name to modify
905      * @param value The value
906      * @return {@code this}
907      */
908     T setByte(K name, byte value);
909 
910     /**
911      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
912      * @param name The name to modify
913      * @param value The value
914      * @return {@code this}
915      */
916     T setChar(K name, char value);
917 
918     /**
919      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
920      * @param name The name to modify
921      * @param value The value
922      * @return {@code this}
923      */
924     T setShort(K name, short value);
925 
926     /**
927      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
928      * @param name The name to modify
929      * @param value The value
930      * @return {@code this}
931      */
932     T setInt(K name, int value);
933 
934     /**
935      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
936      * @param name The name to modify
937      * @param value The value
938      * @return {@code this}
939      */
940     T setLong(K name, long value);
941 
942     /**
943      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
944      * @param name The name to modify
945      * @param value The value
946      * @return {@code this}
947      */
948     T setFloat(K name, float value);
949 
950     /**
951      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
952      * @param name The name to modify
953      * @param value The value
954      * @return {@code this}
955      */
956     T setDouble(K name, double value);
957 
958     /**
959      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
960      * @param name The name to modify
961      * @param value The value
962      * @return {@code this}
963      */
964     T setTimeMillis(K name, long value);
965 
966     /**
967      * Clears the current header entries and copies all header entries of the specified {@code headers}.
968      *
969      * @return {@code this}
970      */
971     T set(Headers<? extends K, ? extends V, ?> headers);
972 
973     /**
974      * Retains all current headers but calls {@link #set(K, V)} for each entry in {@code headers}.
975      *
976      * @param headers The headers used to {@link #set(K, V)} values in this instance
977      * @return {@code this}
978      */
979     T setAll(Headers<? extends K, ? extends V, ?> headers);
980 
981     /**
982      * Removes all headers with the specified {@code name}.
983      *
984      * @param name the header name
985      * @return {@code true} if at least one entry has been removed.
986      */
987     boolean remove(K name);
988 
989     /**
990      * Removes all headers. After a call to this method {@link #size()} equals {@code 0}.
991      *
992      * @return {@code this}
993      */
994     T clear();
995 
996     @Override
997     Iterator<Entry<K, V>> iterator();
998 }