View Javadoc
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 containsHeaders(String name);
55  
56      /**
57       * Returns all the headers with a specified name of this message. Header values
58       * are ignored. Headers are orderd in the sequence they will be sent over a
59       * connection.
60       *
61       * @param name the name of the headers to return.
62       * @return the headers whose name property equals {@code name}.
63       */
64      Header[] getHeaders(String name);
65  
66      /**
67       * Gets single first header with the given name.
68       *
69       * <p>Header name comparison is case insensitive.
70       *
71       * @param name the name of the header to get
72       * @return the first header or {@code null}
73       * @throws ProtocolException in case multiple headers with the given name are found.
74       */
75      Header getSingleHeader(String name) throws ProtocolException;
76  
77      /**
78       * Returns the first header with a specified name of this message. Header
79       * values are ignored. If there is more than one matching header in the
80       * message the first element of {@link #getHeaders(String)} is returned.
81       * If there is no matching header in the message {@code null} is
82       * returned.
83       *
84       * @param name the name of the header to return.
85       * @return the first header whose name property equals {@code name}
86       *   or {@code null} if no such header could be found.
87       */
88      Header getFirstHeader(String name);
89  
90      /**
91       * Returns the last header with a specified name of this message. Header values
92       * are ignored. If there is more than one matching header in the message the
93       * last element of {@link #getHeaders(String)} is returned. If there is no
94       * matching header in the message {@code null} is returned.
95       *
96       * @param name the name of the header to return.
97       * @return the last header whose name property equals {@code name}.
98       *   or {@code null} if no such header could be found.
99       */
100     Header getLastHeader(String name);
101 
102     /**
103      * Returns all the headers of this message. Headers are orderd in the sequence
104      * they will be sent over a connection.
105      *
106      * @return all the headers of this message
107      */
108     Header[] getAllHeaders();
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 }