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 }