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
