1/*
2 * Copyright (c) 2003, 2013, 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
26package java.net;
27
28/**
29 * This class represents a proxy setting, typically a type (http, socks) and
30 * a socket address.
31 * A {@code Proxy} is an immutable object.
32 *
33 * @see     java.net.ProxySelector
34 * @author Yingxian Wang
35 * @author Jean-Christophe Collet
36 * @since   1.5
37 */
38public class Proxy {
39
40    /**
41     * Represents the proxy type.
42     *
43     * @since 1.5
44     */
45    public enum Type {
46        /**
47         * Represents a direct connection, or the absence of a proxy.
48         */
49        DIRECT,
50        /**
51         * Represents proxy for high level protocols such as HTTP or FTP.
52         */
53        HTTP,
54        /**
55         * Represents a SOCKS (V4 or V5) proxy.
56         */
57        SOCKS
58    };
59
60    private Type type;
61    private SocketAddress sa;
62
63    /**
64     * A proxy setting that represents a {@code DIRECT} connection,
65     * basically telling the protocol handler not to use any proxying.
66     * Used, for instance, to create sockets bypassing any other global
67     * proxy settings (like SOCKS):
68     * <P>
69     * {@code Socket s = new Socket(Proxy.NO_PROXY);}
70     *
71     */
72    public static final Proxy NO_PROXY = new Proxy();
73
74    // Creates the proxy that represents a {@code DIRECT} connection.
75    private Proxy() {
76        type = Type.DIRECT;
77        sa = null;
78    }
79
80    /**
81     * Creates an entry representing a PROXY connection.
82     * Certain combinations are illegal. For instance, for types Http, and
83     * Socks, a SocketAddress <b>must</b> be provided.
84     * <P>
85     * Use the {@code Proxy.NO_PROXY} constant
86     * for representing a direct connection.
87     *
88     * @param type the {@code Type} of the proxy
89     * @param sa the {@code SocketAddress} for that proxy
90     * @throws IllegalArgumentException when the type and the address are
91     * incompatible
92     */
93    public Proxy(Type type, SocketAddress sa) {
94        if ((type == Type.DIRECT) || !(sa instanceof InetSocketAddress))
95            throw new IllegalArgumentException("type " + type + " is not compatible with address " + sa);
96        this.type = type;
97        this.sa = sa;
98    }
99
100    /**
101     * Returns the proxy type.
102     *
103     * @return a Type representing the proxy type
104     */
105    public Type type() {
106        return type;
107    }
108
109    /**
110     * Returns the socket address of the proxy, or
111     * {@code null} if its a direct connection.
112     *
113     * @return a {@code SocketAddress} representing the socket end
114     *         point of the proxy
115     */
116    public SocketAddress address() {
117        return sa;
118    }
119
120    /**
121     * Constructs a string representation of this Proxy.
122     * This String is constructed by calling toString() on its type
123     * and concatenating " @ " and the toString() result from its address
124     * if its type is not {@code DIRECT}.
125     *
126     * @return  a string representation of this object.
127     */
128    public String toString() {
129        if (type() == Type.DIRECT)
130            return "DIRECT";
131        return type() + " @ " + address();
132    }
133
134        /**
135     * Compares this object against the specified object.
136     * The result is {@code true} if and only if the argument is
137     * not {@code null} and it represents the same proxy as
138     * this object.
139     * <p>
140     * Two instances of {@code Proxy} represent the same
141     * address if both the SocketAddresses and type are equal.
142     *
143     * @param   obj   the object to compare against.
144     * @return  {@code true} if the objects are the same;
145     *          {@code false} otherwise.
146     * @see java.net.InetSocketAddress#equals(java.lang.Object)
147     */
148    public final boolean equals(Object obj) {
149        if (obj == null || !(obj instanceof Proxy))
150            return false;
151        Proxy p = (Proxy) obj;
152        if (p.type() == type()) {
153            if (address() == null) {
154                return (p.address() == null);
155            } else
156                return address().equals(p.address());
157        }
158        return false;
159    }
160
161    /**
162     * Returns a hashcode for this Proxy.
163     *
164     * @return  a hash code value for this Proxy.
165     */
166    public final int hashCode() {
167        if (address() == null)
168            return type().hashCode();
169        return type().hashCode() + address().hashCode();
170    }
171}
172