xref: /libcore/luni/src/main/java/java/net/Proxy.java

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package java.net;

/**
 * This class represents proxy server settings. A created instance of {@code
 * Proxy} stores a type and an address and is immutable. There are three types
 * of proxies:
 * <ul>
 * <li>DIRECT</li>
 * <li>HTTP</li>
 * <li>SOCKS</li></ul
 */
public class Proxy {

    /**
     * Represents the proxy type setting {@code Proxy.Type.DIRECT}. It tells
     * protocol handlers that there is no proxy to be used. The address is set
     * to {@code null}.
     */
    public static final Proxy NO_PROXY = new Proxy();

    private Proxy.Type type;

    private SocketAddress address;

    /**
     * Creates a new {@code Proxy} instance. {@code SocketAddress} must NOT be
     * {@code null} when {@code type} is either {@code Proxy.Type.HTTP} or
     * {@code Proxy.Type.SOCKS}. To create a {@code Proxy} instance representing
     * the proxy type {@code Proxy.Type.DIRECT}, use {@code Proxy.NO_PROXY}
     * instead of this constructor.
     *
     * @param type
     *            the proxy type of this instance.
     * @param sa
     *            the proxy address of this instance.
     * @throws IllegalArgumentException
     *             if the parameter {@code type} is set to {@code
     *             Proxy.Type.DIRECT} or the value for {@code SocketAddress} is
     *             {@code null}.
     */
    public Proxy(Proxy.Type type, SocketAddress sa) {
        /*
         * Don't use DIRECT type to construct a proxy instance directly.
         * SocketAddress must NOT be null.
         */
        if (type == Type.DIRECT || sa == null) {
            throw new IllegalArgumentException("Illegal Proxy.Type or SocketAddress argument");
        }
        this.type = type;
        address = sa;
    }

    /*
     * Constructs a Proxy instance, which is Proxy.DIRECT type with null
     * SocketAddress. This constructor is used for NO_PROXY.
     */
    private Proxy() {
        type = Type.DIRECT;
        address = null;
    }

    /**
     * Gets the type of this {@code Proxy} instance.
     *
     * @return the stored proxy type.
     */
    public Proxy.Type type() {
        return type;
    }

    /**
     * Gets the address of this {@code Proxy} instance.
     *
     * @return the stored proxy address or {@code null} if the proxy type is
     *         {@code DIRECT}.
     */
    public SocketAddress address() {
        return address;
    }

    /**
     * Gets a textual representation of this {@code Proxy} instance. The string
     * includes the two parts {@code type.toString()} and {@code
     * address.toString()} if {@code address} is not {@code null}.
     *
     * @return the representing string of this proxy.
     */
    @Override
    public String toString() {
        StringBuilder builder = new StringBuilder();
        if (type != null) {
            builder.append(type.toString());
        }
        builder.append("@");
        if (type != Proxy.Type.DIRECT && address != null) {
            builder.append(address.toString());
        }
        return builder.toString();
    }

    /**
     * Compares the specified {@code obj} to this {@code Proxy} instance and
     * returns whether they are equal or not. The given object must be an
     * instance of {@code Proxy} with the same address and the same type value
     * to be equal.
     *
     * @param obj
     *            the object to compare with this instance.
     * @return {@code true} if the given object represents the same {@code
     *         Proxy} as this instance, {@code false} otherwise.
     * @see #hashCode
     */
    @Override
    public final boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (!(obj instanceof Proxy)) {
            return false;
        }
        Proxy another = (Proxy) obj;
        // address is null when and only when it's NO_PROXY.
        return (type == another.type) && address.equals(another.address);
    }

    /**
     * Gets the hashcode for this {@code Proxy} instance.
     *
     * @return the hashcode value for this Proxy instance.
     */
    @Override
    public final int hashCode() {
        int ret = 0;
        ret += type.hashCode();
        if (address != null) {
            ret += address.hashCode();
        }
        return ret;
    }

    /**
     * {@code Enum} class for the proxy type. Possible options are {@code
     * DIRECT}, {@code HTTP} and {@code SOCKS}.
     */
    public enum Type {
        /**
         * Direct connection. Connect without any proxy.
         */
        DIRECT,

        /**
         * HTTP type proxy. It's often used by protocol handlers such as HTTP,
         * HTTPS and FTP.
         */
        HTTP,

        /**
         * SOCKS type proxy.
         */
        SOCKS
    }
}