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    * http://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.netty.handler.codec;
16  
17  import java.util.Comparator;
18  import java.util.Iterator;
19  import java.util.List;
20  import java.util.Map;
21  import java.util.Map.Entry;
22  import java.util.Set;
23  
24  public interface Headers<T> extends Iterable<Map.Entry<T, T>> {
25      /**
26       * A visitor that helps reduce GC pressure while iterating over a collection of {@link Headers}.
27       */
28      interface EntryVisitor<T> {
29          /**
30           * @return <ul>
31           *         <li>{@code true} if the processor wants to continue the loop and handle the entry.</li>
32           *         <li>{@code false} if the processor wants to stop handling headers and abort the loop.</li>
33           *         </ul>
34           */
35          boolean visit(Map.Entry<T, T> entry) throws Exception;
36      }
37  
38      /**
39       * A visitor that helps reduce GC pressure while iterating over a collection of {@link Headers}.
40       */
41      interface NameVisitor<T> {
42          /**
43           * @return <ul>
44           *         <li>{@code true} if the processor wants to continue the loop and handle the entry.</li>
45           *         <li>{@code false} if the processor wants to stop handling headers and abort the loop.</li>
46           *         </ul>
47           */
48          boolean visit(T name) throws Exception;
49      }
50  
51      /**
52       * Converts to/from a generic object to the type of the name for this map
53       */
54      interface ValueConverter<T> {
55          T convertObject(Object value);
56  
57          T convertBoolean(boolean value);
58  
59          boolean convertToBoolean(T value);
60  
61          T convertByte(byte value);
62  
63          byte convertToByte(T value);
64  
65          T convertChar(char value);
66  
67          char convertToChar(T value);
68  
69          T convertShort(short value);
70  
71          short convertToShort(T value);
72  
73          T convertInt(int value);
74  
75          int convertToInt(T value);
76  
77          T convertLong(long value);
78  
79          long convertToLong(T value);
80  
81          T convertTimeMillis(long value);
82  
83          long convertToTimeMillis(T value);
84  
85          T convertFloat(float value);
86  
87          float convertToFloat(T value);
88  
89          T convertDouble(double value);
90  
91          double convertToDouble(T value);
92      }
93  
94      /**
95       * Returns the value of a header with the specified name. If there are more than one values for the specified name,
96       * the first value is returned.
97       *
98       * @param name the name of the header to search
99       * @return the first header value if the header is found. {@code null} if there's no such header.
100      */
101     T get(T name);
102 
103     /**
104      * Returns the value of a header with the specified name. If there are more than one values for the specified name,
105      * the first value is returned.
106      *
107      * @param name the name of the header to search
108      * @param defaultValue the default value
109      * @return the first header value if the header is found. {@code defaultValue} if there's no such header.
110      */
111     T get(T name, T defaultValue);
112 
113     /**
114      * Returns and removes the value of a header with the specified name. If there are more than one values for the
115      * specified name, the first value is returned.
116      *
117      * @param name the name of the header to search
118      * @return the first header value or {@code null} if there is no such header
119      */
120     T getAndRemove(T name);
121 
122     /**
123      * Returns and removes the value of a header with the specified name. If there are more than one values for the
124      * specified name, the first value is returned.
125      *
126      * @param name the name of the header to search
127      * @param defaultValue the default value
128      * @return the first header value or {@code defaultValue} if there is no such header
129      */
130     T getAndRemove(T name, T defaultValue);
131 
132     /**
133      * Returns the values of headers with the specified name
134      *
135      * @param name The name of the headers to search
136      * @return A {@link List} of header values which will be empty if no values are found
137      */
138     List<T> getAll(T name);
139 
140     /**
141      * Returns and Removes the values of headers with the specified name
142      *
143      * @param name The name of the headers to search
144      * @return A {@link List} of header values which will be empty if no values are found
145      */
146     List<T> getAllAndRemove(T name);
147 
148     /**
149      * Returns the boolean value of a header with the specified name. If there are more than one values for the
150      * specified name, the first value is returned.
151      *
152      * @param name the name of the header to search
153      * @return the first header value if the header is found and its value is a boolean. {@code null} if there's no such
154      *         header or its value is not a boolean.
155      */
156     Boolean getBoolean(T name);
157 
158     /**
159      * Returns the boolean value of a header with the specified name. If there are more than one values for the
160      * specified name, the first value is returned.
161      *
162      * @param name the name of the header to search
163      * @param defaultValue the default value
164      * @return the first header value if the header is found and its value is a boolean. {@code defaultValue} if there's
165      *         no such header or its value is not a boolean.
166      */
167     boolean getBoolean(T name, boolean defaultValue);
168 
169     /**
170      * Returns the byte value of a header with the specified name. If there are more than one values for the specified
171      * name, the first value is returned.
172      *
173      * @param name the name of the header to search
174      * @return the first header value if the header is found and its value is a byte. {@code null} if there's no such
175      *         header or its value is not a byte.
176      */
177     Byte getByte(T name);
178 
179     /**
180      * Returns the byte value of a header with the specified name. If there are more than one values for the specified
181      * name, the first value is returned.
182      *
183      * @param name the name of the header to search
184      * @param defaultValue the default value
185      * @return the first header value if the header is found and its value is a byte. {@code defaultValue} if there's no
186      *         such header or its value is not a byte.
187      */
188     byte getByte(T name, byte defaultValue);
189 
190     /**
191      * Returns the char value of a header with the specified name. If there are more than one values for the specified
192      * name, the first value is returned.
193      *
194      * @param name the name of the header to search
195      * @return the first header value if the header is found and its value is a char. {@code null} if there's no such
196      *         header or its value is not a char.
197      */
198     Character getChar(T name);
199 
200     /**
201      * Returns the char value of a header with the specified name. If there are more than one values for the specified
202      * name, the first value is returned.
203      *
204      * @param name the name of the header to search
205      * @param defaultValue the default value
206      * @return the first header value if the header is found and its value is a char. {@code defaultValue} if there's no
207      *         such header or its value is not a char.
208      */
209     char getChar(T name, char defaultValue);
210 
211     /**
212      * Returns the short value of a header with the specified name. If there are more than one values for the specified
213      * name, the first value is returned.
214      *
215      * @param name the name of the header to search
216      * @return the first header value if the header is found and its value is a short. {@code null} if there's no such
217      *         header or its value is not a short.
218      */
219     Short getShort(T name);
220 
221     /**
222      * Returns the short value of a header with the specified name. If there are more than one values for the specified
223      * name, the first value is returned.
224      *
225      * @param name the name of the header to search
226      * @param defaultValue the default value
227      * @return the first header value if the header is found and its value is a short. {@code defaultValue} if there's
228      *         no such header or its value is not a short.
229      */
230     short getInt(T name, short defaultValue);
231 
232     /**
233      * Returns the integer value of a header with the specified name. If there are more than one values for the
234      * specified name, the first value is returned.
235      *
236      * @param name the name of the header to search
237      * @return the first header value if the header is found and its value is an integer. {@code null} if there's no
238      *         such header or its value is not an integer.
239      */
240     Integer getInt(T name);
241 
242     /**
243      * Returns the integer value of a header with the specified name. If there are more than one values for the
244      * specified name, the first value is returned.
245      *
246      * @param name the name of the header to search
247      * @param defaultValue the default value
248      * @return the first header value if the header is found and its value is an integer. {@code defaultValue} if
249      *         there's no such header or its value is not an integer.
250      */
251     int getInt(T name, int defaultValue);
252 
253     /**
254      * Returns the long value of a header with the specified name. If there are more than one values for the specified
255      * name, the first value is returned.
256      *
257      * @param name the name of the header to search
258      * @return the first header value if the header is found and its value is a long. {@code null} if there's no such
259      *         header or its value is not a long.
260      */
261     Long getLong(T name);
262 
263     /**
264      * Returns the long value of a header with the specified name. If there are more than one values for the specified
265      * name, the first value is returned.
266      *
267      * @param name the name of the header to search
268      * @param defaultValue the default value
269      * @return the first header value if the header is found and its value is a long. {@code defaultValue} if there's no
270      *         such header or its value is not a long.
271      */
272     long getLong(T name, long defaultValue);
273 
274     /**
275      * Returns the float value of a header with the specified name. If there are more than one values for the specified
276      * name, the first value is returned.
277      *
278      * @param name the name of the header to search
279      * @return the first header value if the header is found and its value is a float. {@code null} if there's no such
280      *         header or its value is not a float.
281      */
282     Float getFloat(T name);
283 
284     /**
285      * Returns the float value of a header with the specified name. If there are more than one values for the specified
286      * name, the first value is returned.
287      *
288      * @param name the name of the header to search
289      * @param defaultValue the default value
290      * @return the first header value if the header is found and its value is a float. {@code defaultValue} if there's
291      *         no such header or its value is not a float.
292      */
293     float getFloat(T name, float defaultValue);
294 
295     /**
296      * Returns the double value of a header with the specified name. If there are more than one values for the specified
297      * name, the first value is returned.
298      *
299      * @param name the name of the header to search
300      * @return the first header value if the header is found and its value is a double. {@code null} if there's no such
301      *         header or its value is not a double.
302      */
303     Double getDouble(T name);
304 
305     /**
306      * Returns the double value of a header with the specified name. If there are more than one values for the specified
307      * name, the first value is returned.
308      *
309      * @param name the name of the header to search
310      * @param defaultValue the default value
311      * @return the first header value if the header is found and its value is a double. {@code defaultValue} if there's
312      *         no such header or its value is not a double.
313      */
314     double getDouble(T name, double defaultValue);
315 
316     /**
317      * Returns the date value of a header with the specified name as milliseconds. If there are more than one values for
318      * the specified name, the first value is returned.
319      *
320      * @param name The name of the header to search
321      * @return the first header value in milliseconds if the header is found and its value is a date. {@code null} if
322      *         there's no such header or its value is not a date.
323      */
324     Long getTimeMillis(T name);
325 
326     /**
327      * Returns the date value of a header with the specified name as milliseconds. If there are more than one values for
328      * the specified name, the first value is returned.
329      *
330      * @param name The name of the header to search
331      * @param defaultValue default value
332      * @return the first header value in milliseconds if the header is found and its value is a date.
333      *         {@code defaultValue} if there's no such header or its value is not a date.
334      */
335     long getTimeMillis(T name, long defaultValue);
336 
337     /**
338      * Returns and removes the boolean value of a header with the specified name. If there are more than one values for
339      * the specified name, the first value is returned.
340      *
341      * @param name the name of the header to search
342      * @return the first header value if the header is found and its value is a boolean. {@code null} if there's no such
343      *         header or its value is not a boolean.
344      */
345     Boolean getBooleanAndRemove(T name);
346 
347     /**
348      * Returns and removes the boolean value of a header with the specified name. If there are more than one values for
349      * the specified name, the first value is returned.
350      *
351      * @param name the name of the header to search
352      * @param defaultValue the default value
353      * @return the first header value if the header is found and its value is a boolean. {@code defaultValue} if there
354      *         is no such header or its value of header is not a boolean.
355      */
356     boolean getBooleanAndRemove(T name, boolean defaultValue);
357 
358     /**
359      * Returns and removes the byte value of a header with the specified name. If there are more than one values for the
360      * specified name, the first value is returned.
361      *
362      * @param name the name of the header to search
363      * @return the first header value if the header is found and its value is a byte. {@code null} if there's no such
364      *         header or its value is not a byte.
365      */
366     Byte getByteAndRemove(T name);
367 
368     /**
369      * Returns and removes the byte value of a header with the specified name. If there are more than one values for the
370      * specified name, the first value is returned.
371      *
372      * @param name the name of the header to search
373      * @param defaultValue the default value
374      * @return the first header value if the header is found and its value is a byte. {@code defaultValue} if there is
375      *         no such header or its value of header is not a byte.
376      */
377     byte getByteAndRemove(T name, byte defaultValue);
378 
379     /**
380      * Returns and removes the char value of a header with the specified name. If there are more than one values for the
381      * specified name, the first value is returned.
382      *
383      * @param name the name of the header to search
384      * @return the first header value if the header is found and its value is a char. {@code null} if there's no such
385      *         header or its value is not a char.
386      */
387     Character getCharAndRemove(T name);
388 
389     /**
390      * Returns and removes the char value of a header with the specified name. If there are more than one values for the
391      * specified name, the first value is returned.
392      *
393      * @param name the name of the header to search
394      * @param defaultValue the default value
395      * @return the first header value if the header is found and its value is a char. {@code defaultValue} if there is
396      *         no such header or its value of header is not a char.
397      */
398     char getCharAndRemove(T name, char defaultValue);
399 
400     /**
401      * Returns and removes the short value of a header with the specified name. If there are more than one values for
402      * the specified name, the first value is returned.
403      *
404      * @param name the name of the header to search
405      * @return the first header value if the header is found and its value is a short. {@code null} if there's no such
406      *         header or its value is not a short.
407      */
408     Short getShortAndRemove(T name);
409 
410     /**
411      * Returns and removes the short value of a header with the specified name. If there are more than one values for
412      * the specified name, the first value is returned.
413      *
414      * @param name the name of the header to search
415      * @param defaultValue the default value
416      * @return the first header value if the header is found and its value is a short. {@code defaultValue} if there is
417      *         no such header or its value of header is not a short.
418      */
419     short getShortAndRemove(T name, short defaultValue);
420 
421     /**
422      * Returns and removes the integer value of a header with the specified name. If there are more than one values for
423      * the specified name, the first value is returned.
424      *
425      * @param name the name of the header to search
426      * @return the first header value if the header is found and its value is an integer. {@code null} if there's no
427      *         such header or its value is not an integer.
428      */
429     Integer getIntAndRemove(T name);
430 
431     /**
432      * Returns and removes the integer value of a header with the specified name. If there are more than one values for
433      * the specified name, the first value is returned.
434      *
435      * @param name the name of the header to search
436      * @param defaultValue the default value
437      * @return the first header value if the header is found and its value is an integer. {@code defaultValue} if there
438      *         is no such header or its value of header is not an integer.
439      */
440     int getIntAndRemove(T name, int defaultValue);
441 
442     /**
443      * Returns and removes the long value of a header with the specified name. If there are more than one values for the
444      * specified name, the first value is returned.
445      *
446      * @param name the name of the header to search
447      * @return the first header value if the header is found and its value is a long. {@code null} if there's no such
448      *         header or its value is not a long.
449      */
450     Long getLongAndRemove(T name);
451 
452     /**
453      * Returns and removes the long value of a header with the specified name. If there are more than one values for the
454      * specified name, the first value is returned.
455      *
456      * @param name the name of the header to search
457      * @param defaultValue the default value
458      * @return the first header value if the header is found and its value is a long. {@code defaultValue} if there's no
459      *         such header or its value is not a long.
460      */
461     long getLongAndRemove(T name, long defaultValue);
462 
463     /**
464      * Returns and removes the float value of a header with the specified name. If there are more than one values for
465      * the specified name, the first value is returned.
466      *
467      * @param name the name of the header to search
468      * @return the first header value if the header is found and its value is a float. {@code null} if there's no such
469      *         header or its value is not a float.
470      */
471     Float getFloatAndRemove(T name);
472 
473     /**
474      * Returns and removes the float value of a header with the specified name. If there are more than one values for
475      * the specified name, the first value is returned.
476      *
477      * @param name the name of the header to search
478      * @param defaultValue the default value
479      * @return the first header value if the header is found and its value is a float. {@code defaultValue} if there's
480      *         no such header or its value is not a float.
481      */
482     float getFloatAndRemove(T name, float defaultValue);
483 
484     /**
485      * Returns and removes the double value of a header with the specified name. If there are more than one values for
486      * the specified name, the first value is returned.
487      *
488      * @param name the name of the header to search
489      * @return the first header value if the header is found and its value is a double. {@code null} if there's no such
490      *         header or its value is not a double.
491      */
492     Double getDoubleAndRemove(T name);
493 
494     /**
495      * Returns and removes the double value of a header with the specified name. If there are more than one values for
496      * the specified name, the first value is returned.
497      *
498      * @param name the name of the header to search
499      * @param defaultValue the default value
500      * @return the first header value if the header is found and its value is a double. {@code defaultValue} if there's
501      *         no such header or its value is not a double.
502      */
503     double getDoubleAndRemove(T name, double defaultValue);
504 
505     /**
506      * Returns and removes the date value of a header with the specified name as milliseconds. If there are more than
507      * one values for the specified name, the first value is returned.
508      *
509      * @param name The name of the header to search
510      * @return the first header value in milliseconds if the header is found and its value is a date. {@code null} if
511      *         there's no such header or its value is not a date.
512      */
513     Long getTimeMillisAndRemove(T name);
514 
515     /**
516      * Returns and removes the date value of a header with the specified name as milliseconds. If there are more than
517      * one values for the specified name, the first value is returned.
518      *
519      * @param name The name of the header to search
520      * @param defaultValue default value
521      * @return the first header value in milliseconds if the header is found and its value is a date.
522      *         {@code defaultValue} if there's no such header or its value is not a date.
523      */
524     long getTimeMillisAndRemove(T name, long defaultValue);
525 
526     /**
527      * Returns a new {@link List} that contains all headers in this object. Note that modifying the returned
528      * {@link List} will not affect the state of this object. If you intend to enumerate over the header entries only,
529      * use {@link #iterator()} instead, which has much less overhead.
530      */
531     List<Entry<T, T>> entries();
532 
533     /**
534      * Returns {@code true} if and only if this collection contains the header with the specified name.
535      *
536      * @param name The name of the header to search for
537      * @return {@code true} if at least one header is found
538      */
539     boolean contains(T name);
540 
541     /**
542      * Returns {@code true} if a header with the name and value exists.
543      *
544      * @param name the header name
545      * @param value the header value
546      * @return {@code true} if it contains it {@code false} otherwise
547      */
548     boolean contains(T name, T value);
549 
550     /**
551      * Returns {@code true} if a header with the name and value exists.
552      *
553      * @param name the header name
554      * @param value the header value
555      * @return {@code true} if it contains it {@code false} otherwise
556      */
557     boolean containsObject(T name, Object value);
558 
559     /**
560      * Returns {@code true} if a header with the name and value exists.
561      *
562      * @param name the header name
563      * @param value the header value
564      * @return {@code true} if it contains it {@code false} otherwise
565      */
566     boolean containsBoolean(T name, boolean value);
567 
568     /**
569      * Returns {@code true} if a header with the name and value exists.
570      *
571      * @param name the header name
572      * @param value the header value
573      * @return {@code true} if it contains it {@code false} otherwise
574      */
575     boolean containsByte(T name, byte value);
576 
577     /**
578      * Returns {@code true} if a header with the name and value exists.
579      *
580      * @param name the header name
581      * @param value the header value
582      * @return {@code true} if it contains it {@code false} otherwise
583      */
584     boolean containsChar(T name, char value);
585 
586     /**
587      * Returns {@code true} if a header with the name and value exists.
588      *
589      * @param name the header name
590      * @param value the header value
591      * @return {@code true} if it contains it {@code false} otherwise
592      */
593     boolean containsShort(T name, short value);
594 
595     /**
596      * Returns {@code true} if a header with the name and value exists.
597      *
598      * @param name the header name
599      * @param value the header value
600      * @return {@code true} if it contains it {@code false} otherwise
601      */
602     boolean containsInt(T name, int value);
603 
604     /**
605      * Returns {@code true} if a header with the name and value exists.
606      *
607      * @param name the header name
608      * @param value the header value
609      * @return {@code true} if it contains it {@code false} otherwise
610      */
611     boolean containsLong(T name, long value);
612 
613     /**
614      * Returns {@code true} if a header with the name and value exists.
615      *
616      * @param name the header name
617      * @param value the header value
618      * @return {@code true} if it contains it {@code false} otherwise
619      */
620     boolean containsFloat(T name, float value);
621 
622     /**
623      * Returns {@code true} if a header with the name and value exists.
624      *
625      * @param name the header name
626      * @param value the header value
627      * @return {@code true} if it contains it {@code false} otherwise
628      */
629     boolean containsDouble(T name, double value);
630 
631     /**
632      * Returns {@code true} if a header with the name and value exists.
633      *
634      * @param name the header name
635      * @param value the header value
636      * @return {@code true} if it contains it {@code false} otherwise
637      */
638     boolean containsTimeMillis(T name, long value);
639 
640     /**
641      * Returns {@code true} if a header with the name and value exists.
642      *
643      * @param name the header name
644      * @param value the header value
645      * @param comparator The comparator to use when comparing {@code name} and {@code value} to entries in this map
646      * @return {@code true} if it contains it {@code false} otherwise
647      */
648     boolean contains(T name, T value, Comparator<? super T> comparator);
649 
650     /**
651      * Returns {@code true} if a header with the name and value exists.
652      *
653      * @param name the header name
654      * @param value the header value
655      * @param keyComparator The comparator to use when comparing {@code name} to names in this map
656      * @param valueComparator The comparator to use when comparing {@code value} to values in this map
657      * @return {@code true} if it contains it {@code false} otherwise
658      */
659     boolean contains(T name, T value, Comparator<? super T> keyComparator, Comparator<? super T> valueComparator);
660 
661     /**
662      * Returns {@code true} if a header with the name and value exists.
663      *
664      * @param name the header name
665      * @param value the header value
666      * @param comparator The comparator to use when comparing {@code name} and {@code value} to entries in this map
667      * @return {@code true} if it contains it {@code false} otherwise
668      */
669     boolean containsObject(T name, Object value, Comparator<? super T> comparator);
670 
671     /**
672      * Returns {@code true} if a header with the name and value exists.
673      *
674      * @param name the header name
675      * @param value the header value
676      * @param keyComparator The comparator to use when comparing {@code name} to names in this map
677      * @param valueComparator The comparator to use when comparing {@code value} to values in this map
678      * @return {@code true} if it contains it {@code false} otherwise
679      */
680     boolean containsObject(T name, Object value, Comparator<? super T> keyComparator,
681             Comparator<? super T> valueComparator);
682 
683     /**
684      * Returns the number of header entries in this collection.
685      */
686     int size();
687 
688     /**
689      * Returns {@code true} if and only if this collection contains no header entries.
690      */
691     boolean isEmpty();
692 
693     /**
694      * Returns a new {@link Set} that contains the names of all headers in this object. Note that modifying the returned
695      * {@link Set} will not affect the state of this object. If you intend to enumerate over the header entries only,
696      * use {@link #iterator()} instead, which has much less overhead.
697      */
698     Set<T> names();
699 
700     /**
701      * Returns a new {@link List} that contains the names of all headers in this object. Note that modifying the
702      * returned {@link List} will not affect the state of this object. If you intend to enumerate over the header
703      * entries only, use {@link #iterator()} instead, which has much less overhead.
704      */
705     List<T> namesList();
706 
707     /**
708      * Adds a new header with the specified name and value. If the specified value is not a {@link String}, it is
709      * converted into a {@link String} by {@link Object#toString()}, except in the cases of {@link java.util.Date} and
710      * {@link java.util.Calendar}, which are formatted to the date format defined in <a
711      * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>.
712      *
713      * @param name the name of the header being added
714      * @param value the value of the header being added
715      * @return {@code this}
716      */
717     Headers<T> add(T name, T value);
718 
719     /**
720      * Adds a new header with the specified name and values. This getMethod can be represented approximately as the
721      * following code:
722      *
723      * <pre>
724      * for (Object v : values) {
725      *     if (v == null) {
726      *         break;
727      *     }
728      *     headers.add(name, v);
729      * }
730      * </pre>
731      *
732      * @param name the name of the headepublic abstract rs being set
733      * @param values the values of the headers being set
734      * @return {@code this}
735      */
736     Headers<T> add(T name, Iterable<? extends T> values);
737 
738     /**
739      * Adds a new header with the specified name and values. This getMethod can be represented approximately as the
740      * following code:
741      *
742      * <pre>
743      * for (Object v : values) {
744      *     if (v == null) {
745      *         break;
746      *     }
747      *     headers.add(name, v);
748      * }
749      * </pre>
750      *
751      * @param name the name of the headepublic abstract rs being set
752      * @param values the values of the headers being set
753      * @return {@code this}
754      */
755     Headers<T> add(T name, T... values);
756 
757     /**
758      * Adds a new header with the specified name and value. If the specified value is not a {@link String}, it is
759      * converted into a {@link String} by {@link Object#toString()}, except in the cases of {@link java.util.Date} and
760      * {@link java.util.Calendar}, which are formatted to the date format defined in <a
761      * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>.
762      *
763      * @param name the name of the header being added
764      * @param value the value of the header being added
765      * @return {@code this}
766      */
767     Headers<T> addObject(T name, Object value);
768 
769     /**
770      * Adds a new header with the specified name and values. This getMethod can be represented approximately as the
771      * following code:
772      *
773      * <pre>
774      * for (Object v : values) {
775      *     if (v == null) {
776      *         break;
777      *     }
778      *     headers.add(name, v);
779      * }
780      * </pre>
781      *
782      * @param name the name of the headepublic abstract rs being set
783      * @param values the values of the headers being set
784      * @return {@code this}
785      */
786     Headers<T> addObject(T name, Iterable<?> values);
787 
788     /**
789      * Adds a new header with the specified name and values. This getMethod can be represented approximately as the
790      * following code:
791      *
792      * <pre>
793      * for (Object v : values) {
794      *     if (v == null) {
795      *         break;
796      *     }
797      *     headers.add(name, v);
798      * }
799      * </pre>
800      *
801      * @param name the name of the headepublic abstract rs being set
802      * @param values the values of the headers being set
803      * @return {@code this}
804      */
805     Headers<T> addObject(T name, Object... values);
806 
807     /**
808      * Add the {@code name} to {@code value}.
809      * @param name The name to modify
810      * @param value The value
811      * @return {@code this}
812      */
813     Headers<T> addBoolean(T name, boolean value);
814 
815     /**
816      * Add the {@code name} to {@code value}.
817      * @param name The name to modify
818      * @param value The value
819      * @return {@code this}
820      */
821     Headers<T> addByte(T name, byte value);
822 
823     /**
824      * Add the {@code name} to {@code value}.
825      * @param name The name to modify
826      * @param value The value
827      * @return {@code this}
828      */
829     Headers<T> addChar(T name, char value);
830 
831     /**
832      * Add the {@code name} to {@code value}.
833      * @param name The name to modify
834      * @param value The value
835      * @return {@code this}
836      */
837     Headers<T> addShort(T name, short value);
838 
839     /**
840      * Add the {@code name} to {@code value}.
841      * @param name The name to modify
842      * @param value The value
843      * @return {@code this}
844      */
845     Headers<T> addInt(T name, int value);
846 
847     /**
848      * Add the {@code name} to {@code value}.
849      * @param name The name to modify
850      * @param value The value
851      * @return {@code this}
852      */
853     Headers<T> addLong(T name, long value);
854 
855     /**
856      * Add the {@code name} to {@code value}.
857      * @param name The name to modify
858      * @param value The value
859      * @return {@code this}
860      */
861     Headers<T> addFloat(T name, float value);
862 
863     /**
864      * Add the {@code name} to {@code value}.
865      * @param name The name to modify
866      * @param value The value
867      * @return {@code this}
868      */
869     Headers<T> addDouble(T name, double value);
870 
871     /**
872      * Add the {@code name} to {@code value}.
873      * @param name The name to modify
874      * @param value The value
875      * @return {@code this}
876      */
877     Headers<T> addTimeMillis(T name, long value);
878 
879     /**
880      * Adds all header entries of the specified {@code headers}.
881      *
882      * @return {@code this}
883      */
884     Headers<T> add(Headers<T> headers);
885 
886     /**
887      * Sets a header with the specified name and value. If there is an existing header with the same name, it is
888      * removed. If the specified value is not a {@link String}, it is converted into a {@link String} by
889      * {@link Object#toString()}, except for {@link java.util.Date} and {@link java.util.Calendar}, which are formatted
890      * to the date format defined in <a
891      * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>.
892      *
893      * @param name The name of the header being set
894      * @param value The value of the header being set
895      * @return {@code this}
896      */
897     Headers<T> set(T name, T value);
898 
899     /**
900      * Sets a header with the specified name and values. If there is an existing header with the same name, it is
901      * removed. This getMethod can be represented approximately as the following code:
902      *
903      * <pre>
904      * headers.remove(name);
905      * for (Object v : values) {
906      *     if (v == null) {
907      *         break;
908      *     }
909      *     headers.add(name, v);
910      * }
911      * </pre>
912      *
913      * @param name the name of the headers being set
914      * @param values the values of the headers being set
915      * @return {@code this}
916      */
917     Headers<T> set(T name, Iterable<? extends T> values);
918 
919     /**
920      * Sets a header with the specified name and values. If there is an existing header with the same name, it is
921      * removed. This getMethod can be represented approximately as the following code:
922      *
923      * <pre>
924      * headers.remove(name);
925      * for (Object v : values) {
926      *     if (v == null) {
927      *         break;
928      *     }
929      *     headers.add(name, v);
930      * }
931      * </pre>
932      *
933      * @param name the name of the headers being set
934      * @param values the values of the headers being set
935      * @return {@code this}
936      */
937     Headers<T> set(T name, T... values);
938 
939     /**
940      * Sets a header with the specified name and value. If there is an existing header with the same name, it is
941      * removed. If the specified value is not a {@link String}, it is converted into a {@link String} by
942      * {@link Object#toString()}, except for {@link java.util.Date} and {@link java.util.Calendar}, which are formatted
943      * to the date format defined in <a
944      * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1">RFC2616</a>.
945      *
946      * @param name The name of the header being set
947      * @param value The value of the header being set
948      * @return {@code this}
949      */
950     Headers<T> setObject(T name, Object value);
951 
952     /**
953      * Sets a header with the specified name and values. If there is an existing header with the same name, it is
954      * removed. This getMethod can be represented approximately as the following code:
955      *
956      * <pre>
957      * headers.remove(name);
958      * for (Object v : values) {
959      *     if (v == null) {
960      *         break;
961      *     }
962      *     headers.add(name, v);
963      * }
964      * </pre>
965      *
966      * @param name the name of the headers being set
967      * @param values the values of the headers being set
968      * @return {@code this}
969      */
970     Headers<T> setObject(T name, Iterable<?> values);
971 
972     /**
973      * Sets a header with the specified name and values. If there is an existing header with the same name, it is
974      * removed. This getMethod can be represented approximately as the following code:
975      *
976      * <pre>
977      * headers.remove(name);
978      * for (Object v : values) {
979      *     if (v == null) {
980      *         break;
981      *     }
982      *     headers.add(name, v);
983      * }
984      * </pre>
985      *
986      * @param name the name of the headers being set
987      * @param values the values of the headers being set
988      * @return {@code this}
989      */
990     Headers<T> setObject(T name, Object... values);
991 
992     /**
993      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
994      * @param name The name to modify
995      * @param value The value
996      * @return {@code this}
997      */
998     Headers<T> setBoolean(T name, boolean value);
999 
1000     /**
1001      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1002      * @param name The name to modify
1003      * @param value The value
1004      * @return {@code this}
1005      */
1006     Headers<T> setByte(T name, byte value);
1007 
1008     /**
1009      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1010      * @param name The name to modify
1011      * @param value The value
1012      * @return {@code this}
1013      */
1014     Headers<T> setChar(T name, char value);
1015 
1016     /**
1017      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1018      * @param name The name to modify
1019      * @param value The value
1020      * @return {@code this}
1021      */
1022     Headers<T> setShort(T name, short value);
1023 
1024     /**
1025      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1026      * @param name The name to modify
1027      * @param value The value
1028      * @return {@code this}
1029      */
1030     Headers<T> setInt(T name, int value);
1031 
1032     /**
1033      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1034      * @param name The name to modify
1035      * @param value The value
1036      * @return {@code this}
1037      */
1038     Headers<T> setLong(T name, long value);
1039 
1040     /**
1041      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1042      * @param name The name to modify
1043      * @param value The value
1044      * @return {@code this}
1045      */
1046     Headers<T> setFloat(T name, float value);
1047 
1048     /**
1049      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1050      * @param name The name to modify
1051      * @param value The value
1052      * @return {@code this}
1053      */
1054     Headers<T> setDouble(T name, double value);
1055 
1056     /**
1057      * Set the {@code name} to {@code value}. This will remove all previous values associated with {@code name}.
1058      * @param name The name to modify
1059      * @param value The value
1060      * @return {@code this}
1061      */
1062     Headers<T> setTimeMillis(T name, long value);
1063 
1064     /**
1065      * Cleans the current header entries and copies all header entries of the specified {@code headers}.
1066      *
1067      * @return {@code this}
1068      */
1069     Headers<T> set(Headers<T> headers);
1070 
1071     /**
1072      * Retains all current headers but calls {@link #set(Object, Object)} for each entry in {@code headers}
1073      *
1074      * @param headers The headers used to {@link #set(Object, Object)} values in this instance
1075      * @return {@code this}
1076      */
1077     Headers<T> setAll(Headers<T> headers);
1078 
1079     /**
1080      * Removes the header with the specified name.
1081      *
1082      * @param name The name of the header to remove
1083      * @return {@code true} if and only if at least one entry has been removed
1084      */
1085     boolean remove(T name);
1086 
1087     /**
1088      * Removes all headers.
1089      *
1090      * @return {@code this}
1091      */
1092     Headers<T> clear();
1093 
1094     @Override
1095     Iterator<Entry<T, T>> iterator();
1096 
1097     /**
1098      * Provide a means of iterating over elements in this map with low GC
1099      *
1100      * @param visitor The visitor which will visit each element in this map
1101      * @return The last entry before iteration stopped or {@code null} if iteration went past the end
1102      */
1103     Map.Entry<T, T> forEachEntry(EntryVisitor<T> visitor) throws Exception;
1104 
1105     /**
1106      * Provide a means of iterating over elements in this map with low GC
1107      *
1108      * @param visitor The visitor which will visit each element in this map
1109      * @return The last key before iteration stopped or {@code null} if iteration went past the end
1110      */
1111     T forEachName(NameVisitor<T> visitor) throws Exception;
1112 }