001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http.conn.scheme;
029
030import java.io.IOException;
031import java.net.InetSocketAddress;
032import java.net.Socket;
033import java.net.UnknownHostException;
034
035import org.apache.http.conn.ConnectTimeoutException;
036import org.apache.http.params.HttpParams;
037
038/**
039 * A factory for creating, initializing and connecting sockets. The factory encapsulates the logic
040 * for establishing a socket connection.
041 *
042 * @since 4.1
043 *
044 * @deprecated (4.3) use {@link org.apache.http.conn.socket.ConnectionSocketFactory}
045 */
046@Deprecated
047public interface SchemeSocketFactory {
048
049    /**
050     * Creates a new, unconnected socket. The socket should subsequently be passed to
051     * {@link #connectSocket(Socket, InetSocketAddress, InetSocketAddress, HttpParams)}.
052     *
053     * @param params    Optional {@link HttpParams parameters}. In most cases these parameters
054     *                  will not be required and will have no effect, as usually socket
055     *                  initialization should take place in the
056     *                  {@link #connectSocket(Socket, InetSocketAddress, InetSocketAddress, HttpParams)}
057     *                  method. However, in rare cases one may want to pass additional parameters
058     *                  to this method in order to create a customized {@link Socket} instance,
059     *                  for instance bound to a SOCKS proxy server.
060     *
061     * @return  a new socket
062     *
063     * @throws IOException if an I/O error occurs while creating the socket
064     */
065    Socket createSocket(HttpParams params) throws IOException;
066
067    /**
068     * Connects a socket to the target host with the given remote address.
069     * <p>
070     * Please note that {@link org.apache.http.conn.HttpInetSocketAddress} class should
071     * be used in order to pass the target remote address along with the original
072     * {@link org.apache.http.HttpHost} value used to resolve the address. The use of
073     * {@link org.apache.http.conn.HttpInetSocketAddress} can also ensure that no reverse
074     * DNS lookup will be performed if the target remote address was specified
075     * as an IP address.
076     * </p>
077     *
078     * @param sock      the socket to connect, as obtained from
079     *                  {@link #createSocket(HttpParams) createSocket}.
080     *                  {@code null} indicates that a new socket
081     *                  should be created and connected.
082     * @param remoteAddress the remote address to connect to.
083     * @param localAddress the local address to bind the socket to, or
084     *                  {@code null} for any
085     * @param params    additional {@link HttpParams parameters} for connecting
086     *
087     * @return  the connected socket. The returned object may be different
088     *          from the {@code sock} argument if this factory supports
089     *          a layered protocol.
090     *
091     * @throws IOException if an I/O error occurs
092     * @throws UnknownHostException if the IP address of the target host
093     *          can not be determined
094     * @throws ConnectTimeoutException if the socket cannot be connected
095     *          within the time limit defined in the {@code params}
096     *
097     * @see org.apache.http.conn.HttpInetSocketAddress
098     */
099    Socket connectSocket(
100        Socket sock,
101        InetSocketAddress remoteAddress,
102        InetSocketAddress localAddress,
103        HttpParams params) throws IOException, UnknownHostException, ConnectTimeoutException;
104
105    /**
106     * Checks whether a socket provides a secure connection. The socket must be
107     * {@link #connectSocket(Socket, InetSocketAddress, InetSocketAddress, HttpParams) connected}
108     * by this factory. The factory will <i>not</i> perform I/O operations in this method.
109     * <p>
110     * As a rule of thumb, plain sockets are not secure and TLS/SSL sockets are secure. However,
111     * there may be application specific deviations. For example, a plain socket to a host in the
112     * same intranet ("trusted zone") could be considered secure. On the other hand, a TLS/SSL
113     * socket could be considered insecure based on the cipher suite chosen for the connection.
114     *
115     * @param sock      the connected socket to check
116     *
117     * @return  {@code true} if the connection of the socket
118     *          should be considered secure, or
119     *          {@code false} if it should not
120     *
121     * @throws IllegalArgumentException
122     *  if the argument is invalid, for example because it is
123     *  not a connected socket or was created by a different
124     *  socket factory.
125     *  Note that socket factories are <i>not</i> required to
126     *  check these conditions, they may simply return a default
127     *  value when called with an invalid socket argument.
128     */
129    boolean isSecure(Socket sock) throws IllegalArgumentException;
130
131}