1/*
2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/scheme/Scheme.java $
3 * $Revision: 652950 $
4 * $Date: 2008-05-02 16:49:48 -0700 (Fri, 02 May 2008) $
5 *
6 * ====================================================================
7 * Licensed to the Apache Software Foundation (ASF) under one
8 * or more contributor license agreements.  See the NOTICE file
9 * distributed with this work for additional information
10 * regarding copyright ownership.  The ASF licenses this file
11 * to you under the Apache License, Version 2.0 (the
12 * "License"); you may not use this file except in compliance
13 * with the License.  You may obtain a copy of the License at
14 *
15 *   http://www.apache.org/licenses/LICENSE-2.0
16 *
17 * Unless required by applicable law or agreed to in writing,
18 * software distributed under the License is distributed on an
19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20 * KIND, either express or implied.  See the License for the
21 * specific language governing permissions and limitations
22 * under the License.
23 * ====================================================================
24 *
25 * This software consists of voluntary contributions made by many
26 * individuals on behalf of the Apache Software Foundation.  For more
27 * information on the Apache Software Foundation, please see
28 * <http://www.apache.org/>.
29 *
30 */
31package org.apache.http.conn.scheme;
32
33import java.util.Locale;
34
35import org.apache.http.util.LangUtils;
36
37/**
38 * Encapsulates specifics of a protocol scheme such as "http" or "https".
39 * Schemes are identified by lowercase names.
40 * Supported schemes are typically collected in a
41 * {@link SchemeRegistry SchemeRegistry}.
42 *
43 * <p>
44 * For example, to configure support for "https://" URLs,
45 * you could write code like the following:
46 * </p>
47 * <pre>
48 * Scheme https = new Scheme("https", new MySecureSocketFactory(), 443);
49 * SchemeRegistry.DEFAULT.register(https);
50 * </pre>
51 *
52 * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
53 * @author Michael Becke
54 * @author Jeff Dever
55 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
56 *
57 * @deprecated Please use {@link java.net.URL#openConnection} instead.
58 *     Please visit <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html">this webpage</a>
59 *     for further details.
60 */
61@Deprecated
62public final class Scheme {
63
64    /** The name of this scheme, in lowercase. (e.g. http, https) */
65    private final String name;
66
67    /** The socket factory for this scheme */
68    private final SocketFactory socketFactory;
69
70    /** The default port for this scheme */
71    private final int defaultPort;
72
73    /** Indicates whether this scheme allows for layered connections */
74    private final boolean layered;
75
76
77    /** A string representation, for {@link #toString toString}. */
78    private String stringRep;
79
80
81    /**
82     * Creates a new scheme.
83     * Whether the created scheme allows for layered connections
84     * depends on the class of <code>factory</code>.
85     *
86     * @param name      the scheme name, for example "http".
87     *                  The name will be converted to lowercase.
88     * @param factory   the factory for creating sockets for communication
89     *                  with this scheme
90     * @param port      the default port for this scheme
91     */
92    public Scheme(final String name,
93                  final SocketFactory factory,
94                  final int port) {
95
96        if (name == null) {
97            throw new IllegalArgumentException
98                ("Scheme name may not be null");
99        }
100        if (factory == null) {
101            throw new IllegalArgumentException
102                ("Socket factory may not be null");
103        }
104        if ((port <= 0) || (port > 0xffff)) {
105            throw new IllegalArgumentException
106                ("Port is invalid: " + port);
107        }
108
109        this.name = name.toLowerCase(Locale.ENGLISH);
110        this.socketFactory = factory;
111        this.defaultPort = port;
112        this.layered = (factory instanceof LayeredSocketFactory);
113    }
114
115
116    /**
117     * Obtains the default port.
118     *
119     * @return  the default port for this scheme
120     */
121    public final int getDefaultPort() {
122        return defaultPort;
123    }
124
125
126    /**
127     * Obtains the socket factory.
128     * If this scheme is {@link #isLayered layered}, the factory implements
129     * {@link LayeredSocketFactory LayeredSocketFactory}.
130     *
131     * @return  the socket factory for this scheme
132     */
133    public final SocketFactory getSocketFactory() {
134        return socketFactory;
135    }
136
137
138    /**
139     * Obtains the scheme name.
140     *
141     * @return  the name of this scheme, in lowercase
142     */
143    public final String getName() {
144        return name;
145    }
146
147
148    /**
149     * Indicates whether this scheme allows for layered connections.
150     *
151     * @return <code>true</code> if layered connections are possible,
152     *         <code>false</code> otherwise
153     */
154    public final boolean isLayered() {
155        return layered;
156    }
157
158
159    /**
160     * Resolves the correct port for this scheme.
161     * Returns the given port if it is valid, the default port otherwise.
162     *
163     * @param port      the port to be resolved,
164     *                  a negative number to obtain the default port
165     *
166     * @return the given port or the defaultPort
167     */
168    public final int resolvePort(int port) {
169        return ((port <= 0) || (port > 0xffff)) ? defaultPort : port;
170    }
171
172
173    /**
174     * Return a string representation of this object.
175     *
176     * @return  a human-readable string description of this scheme
177     */
178    @Override
179    public final String toString() {
180        if (stringRep == null) {
181            StringBuilder buffer = new StringBuilder();
182            buffer.append(this.name);
183            buffer.append(':');
184            buffer.append(Integer.toString(this.defaultPort));
185            stringRep = buffer.toString();
186        }
187        return stringRep;
188    }
189
190
191    /**
192     * Compares this scheme to an object.
193     *
194     * @param obj       the object to compare with
195     *
196     * @return  <code>true</code> iff the argument is equal to this scheme
197     */
198    @Override
199    public final boolean equals(Object obj) {
200        if (obj == null) return false;
201        if (this == obj) return true;
202        if (!(obj instanceof Scheme)) return false;
203
204        Scheme s = (Scheme) obj;
205        return (name.equals(s.name) &&
206                defaultPort == s.defaultPort &&
207                layered == s.layered &&
208                socketFactory.equals(s.socketFactory)
209                );
210    } // equals
211
212
213    /**
214     * Obtains a hash code for this scheme.
215     *
216     * @return  the hash code
217     */
218    @Override
219    public int hashCode() {
220        int hash = LangUtils.HASH_SEED;
221        hash = LangUtils.hashCode(hash, this.defaultPort);
222        hash = LangUtils.hashCode(hash, this.name);
223        hash = LangUtils.hashCode(hash, this.layered);
224        hash = LangUtils.hashCode(hash, this.socketFactory);
225        return hash;
226    }
227
228} // class Scheme
229