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 }