View Javadoc

1   /*
2    * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HostConfiguration.java,v 1.21 2004/11/03 18:24:44 olegk Exp $
3    * $Revision: 1.21 $
4    * $Date: 2004/11/03 18:24:44 $
5    *
6    * ====================================================================
7    *
8    *  Copyright 2002-2004 The Apache Software Foundation
9    *
10   *  Licensed under the Apache License, Version 2.0 (the "License");
11   *  you may not use this file except in compliance with the License.
12   *  You may obtain a copy of the License at
13   *
14   *      http://www.apache.org/licenses/LICENSE-2.0
15   *
16   *  Unless required by applicable law or agreed to in writing, software
17   *  distributed under the License is distributed on an "AS IS" BASIS,
18   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19   *  See the License for the specific language governing permissions and
20   *  limitations under the License.
21   * ====================================================================
22   *
23   * This software consists of voluntary contributions made by many
24   * individuals on behalf of the Apache Software Foundation.  For more
25   * information on the Apache Software Foundation, please see
26   * <http://www.apache.org/>.
27   *
28   */
29  
30  package org.apache.commons.httpclient;
31  
32  import org.apache.commons.httpclient.params.HostParams;
33  import org.apache.commons.httpclient.protocol.Protocol;
34  
35  import java.net.InetAddress;
36  
37  /***
38   * Holds all of the variables needed to describe an HTTP connection to a host.  This includes 
39   * remote host, port and protocol, proxy host and port, local address, and virtual host.
40   * 
41   * @author <a href="mailto:becke@u.washington.edu">Michael Becke</a>
42   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
43   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
44   * @author Laura Werner
45   * 
46   * @since 2.0 
47   */
48  public class HostConfiguration implements Cloneable {
49  
50      /***
51       * A value to represent any host configuration, instead of using something like
52       * <code>null</code>. This value should be treated as immutable and only used in 
53       * lookups and other such places to represent "any" host config.
54       */
55      public static final HostConfiguration ANY_HOST_CONFIGURATION = new HostConfiguration();
56  
57      /*** The host to use. */
58      private HttpHost host = null;
59  
60      /*** The host name of the proxy server */
61      private ProxyHost proxyHost = null;
62  
63      /*** The local address to use when creating the socket, or null to use the default */
64      private InetAddress localAddress = null;
65  
66      /*** Parameters specific to this host */
67      private HostParams params = new HostParams();
68  
69      /***
70       * Constructor for HostConfiguration.
71       */
72      public HostConfiguration() {
73          super();
74      }
75      
76      /***
77       * Copy constructor for HostConfiguration
78       * 
79       * @param hostConfiguration the hostConfiguration to copy
80       */
81      public HostConfiguration (final HostConfiguration hostConfiguration) {
82          // wrap all of the assignments in a synchronized block to avoid
83          // having to negotiate the monitor for each method call
84          synchronized (hostConfiguration) {
85              try {
86                  if (hostConfiguration.host != null) {
87                      this.host = (HttpHost) hostConfiguration.host.clone();
88                  } else {
89                      this.host = null;
90                  }
91                  if (hostConfiguration.proxyHost != null) {
92                      this.proxyHost = (ProxyHost) hostConfiguration.proxyHost.clone();
93                  } else {
94                      this.proxyHost = null;
95                  }
96                  this.localAddress = hostConfiguration.getLocalAddress();
97                  this.params = (HostParams)hostConfiguration.getParams().clone();
98              } catch (CloneNotSupportedException e) {
99                  throw new IllegalArgumentException("Host configuration could not be cloned");
100             }
101         }        
102     }
103 
104     /***
105      * @see java.lang.Object#clone()
106      */
107     public Object clone() {
108         return new HostConfiguration(this);
109     }    
110     
111     /***
112      * @see java.lang.Object#toString()
113      */
114     public synchronized String toString() {
115         
116         boolean appendComma = false;
117         StringBuffer b = new StringBuffer(50);        
118         b.append("HostConfiguration[");
119         
120         if (this.host != null) {
121             appendComma = true;
122             b.append("host=").append(this.host);
123         }
124         if (this.proxyHost != null) {
125             if (appendComma) {
126                 b.append(", ");
127             } else {
128                 appendComma = true;
129             }
130             b.append("proxyHost=").append(this.proxyHost);
131         }
132         if (this.localAddress != null) {
133             if (appendComma) {
134                 b.append(", ");
135             } else {
136                 appendComma = true;
137             }
138             b.append("localAddress=").append(this.localAddress);
139             if (appendComma) {
140                 b.append(", ");
141             } else {
142                 appendComma = true;
143             }
144             b.append("params=").append(this.params);
145         }
146         b.append("]");
147         return b.toString();
148     }    
149     
150     /***
151      * Tests if the host configuration equals the configuration set on the
152      * connection. True only if the host, port, protocol, local address and virtual address
153      * are equal.  If no host configuration has been set false will be returned.
154      * 
155      * @param connection the connection to test against
156      * @return <code>true</code> if the connection's host information equals that of this
157      * configuration
158      * 
159      * @see #proxyEquals(HttpConnection)
160      */
161     public synchronized boolean hostEquals(final HttpConnection connection) {
162         if (connection == null) {
163             throw new IllegalArgumentException("Connection may not be null");
164         }
165         if (this.host != null) {
166             if (!this.host.getHostName().equalsIgnoreCase(connection.getHost())) {
167                 return false;
168             }
169             if (this.host.getPort() != connection.getPort()) {
170                 return false;
171             }
172             if (!this.host.getProtocol().equals(connection.getProtocol())) {
173                 return false;
174             }
175             if (this.localAddress != null) {
176                 if (!this.localAddress.equals(connection.getLocalAddress())) {
177                     return false;
178                 }
179             } else {
180                 if (connection.getLocalAddress() != null) {
181                     return false; 
182                 }
183             }
184             return true;
185         } else {
186             return false;   
187         }
188     }
189 
190     /***
191      * Tests if the proxy configuration equals the configuration set on the
192      * connection. True only if the proxyHost and proxyPort are equal.
193      *
194      * @param connection the connection to test against
195      * @return <code>true</code> if the connection's proxy information equals that of this
196      * configuration
197      *
198      * @see #hostEquals(HttpConnection)
199      */
200     public synchronized boolean proxyEquals(final HttpConnection connection) {
201         if (connection == null) {
202             throw new IllegalArgumentException("Connection may not be null");
203         }
204         if (this.proxyHost != null) {
205             return
206                 this.proxyHost.getHostName().equalsIgnoreCase(connection.getProxyHost())
207                 && this.proxyHost.getPort() == connection.getProxyPort();
208         } else {
209             return connection.getProxyHost() == null;
210         }
211     }    
212     
213     /***
214      * Returns true if the host is set.
215      * @return <code>true</code> if the host is set.
216      * 
217      * @deprecated no longer used
218      */
219     public synchronized boolean isHostSet() {
220         return this.host != null;
221     }
222 
223     /***
224      * Sets the given host
225      * 
226      * @param host the host
227      */
228     public synchronized void setHost(final HttpHost host) {
229         this.host = host;
230     }
231     
232     /***
233      * Sets the given host, port and protocol
234      * 
235      * @param host the host(IP or DNS name)
236      * @param port The port
237      * @param protocol The protocol.
238      */
239     public synchronized void setHost(final String host, int port, final String protocol) {
240         this.host = new HttpHost(host, port, Protocol.getProtocol(protocol));
241     }
242     
243     /***
244      * Sets the given host, virtual host, port and protocol.
245      * 
246      * @param host the host(IP or DNS name)
247      * @param virtualHost the virtual host name or <code>null</code>
248      * @param port the host port or -1 to use protocol default
249      * @param protocol the protocol
250      * 
251      * @deprecated #setHost(String, int, Protocol)
252      */
253     public synchronized void setHost(final String host, final String virtualHost, int port, 
254         final Protocol protocol) {
255         setHost(host, port, protocol);
256         this.params.setVirtualHost(virtualHost);
257     }
258 
259     /***
260      * Sets the given host, port and protocol.
261      *   
262      * @param host the host(IP or DNS name)
263      * @param port The port
264      * @param protocol the protocol
265      */
266     public synchronized void setHost(final String host, int port, final Protocol protocol) {
267         if (host == null) {
268             throw new IllegalArgumentException("host must not be null");   
269         }
270         if (protocol == null) {
271             throw new IllegalArgumentException("protocol must not be null");   
272         }
273         this.host = new HttpHost(host, port, protocol);
274     }
275 
276     /***
277      * Sets the given host and port.  Uses the default protocol "http".
278      * 
279      * @param host the host(IP or DNS name)
280      * @param port The port
281      */
282     public synchronized void setHost(final String host, int port) {
283         setHost(host, port, Protocol.getProtocol("http"));
284     }
285     
286     /***
287      * Set the given host. Uses the default protocol("http") and its port.
288      * 
289      * @param host The host(IP or DNS name).
290      */
291     public synchronized void setHost(final String host) {
292         Protocol defaultProtocol = Protocol.getProtocol("http"); 
293         setHost(host, null, defaultProtocol.getDefaultPort(), defaultProtocol);
294     }
295     
296     /***
297      * Sets the protocol, host and port from the given URI.
298      * @param uri the URI.
299      */
300     public synchronized void setHost(final URI uri) {
301         try {
302             setHost(uri.getHost(), uri.getPort(), uri.getScheme());
303         } catch (URIException e) {
304             throw new IllegalArgumentException(e.toString());
305         }
306     }
307 
308     /***
309      * Return the host url.
310      * 
311      * @return The host url.
312      */
313     public synchronized String getHostURL() {
314         if (this.host == null) {
315             throw new IllegalStateException("Host must be set to create a host URL");   
316         } else {
317             return this.host.toURI();
318         }
319     }
320 
321     /***
322      * Returns the host.
323      * 
324      * @return the host(IP or DNS name), or <code>null</code> if not set
325      * 
326      * @see #isHostSet()
327      */
328     public synchronized String getHost() {
329         if (this.host != null) {
330             return this.host.getHostName();
331         } else {
332             return null;
333         }
334     }
335 
336     /***
337      * Returns the virtual host.
338      * 
339      * @return the virtual host name, or <code>null</code> if not set
340      * 
341      * @deprecated use HostParams
342      */
343     public synchronized String getVirtualHost() {
344     	return this.params.getVirtualHost();
345     }
346 
347     /***
348      * Returns the port.
349      * 
350      * @return the host port, or <code>-1</code> if not set
351      * 
352      * @see #isHostSet()
353      */
354     public synchronized int getPort() {
355         if (this.host != null) {
356             return this.host.getPort();
357         } else {
358             return -1;
359         }
360     }
361 
362     /***
363      * Returns the protocol.
364      * @return The protocol.
365      */
366     public synchronized Protocol getProtocol() {
367         if (this.host != null) {
368             return this.host.getProtocol();
369         } else {
370             return null;
371         }
372     }
373 
374     /***
375      * Tests if the proxy host/port have been set.
376      * 
377      * @return <code>true</code> if a proxy server has been set.
378      * 
379      * @see #setProxy(String, int)
380      * 
381      * @deprecated no longer used
382      */    
383     public synchronized boolean isProxySet() {
384         return this.proxyHost != null;   
385     }
386 
387     /***
388      * Sets the given proxy host
389      * 
390      * @param host the proxy host
391      */
392     public synchronized void setProxyHost(final ProxyHost proxyHost) {
393         this.proxyHost = proxyHost;
394     }
395     
396     /***
397      * Set the proxy settings.
398      * @param proxyHost The proxy host
399      * @param proxyPort The proxy port
400      */
401     public synchronized void setProxy(final String proxyHost, int proxyPort) {
402         this.proxyHost = new ProxyHost(proxyHost, proxyPort); 
403     }
404 
405     /***
406      * Returns the proxyHost.
407      * 
408      * @return the proxy host, or <code>null</code> if not set
409      * 
410      * @see #isProxySet()
411      */
412     public synchronized String getProxyHost() {
413         if (this.proxyHost != null) {
414             return this.proxyHost.getHostName();
415         } else {
416             return null;
417         }
418     }
419 
420     /***
421      * Returns the proxyPort.
422      * 
423      * @return the proxy port, or <code>-1</code> if not set
424      * 
425      * @see #isProxySet()
426      */
427     public synchronized int getProxyPort() {
428         if (this.proxyHost != null) {
429             return this.proxyHost.getPort();
430         } else {
431             return -1;
432         }
433     }
434 
435     /***
436      * Set the local address to be used when creating connections.
437      * If this is unset, the default address will be used.
438      * This is useful for specifying the interface to use on multi-homed or clustered systems.
439      * 
440      * @param localAddress the local address to use
441      */
442     
443     public synchronized void setLocalAddress(InetAddress localAddress) {
444         this.localAddress = localAddress;
445     }
446 
447     /***
448      * Return the local address to be used when creating connections.
449      * If this is unset, the default address should be used.
450      * 
451      * @return the local address to be used when creating Sockets, or <code>null</code>
452      */
453     
454     public synchronized InetAddress getLocalAddress() {
455         return this.localAddress;
456     }
457     
458     /***
459      * Returns {@link HostParams HTTP protocol parameters} associated with this host.
460      *
461      * @return HTTP parameters.
462      *
463      * @since 3.0
464      */
465     public HostParams getParams() {
466         return this.params;
467     }
468 
469     /***
470      * Assigns {@link HostParams HTTP protocol parameters} specific to this host.
471      * 
472      * @since 3.0
473      * 
474      * @see HostParams
475      */
476     public void setParams(final HostParams params) {
477         if (params == null) {
478             throw new IllegalArgumentException("Parameters may not be null");
479         }
480         this.params = params;
481     }
482 
483     /***
484      * @see java.lang.Object#equals(java.lang.Object)
485      */
486     public synchronized boolean equals(final Object o) {
487         
488         if (o instanceof HostConfiguration) {
489             
490             // shortcut if we're comparing with ourselves
491             if (o == this) { 
492                 return true;
493             }
494             
495             HostConfiguration that = (HostConfiguration) o;
496             
497             if (this.host != null) {
498                 if (!this.host.equals(that.host)) {
499                     return false;
500                 }
501             } else {
502                 if (that.host != null) {
503                     return false;
504                 }
505             }
506             if (this.proxyHost != null) {
507                 if (!this.proxyHost.equals(that.proxyHost)) {
508                     return false;
509                 }
510             } else {
511                 if (that.proxyHost != null) {
512                     return false;
513                 }
514             }
515             if (localAddress != null) {
516                 if (!localAddress.equals(that.getLocalAddress())) {
517                     return false;
518                 }
519             } else {
520                 if (that.getLocalAddress() != null) {
521                     return false; 
522                 }
523             }
524             // everything matches
525             return true;
526         } else {
527             return false;
528         }
529         
530     }
531 
532     /***
533      * @see java.lang.Object#hashCode()
534      */
535     public int hashCode() {
536         if (host != null) {
537             return host.hashCode();
538         } else if (proxyHost != null) {
539             return proxyHost.hashCode();   
540         } else {
541             return super.hashCode();
542         }
543     }
544 
545 }