View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/protocol/ProtocolSocketFactory.java $
3    * $Revision: 1425331 $
4    * $Date: 2012-12-22 18:29:41 +0000 (Sat, 22 Dec 2012) $
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  
31  package org.apache.commons.httpclient.protocol;
32  
33  import java.io.IOException;
34  import java.net.InetAddress;
35  import java.net.Socket;
36  import java.net.UnknownHostException;
37  
38  import org.apache.commons.httpclient.ConnectTimeoutException;
39  import org.apache.commons.httpclient.params.HttpConnectionParams;
40  
41  /***
42   * A factory for creating Sockets.
43   * 
44   * <p>Both {@link java.lang.Object#equals(java.lang.Object) Object.equals()} and 
45   * {@link java.lang.Object#hashCode() Object.hashCode()} should be overridden appropriately.  
46   * Protocol socket factories are used to uniquely identify <code>Protocol</code>s and 
47   * <code>HostConfiguration</code>s, and <code>equals()</code> and <code>hashCode()</code> are 
48   * required for the correct operation of some connection managers.</p>
49   * 
50   * @see Protocol
51   * 
52   * @author Michael Becke
53   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
54   * 
55   * @since 2.0
56   */
57  public interface ProtocolSocketFactory {
58  
59      /***
60       * Gets a new socket connection to the given host.
61       * 
62       * @param host the host name/IP
63       * @param port the port on the host
64       * @param localAddress the local host name/IP to bind the socket to
65       * @param localPort the port on the local machine
66       * 
67       * @return Socket a new socket
68       * 
69       * @throws IOException if an I/O error occurs while creating the socket
70       * @throws UnknownHostException if the IP address of the host cannot be
71       * determined
72       */
73      Socket createSocket(
74          String host, 
75          int port, 
76          InetAddress localAddress, 
77          int localPort
78      ) throws IOException, UnknownHostException;
79  
80      /***
81       * Gets a new socket connection to the given host.
82       * 
83       * @param host the host name/IP
84       * @param port the port on the host
85       * @param localAddress the local host name/IP to bind the socket to
86       * @param localPort the port on the local machine
87       * @param params {@link HttpConnectionParams Http connection parameters}
88       * 
89       * @return Socket a new socket
90       * 
91       * @throws IOException if an I/O error occurs while creating the socket
92       * @throws UnknownHostException if the IP address of the host cannot be
93       * determined
94       * @throws ConnectTimeoutException if socket cannot be connected within the
95       *  given time limit
96       * 
97       * @since 3.0
98       */
99      Socket createSocket(
100         String host, 
101         int port, 
102         InetAddress localAddress, 
103         int localPort,
104         HttpConnectionParams params
105     ) throws IOException, UnknownHostException, ConnectTimeoutException;
106 
107     /***
108      * Gets a new socket connection to the given host.
109      *
110      * @param host the host name/IP
111      * @param port the port on the host
112      *
113      * @return Socket a new socket
114      *
115      * @throws IOException if an I/O error occurs while creating the socket
116      * @throws UnknownHostException if the IP address of the host cannot be
117      * determined
118      */
119     Socket createSocket(
120         String host, 
121         int port
122     ) throws IOException, UnknownHostException;
123 
124 }