1 /*
2 * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.net.http;
27
28 import java.util.ArrayList;
29 import java.util.List;
30 import java.util.Locale;
31 import java.util.Map;
32 import java.util.Optional;
33 import java.util.OptionalLong;
34 import java.util.TreeMap;
35 import java.util.TreeSet;
36 import java.util.function.BiPredicate;
37 import static java.lang.String.CASE_INSENSITIVE_ORDER;
38 import static java.util.Collections.unmodifiableMap;
39 import static java.util.Objects.requireNonNull;
40
41 /**
42 * A read-only view of a set of HTTP headers.
43 *
44 * <p> An {@code HttpHeaders} is not typically created directly, but rather
45 * returned from an {@link HttpRequest#headers() HttpRequest} or an
46 * {@link HttpResponse#headers() HttpResponse}. Specific HTTP headers can be
47 * set for a {@linkplain HttpRequest request} through one of the request
48 * builder's {@link HttpRequest.Builder#header(String, String) headers} methods.
49 *
50 * <p> The methods of this class ( that accept a String header name ), and the
51 * {@code Map} returned by the {@link #map() map} method, operate without regard
52 * to case when retrieving the header value(s).
53 *
54 * <p> An HTTP header name may appear more than once in the HTTP protocol. As
55 * such, headers are represented as a name and a list of values. Each occurrence
56 * of a header value is added verbatim, to the appropriate header name list,
57 * without interpreting its value. In particular, {@code HttpHeaders} does not
58 * perform any splitting or joining of comma separated header value strings. The
59 * order of elements in a header value list is preserved when {@link
60 * HttpRequest.Builder#header(String, String) building} a request. For
61 * responses, the order of elements in a header value list is the order in which
62 * they were received. The {@code Map} returned by the {@code map} method,
63 * however, does not provide any guarantee with regard to the ordering of its
64 * entries.
65 *
66 * <p> {@code HttpHeaders} instances are immutable.
67 *
68 * @since 11
69 */
70 public final class HttpHeaders {
71
72 /**
73 * Returns an {@link Optional} containing the first header string value of
74 * the given named (and possibly multi-valued) header. If the header is not
75 * present, then the returned {@code Optional} is empty.
76 *
77 * @param name the header name
78 * @return an {@code Optional<String>} containing the first named header
79 * string value, if present
80 */
81 public Optional<String> firstValue(String name) {
82 return allValues(name).stream().findFirst();
83 }
84
85 /**
86 * Returns an {@link OptionalLong} containing the first header string value
87 * of the named header field. If the header is not present, then the
88 * Optional is empty. If the header is present but contains a value that
89 * does not parse as a {@code Long} value, then an exception is thrown.
90 *
91 * @param name the header name
92 * @return an {@code OptionalLong}
93 * @throws NumberFormatException if a value is found, but does not parse as
94 * a Long
95 */
96 public OptionalLong firstValueAsLong(String name) {
97 return allValues(name).stream().mapToLong(Long::valueOf).findFirst();
98 }
99
100 /**
101 * Returns an unmodifiable List of all of the header string values of the
102 * given named header. Always returns a List, which may be empty if the
103 * header is not present.
104 *
105 * @param name the header name
106 * @return a List of headers string values
107 */
108 public List<String> allValues(String name) {
109 requireNonNull(name);
110 List<String> values = map().get(name);
111 // Making unmodifiable list out of empty in order to make a list which
112 // throws UOE unconditionally
113 return values != null ? values : List.of();
114 }
115
116 /**
117 * Returns an unmodifiable multi Map view of this HttpHeaders.
118 *
119 * @return the Map
120 */
121 public Map<String,List<String>> map() {
122 return headers;
123 }
124
125 /**
126 * Tests this HTTP headers instance for equality with the given object.
127 *
128 * <p> If the given object is not an {@code HttpHeaders} then this
129 * method returns {@code false}. Two HTTP headers are equal if each
130 * of their corresponding {@linkplain #map() maps} are equal.
131 *
132 * <p> This method satisfies the general contract of the {@link
133 * Object#equals(Object) Object.equals} method.
134 *
135 * @param obj the object to which this object is to be compared
136 * @return {@code true} if, and only if, the given object is an {@code
137 * HttpHeaders} that is equal to this HTTP headers
138 */
139 public final boolean equals(Object obj) {
140 if (!(obj instanceof HttpHeaders))
141 return false;
142 HttpHeaders that = (HttpHeaders)obj;
143 return this.map().equals(that.map());
144 }
145
146 /**
147 * Computes a hash code for this HTTP headers instance.
148 *
149 * <p> The hash code is based upon the components of the HTTP headers
150 * {@link #map() map}, and satisfies the general contract of the
151 * {@link Object#hashCode Object.hashCode} method.
152 *
153 * @return the hash-code value for this HTTP headers
154 */
155 public final int hashCode() {
156 return map().hashCode();
157 }
158
159 /**
160 * Returns this HTTP headers as a string.
161 *
162 * @return a string describing the HTTP headers
163 */
164 @Override
165 public String toString() {
166 StringBuilder sb = new StringBuilder();
167 sb.append(super.toString()).append(" { ");
168 sb.append(map());
169 sb.append(" }");
170 return sb.toString();
171 }
172
173 /**
174 * Returns an HTTP headers from the given map. The given map's key
175 * represents the header name, and its value the list of string header
176 * values for that header name.
177 *
178 * <p> An HTTP header name may appear more than once in the HTTP protocol.
179 * Such, <i>multi-valued</i>, headers must be represented by a single entry
180 * in the given map, whose entry value is a list that represents the
181 * multiple header string values. Leading and trailing whitespaces are
182 * removed from all string values retrieved from the given map and its lists
183 * before processing. Only headers that, after filtering, contain at least
184 * one, possibly empty string, value will be added to the HTTP headers.
185 *
186 * @apiNote The primary purpose of this method is for testing frameworks.
187 * Per-request headers can be set through one of the {@code HttpRequest}
188 * {@link HttpRequest.Builder#header(String, String) headers} methods.
189 *
190 * @param headerMap the map containing the header names and values
191 * @param filter a filter that can be used to inspect each
192 * header-name-and-value pair in the given map to determine if
193 * it should, or should not, be added to the to the HTTP
194 * headers
195 * @return an HTTP headers instance containing the given headers
196 * @throws NullPointerException if any of: {@code headerMap}, a key or value
197 * in the given map, or an entry in the map's value list, or
198 * {@code filter}, is {@code null}
199 * @throws IllegalArgumentException if the given {@code headerMap} contains
200 * any two keys that are equal ( without regard to case ); or if the
201 * given map contains any key whose length, after trimming
202 * whitespaces, is {@code 0}
203 */
204 public static HttpHeaders of(Map<String,List<String>> headerMap,
205 BiPredicate<String,String> filter) {
206 requireNonNull(headerMap);
207 requireNonNull(filter);
208 return headersOf(headerMap, filter);
209 }
210
211 // --
212
213 private static final HttpHeaders NO_HEADERS = new HttpHeaders(Map.of());
214
215 private final Map<String,List<String>> headers;
216
217 private HttpHeaders(Map<String,List<String>> headers) {
218 this.headers = headers;
219 }
220
221 // Returns a new HTTP headers after performing a structural copy and filtering.
222 private static HttpHeaders headersOf(Map<String,List<String>> map,
223 BiPredicate<String,String> filter) {
224 TreeMap<String,List<String>> other = new TreeMap<>(CASE_INSENSITIVE_ORDER);
225 TreeSet<String> notAdded = new TreeSet<>(CASE_INSENSITIVE_ORDER);
226 ArrayList<String> tempList = new ArrayList<>();
227 map.forEach((key, value) -> {
228 String headerName = requireNonNull(key).trim();
229 if (headerName.isEmpty()) {
230 throw new IllegalArgumentException("empty key");
231 }
232 List<String> headerValues = requireNonNull(value);
233 headerValues.forEach(headerValue -> {
234 headerValue = requireNonNull(headerValue).trim();
235 if (filter.test(headerName, headerValue)) {
236 tempList.add(headerValue);
237 }
238 });
239
240 if (tempList.isEmpty()) {
241 if (other.containsKey(headerName)
242 || notAdded.contains(headerName.toLowerCase(Locale.ROOT)))
243 throw new IllegalArgumentException("duplicate key: " + headerName);
244 notAdded.add(headerName.toLowerCase(Locale.ROOT));
245 } else if (other.put(headerName, List.copyOf(tempList)) != null) {
246 throw new IllegalArgumentException("duplicate key: " + headerName);
247 }
248 tempList.clear();
249 });
250 return other.isEmpty() ? NO_HEADERS : new HttpHeaders(unmodifiableMap(other));
251 }
252 }