    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017
    018package org.apache.commons.configuration2.io;
    019
    020import java.io.IOException;
    021import java.net.URL;
    022import java.net.URLConnection;
    023import java.util.Objects;
    024
    025/**
    026 * Carries options and operates on {@link URLConnection}.
    027 *
    028 * @since 2.8.0
    029 */
    030public final class URLConnectionOptions {
    031
    032    /**
    033     * Default options.
    034     */
    035    public static final URLConnectionOptions DEFAULT = new URLConnectionOptions();
    036
    037    /**
    038     * Tells if user interaction, sicj as displaying an authentication dialog, is allowed.
    039     */
    040    private boolean allowUserInteraction;
    041
    042    /**
    043     * The connect timeout in milliseconds.
    044     */
    045    private int connectTimeoutMillis;
    046
    047    /**
    048     * The read timeout in milliseconds.
    049     */
    050    private int readTimeoutMillis;
    051
    052    /**
    053     * Tells if the connection should use caches.
    054     */
    055    private boolean useCaches = true;
    056
    057    /**
    058     * Constructs a new default instance.
    059     */
    060    public URLConnectionOptions() {
    061        // Defaults initialized in declarations.
    062    }
    063
    064    /**
    065     * Constructs an instance with values from the given URLConnectionOptions.
    066     *
    067     * @param urlConnectionOptions the source
    068     */
    069    public URLConnectionOptions(final URLConnectionOptions urlConnectionOptions) {
    070        this.allowUserInteraction = urlConnectionOptions.getAllowUserInteraction();
    071        this.useCaches = urlConnectionOptions.getUseCaches();
    072        this.connectTimeoutMillis = urlConnectionOptions.getConnectTimeoutMillis();
    073        this.readTimeoutMillis = urlConnectionOptions.getReadTimeoutMillis();
    074    }
    075
    076    /**
    077     * Applies the options to the given connection.
    078     *
    079     * @param urlConnection the target connection.
    080     * @return the given connection.
    081     */
    082    public URLConnection apply(final URLConnection urlConnection) {
    083        urlConnection.setUseCaches(useCaches);
    084        urlConnection.setConnectTimeout(connectTimeoutMillis);
    085        urlConnection.setReadTimeout(readTimeoutMillis);
    086        return urlConnection;
    087    }
    088
    089    @Override
    090    public boolean equals(final Object obj) {
    091        if (this == obj) {
    092            return true;
    093        }
    094        if (!(obj instanceof URLConnectionOptions)) {
    095            return false;
    096        }
    097        final URLConnectionOptions other = (URLConnectionOptions) obj;
    098        return allowUserInteraction == other.allowUserInteraction && connectTimeoutMillis == other.connectTimeoutMillis
    099            && readTimeoutMillis == other.readTimeoutMillis && useCaches == other.useCaches;
    100    }
    101
    102    /**
    103     * Gets whether to allow user interaction.
    104     *
    105     * @return whether to allow user interaction.
    106     */
    107    public boolean getAllowUserInteraction() {
    108        return allowUserInteraction;
    109    }
    110
    111    /**
    112     * Gets the connect timeout.
    113     *
    114     * @return the connect timeout.
    115     */
    116    public int getConnectTimeoutMillis() {
    117        return connectTimeoutMillis;
    118    }
    119
    120    /**
    121     * Gets the read timeout.
    122     *
    123     * @return the read timeout.
    124     */
    125    public int getReadTimeoutMillis() {
    126        return readTimeoutMillis;
    127    }
    128
    129    /**
    130     * Gets whether to cache.
    131     *
    132     * @return Whether to cache.
    133     */
    134    public boolean getUseCaches() {
    135        return useCaches;
    136    }
    137
    138    @Override
    139    public int hashCode() {
    140        return Objects.hash(allowUserInteraction, connectTimeoutMillis, readTimeoutMillis, useCaches);
    141    }
    142
    143    /**
    144     * Opens a connection for the given URL with our options.
    145     *
    146     * @param url the URL to open
    147     * @return A new connection
    148     * @throws IOException if an I/O exception occurs.
    149     */
    150    public URLConnection openConnection(final URL url) throws IOException {
    151        return apply(url.openConnection());
    152    }
    153
    154    public URLConnectionOptions setAllowUserInteraction(final boolean allowUserInteraction) {
    155        this.allowUserInteraction = allowUserInteraction;
    156        return this;
    157    }
    158
    159    public URLConnectionOptions setConnectTimeoutMillis(final int connectTimeoutMillis) {
    160        this.connectTimeoutMillis = connectTimeoutMillis;
    161        return this;
    162    }
    163
    164    public URLConnectionOptions setReadTimeoutMillis(final int readTimeoutMillis) {
    165        this.readTimeoutMillis = readTimeoutMillis;
    166        return this;
    167    }
    168
    169    public URLConnectionOptions setUseCaches(final boolean useCaches) {
    170        this.useCaches = useCaches;
    171        return this;
    172    }
    173
    174    @Override
    175    public String toString() {
    176        return "URLConnectionOptions [allowUserInteraction=" + allowUserInteraction + ", connectTimeoutMillis=" + connectTimeoutMillis + ", readTimeoutMillis="
    177            + readTimeoutMillis + ", useCaches=" + useCaches + "]";
    178    }
    179}