1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 28 package org.apache.hc.core5.http; 29 30 import java.util.Iterator; 31 32 /** 33 * Messages head consisting of multiple message headers. 34 * 35 * @since 5.0 36 */ 37 public interface MessageHeaders { 38 39 /** 40 * Checks if a certain header is present in this message. Header values are 41 * ignored. 42 * 43 * @param name the header name to check for. 44 * @return true if at least one header with this name is present. 45 */ 46 boolean containsHeader(String name); 47 48 /** 49 * Checks if a certain header is present in this message and how many times. 50 * 51 * @param name the header name to check for. 52 * @return number of occurrences of the header in the message. 53 */ 54 int countHeaders(String name); 55 56 /** 57 * Returns the first header with a specified name of this message. Header 58 * values are ignored. If there is more than one matching header in the 59 * message the first element of {@link #getHeaders(String)} is returned. 60 * If there is no matching header in the message {@code null} is 61 * returned. 62 * 63 * @param name the name of the header to return. 64 * @return the first header whose name property equals {@code name} 65 * or {@code null} if no such header could be found. 66 */ 67 Header getFirstHeader(String name); 68 69 /** 70 * Gets single first header with the given name. 71 * 72 * <p>Header name comparison is case insensitive. 73 * 74 * @param name the name of the header to get 75 * @return the first header or {@code null} 76 * @throws ProtocolException in case multiple headers with the given name are found. 77 */ 78 Header getHeader(String name) throws ProtocolException; 79 80 /** 81 * Returns all the headers of this message. Headers are ordered in the sequence 82 * they will be sent over a connection. 83 * 84 * @return all the headers of this message 85 */ 86 Header[] getHeaders(); 87 88 /** 89 * Returns all the headers with a specified name of this message. Header values 90 * are ignored. Headers are ordered in the sequence they will be sent over a 91 * connection. 92 * 93 * @param name the name of the headers to return. 94 * @return the headers whose name property equals {@code name}. 95 */ 96 Header[] getHeaders(String name); 97 98 /** 99 * Returns the last header with a specified name of this message. Header values 100 * are ignored. If there is more than one matching header in the message the 101 * last element of {@link #getHeaders(String)} is returned. If there is no 102 * matching header in the message {@code null} is returned. 103 * 104 * @param name the name of the header to return. 105 * @return the last header whose name property equals {@code name}. 106 * or {@code null} if no such header could be found. 107 */ 108 Header getLastHeader(String name); 109 110 /** 111 * Returns an iterator of all the headers. 112 * 113 * @return Iterator that returns Header objects in the sequence they are 114 * sent over a connection. 115 */ 116 Iterator<Header> headerIterator(); 117 118 /** 119 * Returns an iterator of the headers with a given name. 120 * 121 * @param name the name of the headers over which to iterate, or 122 * {@code null} for all headers 123 * 124 * @return Iterator that returns Header objects with the argument name 125 * in the sequence they are sent over a connection. 126 */ 127 Iterator<Header> headerIterator(String name); 128 129 }