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.socket;
029
030import java.io.IOException;
031import java.net.InetSocketAddress;
032import java.net.Socket;
033
034import org.apache.http.HttpHost;
035import org.apache.http.protocol.HttpContext;
036
037/**
038 * A factory for creating and connecting connection sockets.
039 *
040 * @since 4.3
041 */
042public interface ConnectionSocketFactory {
043
044    /**
045     * Creates new, unconnected socket. The socket should subsequently be passed to
046     * {@link #connectSocket(int, Socket, HttpHost, InetSocketAddress, InetSocketAddress,
047     *    HttpContext) connectSocket} method.
048     *
049     * @return  a new socket
050     *
051     * @throws IOException if an I/O error occurs while creating the socket
052     */
053    Socket createSocket(HttpContext context) throws IOException;
054
055    /**
056     * Connects the socket to the target host with the given resolved remote address.
057     *
058     * @param connectTimeout connect timeout.
059     * @param sock the socket to connect, as obtained from {@link #createSocket(HttpContext)}.
060     * {@code null} indicates that a new socket should be created and connected.
061     * @param host target host as specified by the caller (end user).
062     * @param remoteAddress the resolved remote address to connect to.
063     * @param localAddress the local address to bind the socket to, or {@code null} for any.
064     * @param context the actual HTTP context.
065     *
066     * @return  the connected socket. The returned object may be different
067     *          from the {@code sock} argument if this factory supports
068     *          a layered protocol.
069     *
070     * @throws IOException if an I/O error occurs
071     */
072    Socket connectSocket(
073        int connectTimeout,
074        Socket sock,
075        HttpHost host,
076        InetSocketAddress remoteAddress,
077        InetSocketAddress localAddress,
078        HttpContext context) throws IOException;
079
080}