View Javadoc

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