1   /*
    2    * $HeadURL: https://svn.apache.org/repos/asf/jakarta/httpcomponents/httpcore/tags/4.0-alpha2/src/java/org/apache/http/io/SocketFactory.java $
    3    * $Revision: 321379 $
    4    * $Date: 2005-10-15 19:07:11 +0200 (Sat, 15 Oct 2005) $
    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.http.io;
   31   
   32   import java.io.IOException;
   33   import java.net.InetAddress;
   34   import java.net.Socket;
   35   import java.net.UnknownHostException;
   36   
   37   import org.apache.http.ConnectTimeoutException;
   38   import org.apache.http.Scheme;
   39   import org.apache.http.params.HttpParams;
   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 Scheme
   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 SocketFactory {
   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        * @param params {@link HttpParams Http parameters}
   67        * 
   68        * @return Socket a new socket
   69        * 
   70        * @throws IOException if an I/O error occurs while creating the socket
   71        * @throws UnknownHostException if the IP address of the host cannot be
   72        * determined
   73        * @throws ConnectTimeoutException if socket cannot be connected within the
   74        *  given time limit
   75        * 
   76        * @since 3.0
   77        */
   78       Socket createSocket(
   79           String host, 
   80           int port, 
   81           InetAddress localAddress, 
   82           int localPort,
   83           HttpParams params
   84       ) throws IOException, UnknownHostException, ConnectTimeoutException;
   85   
   86   }