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.netty.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 }