The Tor Browser: mobile/android/thirdparty/ch/boye/httpclientandroidlib/conn/OperatedClientConnection.java@fc2d59ddac77

     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  */

    28 package ch.boye.httpclientandroidlib.conn;

    30 import java.io.IOException;

    31 import java.net.Socket;

    33 import ch.boye.httpclientandroidlib.HttpClientConnection;

    34 import ch.boye.httpclientandroidlib.HttpHost;

    35 import ch.boye.httpclientandroidlib.HttpInetConnection;

    36 import ch.boye.httpclientandroidlib.params.HttpParams;

    38 /**

    39  * A client-side connection that relies on outside logic to connect sockets to the

    40  * appropriate hosts. It can be operated directly by an application, or through an

    41  * {@link ClientConnectionOperator operator}.

    42  *

    43  * @since 4.0

    44  */

    45 public interface OperatedClientConnection extends HttpClientConnection, HttpInetConnection {

    47     /**

    48      * Obtains the target host for this connection.

    49      * If the connection is to a proxy but not tunnelled, this is

    50      * the proxy. If the connection is tunnelled through a proxy,

    51      * this is the target of the tunnel.

    52      * <br/>

    53      * The return value is well-defined only while the connection is open.

    54      * It may change even while the connection is open,

    55      * because of an {@link #update update}.

    56      *

    57      * @return  the host to which this connection is opened

    58      */

    59     HttpHost getTargetHost();

    61     /**

    62      * Indicates whether this connection is secure.

    63      * The return value is well-defined only while the connection is open.

    64      * It may change even while the connection is open,

    65      * because of an {@link #update update}.

    66      *

    67      * @return  <code>true</code> if this connection is secure,

    68      *          <code>false</code> otherwise

    69      */

    70     boolean isSecure();

    72     /**

    73      * Obtains the socket for this connection.

    74      * The return value is well-defined only while the connection is open.

    75      * It may change even while the connection is open,

    76      * because of an {@link #update update}.

    77      *

    78      * @return  the socket for communicating with the

    79      *          {@link #getTargetHost target host}

    80      */

    81     Socket getSocket();

    83     /**

    84      * Signals that this connection is in the process of being open.

    85      * <p>

    86      * By calling this method, the connection can be re-initialized

    87      * with a new Socket instance before {@link #openCompleted} is called.

    88      * This enabled the connection to close that socket if

    89      * {@link ch.boye.httpclientandroidlib.HttpConnection#shutdown shutdown}

    90      * is called before it is fully open. Closing an unconnected socket

    91      * will interrupt a thread that is blocked on the connect.

    92      * Otherwise, that thread will either time out on the connect,

    93      * or it returns successfully and then opens this connection

    94      * which was just shut down.

    95      * <p>

    96      * This method can be called multiple times if the connection

    97      * is layered over another protocol. <b>Note:</b> This method

    98      * will <i>not</i> close the previously used socket. It is

    99      * the caller's responsibility to close that socket if it is

   100      * no longer required.

   101      * <p>

   102      * The caller must invoke {@link #openCompleted} in order to complete

   103      * the process.

   104      *

   105      * @param sock      the unconnected socket which is about to

   106      *                  be connected.

   107      * @param target    the target host of this connection

   108      */

   109     void opening(Socket sock, HttpHost target)

   110         throws IOException;

   112     /**

   113      * Signals that the connection has been successfully open.

   114      * An attempt to call this method on an open connection will cause

   115      * an exception.

   116      *

   117      * @param secure    <code>true</code> if this connection is secure, for

   118      *                  example if an <code>SSLSocket</code> is used, or

   119      *                  <code>false</code> if it is not secure

   120      * @param params    parameters for this connection. The parameters will

   121      *                  be used when creating dependent objects, for example

   122      *                  to determine buffer sizes.

   123      */

   124     void openCompleted(boolean secure, HttpParams params)

   125         throws IOException;

   127     /**

   128      * Updates this connection.

   129      * A connection can be updated only while it is open.

   130      * Updates are used for example when a tunnel has been established,

   131      * or when a TLS/SSL connection has been layered on top of a plain

   132      * socket connection.

   133      * <br/>

   134      * <b>Note:</b> Updating the connection will <i>not</i> close the

   135      * previously used socket. It is the caller's responsibility to close

   136      * that socket if it is no longer required.

   137      *

   138      * @param sock      the new socket for communicating with the target host,

   139      *                  or <code>null</code> to continue using the old socket.

   140      *                  If <code>null</code> is passed, helper objects that

   141      *                  depend on the socket should be re-used. In that case,

   142      *                  some changes in the parameters will not take effect.

   143      * @param target    the new target host of this connection

   144      * @param secure    <code>true</code> if this connection is now secure,

   145      *                  <code>false</code> if it is not secure

   146      * @param params    new parameters for this connection

   147      */

   148     void update(Socket sock, HttpHost target,

   149                 boolean secure, HttpParams params)

   150         throws IOException;

   152 }

The Tor Browser / file revision