View Javadoc

    1   /*
    2    * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/protocol/ProtocolSocketFactory.java,v 1.10 2004/05/13 04:01:22 mbecke Exp $
    3    * $Revision: 480424 $
    4    * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
    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 }