001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.tools;
003
004import static org.openstreetmap.josm.tools.I18n.tr;
005
006import java.io.BufferedReader;
007import java.io.IOException;
008import java.io.InputStream;
009import java.net.CookieHandler;
010import java.net.CookieManager;
011import java.net.CookiePolicy;
012import java.net.HttpURLConnection;
013import java.net.MalformedURLException;
014import java.net.URL;
015import java.nio.charset.StandardCharsets;
016import java.util.List;
017import java.util.Locale;
018import java.util.Map;
019import java.util.Objects;
020import java.util.Scanner;
021import java.util.TreeMap;
022import java.util.concurrent.TimeUnit;
023import java.util.regex.Matcher;
024import java.util.regex.Pattern;
025import java.util.zip.GZIPInputStream;
026import java.util.zip.InflaterInputStream;
027
028import org.openstreetmap.josm.data.validation.routines.DomainValidator;
029import org.openstreetmap.josm.gui.progress.NullProgressMonitor;
030import org.openstreetmap.josm.gui.progress.ProgressMonitor;
031import org.openstreetmap.josm.io.Compression;
032import org.openstreetmap.josm.io.NetworkManager;
033import org.openstreetmap.josm.io.ProgressInputStream;
034import org.openstreetmap.josm.io.UTFInputStreamReader;
035import org.openstreetmap.josm.io.auth.DefaultAuthenticator;
036import org.openstreetmap.josm.spi.preferences.Config;
037
038/**
039 * Provides uniform access for a HTTP/HTTPS server. This class should be used in favour of {@link HttpURLConnection}.
040 * @since 9168
041 */
042public abstract class HttpClient {
043
044    /**
045     * HTTP client factory.
046     * @since 15229
047     */
048    @FunctionalInterface
049    public interface HttpClientFactory {
050        /**
051         * Creates a new instance for the given URL and a {@code GET} request
052         *
053         * @param url the URL
054         * @param requestMethod the HTTP request method to perform when calling
055         * @return a new instance
056         */
057        HttpClient create(URL url, String requestMethod);
058    }
059
060    private URL url;
061    private final String requestMethod;
062    private int connectTimeout = (int) TimeUnit.SECONDS.toMillis(Config.getPref().getInt("socket.timeout.connect", 15));
063    private int readTimeout = (int) TimeUnit.SECONDS.toMillis(Config.getPref().getInt("socket.timeout.read", 30));
064    private byte[] requestBody;
065    private long ifModifiedSince;
066    private final Map<String, String> headers = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
067    private int maxRedirects = Config.getPref().getInt("socket.maxredirects", 5);
068    private boolean useCache = true;
069    private String reasonForRequest;
070    private String outputMessage = tr("Uploading data ...");
071    private Response response;
072    private boolean finishOnCloseOutput = true;
073    private boolean debug;
074
075    // Pattern to detect Tomcat error message. Be careful with change of format:
076    // CHECKSTYLE.OFF: LineLength
077    // https://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/valves/ErrorReportValve.java?r1=1740707&r2=1779641&pathrev=1779641&diff_format=h
078    // CHECKSTYLE.ON: LineLength
079    private static final Pattern TOMCAT_ERR_MESSAGE = Pattern.compile(
080        ".*<p><b>[^<]+</b>[^<]+</p><p><b>[^<]+</b> (?:<u>)?([^<]*)(?:</u>)?</p><p><b>[^<]+</b> (?:<u>)?[^<]*(?:</u>)?</p>.*",
081        Pattern.CASE_INSENSITIVE);
082
083    private static HttpClientFactory factory;
084
085    static {
086        try {
087            CookieHandler.setDefault(new CookieManager(null, CookiePolicy.ACCEPT_ALL));
088        } catch (SecurityException e) {
089            Logging.log(Logging.LEVEL_ERROR, "Unable to set default cookie handler", e);
090        }
091    }
092
093    /**
094     * Registers a new HTTP client factory.
095     * @param newFactory new HTTP client factory
096     * @since 15229
097     */
098    public static void setFactory(HttpClientFactory newFactory) {
099        factory = Objects.requireNonNull(newFactory);
100    }
101
102    /**
103     * Constructs a new {@code HttpClient}.
104     * @param url URL to access
105     * @param requestMethod HTTP request method (GET, POST, PUT, DELETE...)
106     */
107    protected HttpClient(URL url, String requestMethod) {
108        try {
109            String host = url.getHost();
110            String asciiHost = DomainValidator.unicodeToASCII(host);
111            this.url = asciiHost.equals(host) ? url : new URL(url.getProtocol(), asciiHost, url.getPort(), url.getFile());
112        } catch (MalformedURLException e) {
113            throw new JosmRuntimeException(e);
114        }
115        this.requestMethod = requestMethod;
116        this.headers.put("Accept-Encoding", "gzip, deflate");
117    }
118
119    /**
120     * Opens the HTTP connection.
121     * @return HTTP response
122     * @throws IOException if any I/O error occurs
123     */
124    public final Response connect() throws IOException {
125        return connect(null);
126    }
127
128    /**
129     * Opens the HTTP connection.
130     * @param progressMonitor progress monitor
131     * @return HTTP response
132     * @throws IOException if any I/O error occurs
133     * @since 9179
134     */
135    public final Response connect(ProgressMonitor progressMonitor) throws IOException {
136        return connect(progressMonitor, null, null);
137    }
138
139    /**
140     * Opens the HTTP connection.
141     * @param progressMonitor progress monitor
142     * @param authRedirectLocation The location where we will be redirected for authentication
143     * @param authRequestProperty The authorization header to set when being redirected to the auth location
144     * @return HTTP response
145     * @throws IOException if any I/O error occurs
146     * @since 18913
147     */
148    public final Response connect(ProgressMonitor progressMonitor, String authRedirectLocation, String authRequestProperty) throws IOException {
149        if (progressMonitor == null) {
150            progressMonitor = NullProgressMonitor.INSTANCE;
151        }
152        setupConnection(progressMonitor);
153
154        boolean successfulConnection = false;
155        try {
156            Stopwatch stopwatch = Stopwatch.createStarted();
157            ConnectionResponse cr;
158            try {
159                if (Logging.isDebugEnabled()) {
160                    Logging.debug("REQUEST HEADERS: {0}", headers);
161                }
162                cr = performConnection();
163                final boolean hasReason = !Utils.isEmpty(reasonForRequest);
164                logRequest("{0} {1}{2} -> {3} {4} ({5}{6})",
165                        getRequestMethod(), TextUtils.stripUrl(getURL().toString()), hasReason ? (" (" + reasonForRequest + ')') : "",
166                        cr.getResponseVersion(), cr.getResponseCode(),
167                        stopwatch,
168                        cr.getContentLengthLong() > 0
169                                ? ("; " + Utils.getSizeString(cr.getContentLengthLong(), Locale.getDefault()))
170                                : ""
171                );
172                if (Logging.isDebugEnabled()) {
173                    try {
174                        Logging.debug("RESPONSE HEADERS: {0}", cr.getHeaderFields());
175                    } catch (IllegalArgumentException e) {
176                        Logging.warn(e);
177                    }
178                }
179                if (DefaultAuthenticator.getInstance().isEnabled() && cr.getResponseCode() == HttpURLConnection.HTTP_UNAUTHORIZED) {
180                    DefaultAuthenticator.getInstance().addFailedCredentialHost(url.getHost());
181                }
182            } catch (IOException | RuntimeException e) {
183                logRequest("{0} {1} -> !!! ({2})", requestMethod, TextUtils.stripUrl(url.toString()), stopwatch);
184                Logging.warn(e);
185                //noinspection ThrowableResultOfMethodCallIgnored
186                NetworkManager.addNetworkError(url, Utils.getRootCause(e));
187                throw e;
188            }
189            if (isRedirect(cr.getResponseCode())) {
190                final String redirectLocation = cr.getHeaderField("Location");
191                if (redirectLocation == null) {
192                    /* I18n: argument is HTTP response code */
193                    throw new IOException(tr("Unexpected response from HTTP server. Got {0} response without ''Location'' header." +
194                            " Can''t redirect. Aborting.", cr.getResponseCode()));
195                } else if (maxRedirects > 0) {
196                    final URL oldUrl = url;
197                    url = new URL(url, redirectLocation);
198                    maxRedirects--;
199                    logRequest(tr("Download redirected to ''{0}''", redirectLocation));
200                    if (authRedirectLocation != null && authRequestProperty != null && redirectLocation.startsWith(authRedirectLocation)) {
201                        setHeader("Authorization", authRequestProperty);
202                    } else if (!Objects.equals(oldUrl.getHost(), this.url.getHost()) && this.getRequestHeader("Authorization") != null) {
203                        // Fix JOSM #21935: Avoid leaking `Authorization` header on redirects.
204                        logRequest(tr("Download redirected to different host (''{0}'' -> ''{1}''), removing authorization headers",
205                                oldUrl.getHost(), url.getHost()));
206                        this.headers.remove("Authorization");
207                    }
208                    response = connect();
209                    successfulConnection = true;
210                    return response;
211                } else if (maxRedirects == 0) {
212                    String msg = tr("Too many redirects to the download URL detected. Aborting.");
213                    throw new IOException(msg);
214                }
215            }
216            response = buildResponse(progressMonitor);
217            successfulConnection = true;
218            return response;
219        } finally {
220            if (!successfulConnection) {
221                performDisconnection();
222                progressMonitor.finishTask();
223            }
224        }
225    }
226
227    protected abstract void setupConnection(ProgressMonitor progressMonitor) throws IOException;
228
229    protected abstract ConnectionResponse performConnection() throws IOException;
230
231    protected abstract void performDisconnection() throws IOException;
232
233    protected abstract Response buildResponse(ProgressMonitor progressMonitor) throws IOException;
234
235    protected final void notifyConnect(ProgressMonitor progressMonitor) {
236        progressMonitor.beginTask(tr("Contacting Server..."), 1);
237        progressMonitor.indeterminateSubTask(null);
238    }
239
240    protected final void logRequest(String pattern, Object... args) {
241        if (debug) {
242            Logging.debug(pattern, args);
243        } else {
244            Logging.info(pattern, args);
245        }
246    }
247
248    protected final void logRequestBody() {
249        logRequest("{0} {1} ({2}) ...", requestMethod, url, Utils.getSizeString(requestBody.length, Locale.getDefault()));
250        if (Logging.isTraceEnabled() && hasRequestBody()) {
251            Logging.trace("BODY: {0}", new String(requestBody, StandardCharsets.UTF_8));
252        }
253    }
254
255    /**
256     * Returns the HTTP response which is set only after calling {@link #connect()}.
257     * Calling this method again, returns the identical object (unless another {@link #connect()} is performed).
258     *
259     * @return the HTTP response
260     * @since 9309
261     */
262    public final Response getResponse() {
263        return response;
264    }
265
266    /**
267     * A wrapper for the HTTP connection response.
268     * @since 15229
269     */
270    public interface ConnectionResponse {
271        /**
272         * Gets the HTTP version from the HTTP response.
273         * @return the HTTP version from the HTTP response
274         */
275        String getResponseVersion();
276
277        /**
278         * Gets the status code from an HTTP response message.
279         * For example, in the case of the following status lines:
280         * <PRE>
281         * HTTP/1.0 200 OK
282         * HTTP/1.0 401 Unauthorized
283         * </PRE>
284         * It will return 200 and 401 respectively.
285         * Returns -1 if no code can be discerned
286         * from the response (i.e., the response is not valid HTTP).
287         * @return the HTTP Status-Code, or -1
288         * @throws IOException if an error occurred connecting to the server.
289         */
290        int getResponseCode() throws IOException;
291
292        /**
293         * Returns the value of the {@code content-length} header field as a long.
294         *
295         * @return  the content length of the resource that this connection's URL
296         *          references, or {@code -1} if the content length is not known.
297         */
298        long getContentLengthLong();
299
300        /**
301         * Returns an unmodifiable Map of the header fields.
302         * The Map keys are Strings that represent the response-header field names.
303         * Each Map value is an unmodifiable List of Strings that represents
304         * the corresponding field values.
305         *
306         * @return a Map of header fields
307         */
308        Map<String, List<String>> getHeaderFields();
309
310        /**
311         * Returns the value of the named header field.
312         * @param name the name of a header field.
313         * @return the value of the named header field, or {@code null}
314         *          if there is no such field in the header.
315         */
316        String getHeaderField(String name);
317    }
318
319    /**
320     * A wrapper for the HTTP response.
321     */
322    public abstract static class Response {
323        private final ProgressMonitor monitor;
324        private final int responseCode;
325        private final String responseMessage;
326        private boolean uncompress;
327        private boolean uncompressAccordingToContentDisposition;
328        private String responseData;
329
330        protected Response(ProgressMonitor monitor, int responseCode, String responseMessage) {
331            this.monitor = Objects.requireNonNull(monitor, "monitor");
332            this.responseCode = responseCode;
333            this.responseMessage = responseMessage;
334        }
335
336        protected final void debugRedirect() throws IOException {
337            if (responseCode >= 300) {
338                String contentType = getContentType();
339                if (contentType == null ||
340                    contentType.contains("text") ||
341                    contentType.contains("html") ||
342                    contentType.contains("xml")
343                ) {
344                    String content = fetchContent();
345                    Logging.debug(content.isEmpty() ? "Server did not return any body" : "Response body: \n" + content);
346                } else {
347                    Logging.debug("Server returned content: {0} of length: {1}. Not printing.", contentType, getContentLength());
348                }
349            }
350        }
351
352        /**
353         * Sets whether {@link #getContent()} should uncompress the input stream if necessary.
354         *
355         * @param uncompress whether the input stream should be uncompressed if necessary
356         * @return {@code this}
357         */
358        public final Response uncompress(boolean uncompress) {
359            this.uncompress = uncompress;
360            return this;
361        }
362
363        /**
364         * Sets whether {@link #getContent()} should uncompress the input stream according to {@code Content-Disposition}
365         * HTTP header.
366         * @param uncompressAccordingToContentDisposition whether the input stream should be uncompressed according to
367         * {@code Content-Disposition}
368         * @return {@code this}
369         * @since 9172
370         */
371        public final Response uncompressAccordingToContentDisposition(boolean uncompressAccordingToContentDisposition) {
372            this.uncompressAccordingToContentDisposition = uncompressAccordingToContentDisposition;
373            return this;
374        }
375
376        /**
377         * Returns the URL.
378         * @return the URL
379         * @see HttpURLConnection#getURL()
380         * @since 9172
381         */
382        public abstract URL getURL();
383
384        /**
385         * Returns the request method.
386         * @return the HTTP request method
387         * @see HttpURLConnection#getRequestMethod()
388         * @since 9172
389         */
390        public abstract String getRequestMethod();
391
392        /**
393         * Returns an input stream that reads from this HTTP connection, or,
394         * error stream if the connection failed but the server sent useful data.
395         * <p>
396         * Note: the return value can be null, if both the input and the error stream are null.
397         * Seems to be the case if the OSM server replies a 401 Unauthorized, see #3887
398         * @return input or error stream
399         * @throws IOException if any I/O error occurs
400         *
401         * @see HttpURLConnection#getInputStream()
402         * @see HttpURLConnection#getErrorStream()
403         */
404        public final InputStream getContent() throws IOException {
405            InputStream in = new ProgressInputStream(getInputStream(), getContentLength(), monitor);
406            if ("gzip".equalsIgnoreCase(getContentEncoding())) {
407                in = new GZIPInputStream(in);
408            } else if ("deflate".equalsIgnoreCase(getContentEncoding())) {
409                in = new InflaterInputStream(in);
410            }
411            Compression compression = Compression.NONE;
412            if (uncompress) {
413                final String contentType = getContentType();
414                Logging.debug("Uncompressing input stream according to Content-Type header: {0}", contentType);
415                compression = Compression.forContentType(contentType);
416            }
417            if (uncompressAccordingToContentDisposition && Compression.NONE == compression) {
418                final String contentDisposition = getHeaderField("Content-Disposition");
419                final Matcher matcher = Pattern.compile("filename=\"([^\"]+)\"").matcher(
420                        contentDisposition != null ? contentDisposition : "");
421                if (matcher.find()) {
422                    Logging.debug("Uncompressing input stream according to Content-Disposition header: {0}", contentDisposition);
423                    compression = Compression.byExtension(matcher.group(1));
424                }
425            }
426            in = compression.getUncompressedInputStream(in);
427            return in;
428        }
429
430        protected abstract InputStream getInputStream() throws IOException;
431
432        /**
433         * Returns {@link #getContent()} wrapped in a buffered reader.
434         *
435         * Detects Unicode charset in use utilizing {@link UTFInputStreamReader}.
436         * @return buffered reader
437         * @throws IOException if any I/O error occurs
438         */
439        public final BufferedReader getContentReader() throws IOException {
440            return new BufferedReader(
441                    UTFInputStreamReader.create(getContent())
442            );
443        }
444
445        /**
446         * Fetches the HTTP response as String.
447         * @return the response
448         * @throws IOException if any I/O error occurs
449         */
450        public final synchronized String fetchContent() throws IOException {
451            if (responseData == null) {
452                try (Scanner scanner = new Scanner(getContentReader()).useDelimiter("\\A")) { // \A - beginning of input
453                    responseData = scanner.hasNext() ? scanner.next() : "";
454                }
455            }
456            return responseData;
457        }
458
459        /**
460         * Gets the response code from this HTTP connection.
461         * @return HTTP response code
462         *
463         * @see HttpURLConnection#getResponseCode()
464         */
465        public final int getResponseCode() {
466            return responseCode;
467        }
468
469        /**
470         * Gets the response message from this HTTP connection.
471         * @return HTTP response message
472         *
473         * @see HttpURLConnection#getResponseMessage()
474         * @since 9172
475         */
476        public final String getResponseMessage() {
477            return responseMessage;
478        }
479
480        /**
481         * Returns the {@code Content-Encoding} header.
482         * @return {@code Content-Encoding} HTTP header
483         * @see HttpURLConnection#getContentEncoding()
484         */
485        public abstract String getContentEncoding();
486
487        /**
488         * Returns the {@code Content-Type} header.
489         * @return {@code Content-Type} HTTP header
490         * @see HttpURLConnection#getContentType()
491         */
492        public abstract String getContentType();
493
494        /**
495         * Returns the {@code Expire} header.
496         * @return {@code Expire} HTTP header
497         * @see HttpURLConnection#getExpiration()
498         * @since 9232
499         */
500        public abstract long getExpiration();
501
502        /**
503         * Returns the {@code Last-Modified} header.
504         * @return {@code Last-Modified} HTTP header
505         * @see HttpURLConnection#getLastModified()
506         * @since 9232
507         */
508        public abstract long getLastModified();
509
510        /**
511         * Returns the {@code Content-Length} header.
512         * @return {@code Content-Length} HTTP header
513         * @see HttpURLConnection#getContentLengthLong()
514         */
515        public abstract long getContentLength();
516
517        /**
518         * Returns the value of the named header field.
519         * @param name the name of a header field
520         * @return the value of the named header field, or {@code null} if there is no such field in the header
521         * @see HttpURLConnection#getHeaderField(String)
522         * @since 9172
523         */
524        public abstract String getHeaderField(String name);
525
526        /**
527         * Returns an unmodifiable Map mapping header keys to a List of header values.
528         * As per RFC 2616, section 4.2 header names are case insensitive, so returned map is also case insensitive
529         * @return unmodifiable Map mapping header keys to a List of header values
530         * @see HttpURLConnection#getHeaderFields()
531         * @since 9232
532         */
533        public abstract Map<String, List<String>> getHeaderFields();
534
535        /**
536         * Indicates that other requests to the server are unlikely in the near future.
537         * @see HttpURLConnection#disconnect()
538         */
539        public abstract void disconnect();
540    }
541
542    /**
543     * Creates a new instance for the given URL and a {@code GET} request
544     *
545     * @param url the URL
546     * @return a new instance
547     */
548    public static HttpClient create(URL url) {
549        return create(url, "GET");
550    }
551
552    /**
553     * Creates a new instance for the given URL and a {@code GET} request
554     *
555     * @param url the URL
556     * @param requestMethod the HTTP request method to perform when calling
557     * @return a new instance
558     */
559    public static HttpClient create(URL url, String requestMethod) {
560        if (factory == null) {
561            throw new IllegalStateException("HTTP factory has not been set");
562        }
563        return factory.create(url, requestMethod)
564                // #18812: specify `Accept=*/*` to prevent Java from adding `Accept=text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2`
565                .setAccept("*/*");
566    }
567
568    /**
569     * Returns the URL set for this connection.
570     * @return the URL
571     * @see #create(URL)
572     * @see #create(URL, String)
573     * @since 9172
574     */
575    public final URL getURL() {
576        return url;
577    }
578
579    /**
580     * Returns the request body set for this connection.
581     * @return the HTTP request body, or null
582     * @since 15229
583     */
584    public final byte[] getRequestBody() {
585        return Utils.copyArray(requestBody);
586    }
587
588    /**
589     * Determines if a non-empty request body has been set for this connection.
590     * @return {@code true} if the request body is set and non-empty
591     * @since 15229
592     */
593    public final boolean hasRequestBody() {
594        return requestBody != null && requestBody.length > 0;
595    }
596
597    /**
598     * Determines if the underlying HTTP method requires a body.
599     * @return {@code true} if the underlying HTTP method requires a body
600     * @since 15229
601     */
602    public final boolean requiresBody() {
603        return "PUT".equals(requestMethod) || "POST".equals(requestMethod) || "DELETE".equals(requestMethod);
604    }
605
606    /**
607     * Returns the request method set for this connection.
608     * @return the HTTP request method
609     * @see #create(URL, String)
610     * @since 9172
611     */
612    public final String getRequestMethod() {
613        return requestMethod;
614    }
615
616    /**
617     * Returns the set value for the given {@code header}.
618     * @param header HTTP header name
619     * @return HTTP header value
620     * @since 9172
621     */
622    public final String getRequestHeader(String header) {
623        return headers.get(header);
624    }
625
626    /**
627     * Returns the connect timeout.
628     * @return the connect timeout, in milliseconds
629     * @since 15229
630     */
631    public final int getConnectTimeout() {
632        return connectTimeout;
633    }
634
635    /**
636     * Returns the read timeout.
637     * @return the read timeout, in milliseconds
638     * @since 15229
639     */
640    public final int getReadTimeout() {
641        return readTimeout;
642    }
643
644    /**
645     * Returns the {@code If-Modified-Since} header value.
646     * @return the {@code If-Modified-Since} header value
647     * @since 15229
648     */
649    public final long getIfModifiedSince() {
650        return ifModifiedSince;
651    }
652
653    /**
654     * Determines whether not to set header {@code Cache-Control=no-cache}.
655     * By default, {@code useCache} is true, i.e., the header {@code Cache-Control=no-cache} is not sent.
656     *
657     * @return whether not to set header {@code Cache-Control=no-cache}
658     * @since 15229
659     */
660    public final boolean isUseCache() {
661        return useCache;
662    }
663
664    /**
665     * Returns the headers.
666     * @return the headers
667     * @since 15229
668     */
669    public final Map<String, String> getHeaders() {
670        return headers;
671    }
672
673    /**
674     * Returns the reason for request.
675     * @return the reason for request
676     * @since 15229
677     */
678    public final String getReasonForRequest() {
679        return reasonForRequest;
680    }
681
682    /**
683     * Returns the output message.
684     * @return the output message
685     */
686    protected final String getOutputMessage() {
687        return outputMessage;
688    }
689
690    /**
691     * Determines whether the progress monitor task will be finished when the output stream is closed. {@code true} by default.
692     * @return the finishOnCloseOutput
693     */
694    protected final boolean isFinishOnCloseOutput() {
695        return finishOnCloseOutput;
696    }
697
698    /**
699     * Sets whether not to set header {@code Cache-Control=no-cache}.
700     * By default, {@code useCache} is true, i.e., the header {@code Cache-Control=no-cache} is not sent.
701     *
702     * @param useCache whether not to set header {@code Cache-Control=no-cache}
703     * @return {@code this}
704     * @see HttpURLConnection#setUseCaches(boolean)
705     */
706    public final HttpClient useCache(boolean useCache) {
707        this.useCache = useCache;
708        return this;
709    }
710
711    /**
712     * Sets whether not to set header {@code Connection=close}
713     * <p>
714     * This might fix #7640, see
715     * <a href='https://web.archive.org/web/20140118201501/http://www.tikalk.com/java/forums/httpurlconnection-disable-keep-alive'>here</a>.
716     *
717     * @param keepAlive whether not to set header {@code Connection=close}
718     * @return {@code this}
719     */
720    public final HttpClient keepAlive(boolean keepAlive) {
721        return setHeader("Connection", keepAlive ? null : "close");
722    }
723
724    /**
725     * Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the resource referenced
726     * by this URLConnection. If the timeout expires before the connection can be established, a
727     * {@link java.net.SocketTimeoutException} is raised. A timeout of zero is interpreted as an infinite timeout.
728     * @param connectTimeout an {@code int} that specifies the connect timeout value in milliseconds
729     * @return {@code this}
730     * @see HttpURLConnection#setConnectTimeout(int)
731     */
732    public final HttpClient setConnectTimeout(int connectTimeout) {
733        this.connectTimeout = connectTimeout;
734        return this;
735    }
736
737    /**
738     * Sets the read timeout to a specified timeout, in milliseconds. A non-zero value specifies the timeout when reading from
739     * input stream when a connection is established to a resource. If the timeout expires before there is data available for
740     * read, a {@link java.net.SocketTimeoutException} is raised. A timeout of zero is interpreted as an infinite timeout.
741     * @param readTimeout an {@code int} that specifies the read timeout value in milliseconds
742     * @return {@code this}
743     * @see HttpURLConnection#setReadTimeout(int)
744     */
745    public final HttpClient setReadTimeout(int readTimeout) {
746        this.readTimeout = readTimeout;
747        return this;
748    }
749
750    /**
751     * Sets the {@code Accept} header.
752     * @param accept header value
753     *
754     * @return {@code this}
755     */
756    public final HttpClient setAccept(String accept) {
757        return setHeader("Accept", accept);
758    }
759
760    /**
761     * Sets the request body for {@code PUT}/{@code POST} requests.
762     * @param requestBody request body
763     *
764     * @return {@code this}
765     */
766    public final HttpClient setRequestBody(byte[] requestBody) {
767        this.requestBody = Utils.copyArray(requestBody);
768        return this;
769    }
770
771    /**
772     * Sets the {@code If-Modified-Since} header.
773     * @param ifModifiedSince header value
774     *
775     * @return {@code this}
776     */
777    public final HttpClient setIfModifiedSince(long ifModifiedSince) {
778        this.ifModifiedSince = ifModifiedSince;
779        return this;
780    }
781
782    /**
783     * Sets the maximum number of redirections to follow.
784     *
785     * Set {@code maxRedirects} to {@code -1} in order to ignore redirects, i.e.,
786     * to not throw an {@link IOException} in {@link #connect()}.
787     * @param maxRedirects header value
788     *
789     * @return {@code this}
790     */
791    public final HttpClient setMaxRedirects(int maxRedirects) {
792        this.maxRedirects = maxRedirects;
793        return this;
794    }
795
796    /**
797     * Sets an arbitrary HTTP header.
798     * @param key header name
799     * @param value header value
800     *
801     * @return {@code this}
802     */
803    public final HttpClient setHeader(String key, String value) {
804        this.headers.put(key, value);
805        return this;
806    }
807
808    /**
809     * Sets arbitrary HTTP headers.
810     * @param headers HTTP headers
811     *
812     * @return {@code this}
813     */
814    public final HttpClient setHeaders(Map<String, String> headers) {
815        this.headers.putAll(headers);
816        return this;
817    }
818
819    /**
820     * Sets a reason to show on console. Can be {@code null} if no reason is given.
821     * @param reasonForRequest Reason to show
822     * @return {@code this}
823     * @since 9172
824     */
825    public final HttpClient setReasonForRequest(String reasonForRequest) {
826        this.reasonForRequest = reasonForRequest;
827        return this;
828    }
829
830    /**
831     * Sets the output message to be displayed in progress monitor for {@code PUT}, {@code POST} and {@code DELETE} methods.
832     * Defaults to "Uploading data ..." (translated). Has no effect for {@code GET} or any other method.
833     * @param outputMessage message to be displayed in progress monitor
834     * @return {@code this}
835     * @since 12711
836     */
837    public final HttpClient setOutputMessage(String outputMessage) {
838        this.outputMessage = outputMessage;
839        return this;
840    }
841
842    /**
843     * Sets whether the progress monitor task will be finished when the output stream is closed. This is {@code true} by default.
844     * @param finishOnCloseOutput whether the progress monitor task will be finished when the output stream is closed
845     * @return {@code this}
846     * @since 10302
847     */
848    public final HttpClient setFinishOnCloseOutput(boolean finishOnCloseOutput) {
849        this.finishOnCloseOutput = finishOnCloseOutput;
850        return this;
851    }
852
853    /**
854     * Sets the connect log at DEBUG level instead of the default INFO level.
855     * @param debug {@code true} to set the connect log at DEBUG level
856     * @return {@code this}
857     * @since 15389
858     */
859    public final HttpClient setLogAtDebug(boolean debug) {
860        this.debug = debug;
861        return this;
862    }
863
864    /**
865     * Determines if the given status code is an HTTP redirection.
866     * @param statusCode HTTP status code
867     * @return {@code true} if the given status code is an HTTP redirection
868     * @since 15423
869     */
870    public static boolean isRedirect(final int statusCode) {
871        switch (statusCode) {
872            case HttpURLConnection.HTTP_MOVED_PERM: // 301
873            case HttpURLConnection.HTTP_MOVED_TEMP: // 302
874            case HttpURLConnection.HTTP_SEE_OTHER: // 303
875            case 307: // TEMPORARY_REDIRECT:
876            case 308: // PERMANENT_REDIRECT:
877                return true;
878            default:
879                return false;
880        }
881    }
882
883    /**
884     * Disconnect client.
885     * @see HttpURLConnection#disconnect()
886     * @since 9309
887     */
888    public abstract void disconnect();
889
890    /**
891     * Returns a {@link Matcher} against predefined Tomcat error messages.
892     * If it matches, error message can be extracted from {@code group(1)}.
893     * @param data HTML contents to check
894     * @return a {@link Matcher} against predefined Tomcat error messages
895     * @since 13358
896     */
897    public static Matcher getTomcatErrorMatcher(String data) {
898        return data != null ? TOMCAT_ERR_MESSAGE.matcher(data) : null;
899    }
900}