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;
029
030import java.io.IOException;
031import java.net.Socket;
032
033import javax.net.ssl.SSLSession;
034
035import org.apache.http.HttpClientConnection;
036import org.apache.http.HttpInetConnection;
037
038/**
039 * Represents a managed connection whose state and life cycle is managed by
040 * a connection manager. This interface extends {@link HttpClientConnection}
041 * with methods to bind the connection to an arbitrary socket and
042 * to obtain SSL session details.
043 *
044 * @since 4.3
045 */
046public interface ManagedHttpClientConnection extends HttpClientConnection, HttpInetConnection {
047
048    /**
049     * Returns connection ID which is expected to be unique
050     * for the life span of the connection manager.
051     */
052    String getId();
053
054    /**
055     * Binds this connection to the given socket. The connection
056     * is considered open if it is bound and the underlying socket
057     * is connection to a remote host.
058     *
059     * @param socket the socket to bind the connection to.
060     * @throws IOException
061     */
062    void bind(Socket socket) throws IOException;
063
064    /**
065     * Returns the underlying socket.
066     */
067    Socket getSocket();
068
069    /**
070     * Obtains the SSL session of the underlying connection, if any.
071     * If this connection is open, and the underlying socket is an
072     * {@link javax.net.ssl.SSLSocket SSLSocket}, the SSL session of
073     * that socket is obtained. This is a potentially blocking operation.
074     *
075     * @return  the underlying SSL session if available,
076     *          {@code null} otherwise
077     */
078    SSLSession getSSLSession();
079
080}