Home | History | Annotate | Download | only in scheme
      1 /*
      2  * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/scheme/SocketFactory.java $
      3  * $Revision: 645850 $
      4  * $Date: 2008-04-08 04:08:52 -0700 (Tue, 08 Apr 2008) $
      5  *
      6  * ====================================================================
      7  * Licensed to the Apache Software Foundation (ASF) under one
      8  * or more contributor license agreements.  See the NOTICE file
      9  * distributed with this work for additional information
     10  * regarding copyright ownership.  The ASF licenses this file
     11  * to you under the Apache License, Version 2.0 (the
     12  * "License"); you may not use this file except in compliance
     13  * with 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,
     18  * software distributed under the License is distributed on an
     19  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     20  * KIND, either express or implied.  See the License for the
     21  * specific language governing permissions and limitations
     22  * under the License.
     23  * ====================================================================
     24  *
     25  * This software consists of voluntary contributions made by many
     26  * individuals on behalf of the Apache Software Foundation.  For more
     27  * information on the Apache Software Foundation, please see
     28  * <http://www.apache.org/>.
     29  *
     30  */
     31 
     32 package org.apache.http.conn.scheme;
     33 
     34 import java.io.IOException;
     35 import java.net.InetAddress;
     36 import java.net.Socket;
     37 import java.net.UnknownHostException;
     38 
     39 import org.apache.http.conn.ConnectTimeoutException;
     40 import org.apache.http.params.HttpParams;
     41 
     42 /**
     43  * A factory for creating and connecting sockets.
     44  * The factory encapsulates the logic for establishing a socket connection.
     45  * <br/>
     46  * Both {@link java.lang.Object#equals(java.lang.Object) Object.equals()}
     47  * and {@link java.lang.Object#hashCode() Object.hashCode()}
     48  * must be overridden for the correct operation of some connection managers.
     49  *
     50  * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
     51  * @author Michael Becke
     52  * @author <a href="mailto:mbowler (at) GargoyleSoftware.com">Mike Bowler</a>
     53  */
     54 public interface SocketFactory {
     55 
     56     /**
     57      * Creates a new, unconnected socket.
     58      * The socket should subsequently be passed to
     59      * {@link #connectSocket connectSocket}.
     60      *
     61      * @return  a new socket
     62      *
     63      * @throws IOException if an I/O error occurs while creating the socket
     64      */
     65     Socket createSocket()
     66         throws IOException
     67         ;
     68 
     69 
     70     /**
     71      * Connects a socket to the given host.
     72      *
     73      * @param sock      the socket to connect, as obtained from
     74      *                  {@link #createSocket createSocket}.
     75      *                  <code>null</code> indicates that a new socket
     76      *                  should be created and connected.
     77      * @param host      the host to connect to
     78      * @param port      the port to connect to on the host
     79      * @param localAddress the local address to bind the socket to, or
     80      *                  <code>null</code> for any
     81      * @param localPort the port on the local machine,
     82      *                  0 or a negative number for any
     83      * @param params    additional {@link HttpParams parameters} for connecting
     84      *
     85      * @return  the connected socket. The returned object may be different
     86      *          from the <code>sock</code> argument if this factory supports
     87      *          a layered protocol.
     88      *
     89      * @throws IOException if an I/O error occurs
     90      * @throws UnknownHostException if the IP address of the target host
     91      *          can not be determined
     92      * @throws ConnectTimeoutException if the socket cannot be connected
     93      *          within the time limit defined in the <code>params</code>
     94      */
     95     Socket connectSocket(
     96         Socket sock,
     97         String host,
     98         int port,
     99         InetAddress localAddress,
    100         int localPort,
    101         HttpParams params
    102     ) throws IOException, UnknownHostException, ConnectTimeoutException;
    103 
    104 
    105     /**
    106      * Checks whether a socket provides a secure connection.
    107      * The socket must be {@link #connectSocket connected}
    108      * by this factory.
    109      * The factory will <i>not</i> perform I/O operations
    110      * in this method.
    111      * <br/>
    112      * As a rule of thumb, plain sockets are not secure and
    113      * TLS/SSL sockets are secure. However, there may be
    114      * application specific deviations. For example, a plain
    115      * socket to a host in the same intranet ("trusted zone")
    116      * could be considered secure. On the other hand, a
    117      * TLS/SSL socket could be considered insecure based on
    118      * the cypher suite chosen for the connection.
    119      *
    120      * @param sock      the connected socket to check
    121      *
    122      * @return  <code>true</code> if the connection of the socket
    123      *          should be considered secure, or
    124      *          <code>false</code> if it should not
    125      *
    126      * @throws IllegalArgumentException
    127      *  if the argument is invalid, for example because it is
    128      *  not a connected socket or was created by a different
    129      *  socket factory.
    130      *  Note that socket factories are <i>not</i> required to
    131      *  check these conditions, they may simply return a default
    132      *  value when called with an invalid socket argument.
    133      */
    134     boolean isSecure(Socket sock)
    135         throws IllegalArgumentException
    136         ;
    137 
    138 }
    139