1/*
2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/params/ConnRouteParams.java $
3 * $Revision: 658785 $
4 * $Date: 2008-05-21 10:47:40 -0700 (Wed, 21 May 2008) $
5 *
6 * ====================================================================
7 *
8 *  Licensed to the Apache Software Foundation (ASF) under one or more
9 *  contributor license agreements.  See the NOTICE file distributed with
10 *  this work for additional information regarding copyright ownership.
11 *  The ASF licenses this file to You under the Apache License, Version 2.0
12 *  (the "License"); you may not use this file except in compliance with
13 *  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, software
18 *  distributed under the License is distributed on an "AS IS" BASIS,
19 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20 *  See the License for the specific language governing permissions and
21 *  limitations under the License.
22 * ====================================================================
23 *
24 * This software consists of voluntary contributions made by many
25 * individuals on behalf of the Apache Software Foundation.  For more
26 * information on the Apache Software Foundation, please see
27 * <http://www.apache.org/>.
28 *
29 */
30
31package org.apache.http.conn.params;
32
33
34import java.net.InetAddress;
35
36import org.apache.http.HttpHost;
37import org.apache.http.params.HttpParams;
38import org.apache.http.conn.routing.HttpRoute;
39
40
41
42/**
43 * An adaptor for accessing route related parameters in {@link HttpParams}.
44 * See {@link ConnRoutePNames} for parameter name definitions.
45 *
46 * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
47 * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
48 *
49 * @version $Revision: 658785 $
50 *
51 * @since 4.0
52 */
53public class ConnRouteParams implements ConnRoutePNames {
54
55    /**
56     * A special value indicating "no host".
57     * This relies on a nonsense scheme name to avoid conflicts
58     * with actual hosts. Note that this is a <i>valid</i> host.
59     */
60    public static final HttpHost NO_HOST =
61        new HttpHost("127.0.0.255", 0, "no-host");
62
63    /**
64     * A special value indicating "no route".
65     * This is a route with {@link #NO_HOST} as the target.
66     */
67    public static final HttpRoute NO_ROUTE = new HttpRoute(NO_HOST);
68
69
70    /** Disabled default constructor. */
71    private ConnRouteParams() {
72        // no body
73    }
74
75
76    /**
77     * Obtains the {@link ConnRoutePNames#DEFAULT_PROXY DEFAULT_PROXY}
78     * parameter value.
79     * {@link #NO_HOST} will be mapped to <code>null</code>,
80     * to allow unsetting in a hierarchy.
81     *
82     * @param params    the parameters in which to look up
83     *
84     * @return  the default proxy set in the argument parameters, or
85     *          <code>null</code> if not set
86     */
87    public static HttpHost getDefaultProxy(HttpParams params) {
88        if (params == null) {
89            throw new IllegalArgumentException("Parameters must not be null.");
90        }
91        HttpHost proxy = (HttpHost)
92            params.getParameter(DEFAULT_PROXY);
93        if ((proxy != null) && NO_HOST.equals(proxy)) {
94            // value is explicitly unset
95            proxy = null;
96        }
97        return proxy;
98    }
99
100
101    /**
102     * Sets the {@link ConnRoutePNames#DEFAULT_PROXY DEFAULT_PROXY}
103     * parameter value.
104     *
105     * @param params    the parameters in which to set the value
106     * @param proxy     the value to set, may be <code>null</code>.
107     *                  Note that {@link #NO_HOST} will be mapped to
108     *                  <code>null</code> by {@link #getDefaultProxy},
109     *                  to allow for explicit unsetting in hierarchies.
110     */
111    public static void setDefaultProxy(HttpParams params,
112                                             HttpHost proxy) {
113        if (params == null) {
114            throw new IllegalArgumentException("Parameters must not be null.");
115        }
116        params.setParameter(DEFAULT_PROXY, proxy);
117    }
118
119
120    /**
121     * Obtains the {@link ConnRoutePNames#FORCED_ROUTE FORCED_ROUTE}
122     * parameter value.
123     * {@link #NO_ROUTE} will be mapped to <code>null</code>,
124     * to allow unsetting in a hierarchy.
125     *
126     * @param params    the parameters in which to look up
127     *
128     * @return  the forced route set in the argument parameters, or
129     *          <code>null</code> if not set
130     */
131    public static HttpRoute getForcedRoute(HttpParams params) {
132        if (params == null) {
133            throw new IllegalArgumentException("Parameters must not be null.");
134        }
135        HttpRoute route = (HttpRoute)
136            params.getParameter(FORCED_ROUTE);
137        if ((route != null) && NO_ROUTE.equals(route)) {
138            // value is explicitly unset
139            route = null;
140        }
141        return route;
142    }
143
144
145    /**
146     * Sets the {@link ConnRoutePNames#FORCED_ROUTE FORCED_ROUTE}
147     * parameter value.
148     *
149     * @param params    the parameters in which to set the value
150     * @param route     the value to set, may be <code>null</code>.
151     *                  Note that {@link #NO_ROUTE} will be mapped to
152     *                  <code>null</code> by {@link #getForcedRoute},
153     *                  to allow for explicit unsetting in hierarchies.
154     */
155    public static void setForcedRoute(HttpParams params,
156                                            HttpRoute route) {
157        if (params == null) {
158            throw new IllegalArgumentException("Parameters must not be null.");
159        }
160        params.setParameter(FORCED_ROUTE, route);
161    }
162
163
164    /**
165     * Obtains the {@link ConnRoutePNames#LOCAL_ADDRESS LOCAL_ADDRESS}
166     * parameter value.
167     * There is no special value that would automatically be mapped to
168     * <code>null</code>. You can use the wildcard address (0.0.0.0 for IPv4,
169     * :: for IPv6) to override a specific local address in a hierarchy.
170     *
171     * @param params    the parameters in which to look up
172     *
173     * @return  the local address set in the argument parameters, or
174     *          <code>null</code> if not set
175     */
176    public static InetAddress getLocalAddress(HttpParams params) {
177        if (params == null) {
178            throw new IllegalArgumentException("Parameters must not be null.");
179        }
180        InetAddress local = (InetAddress)
181            params.getParameter(LOCAL_ADDRESS);
182        // no explicit unsetting
183        return local;
184    }
185
186
187    /**
188     * Sets the {@link ConnRoutePNames#LOCAL_ADDRESS LOCAL_ADDRESS}
189     * parameter value.
190     *
191     * @param params    the parameters in which to set the value
192     * @param local     the value to set, may be <code>null</code>
193     */
194    public static void setLocalAddress(HttpParams params,
195                                             InetAddress local) {
196        if (params == null) {
197            throw new IllegalArgumentException("Parameters must not be null.");
198        }
199        params.setParameter(LOCAL_ADDRESS, local);
200    }
201
202}
203
204