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;
29  
30  import java.io.IOException;
31  import java.net.Socket;
32  
33  import org.apache.http.HttpClientConnection;
34  import org.apache.http.HttpHost;
35  import org.apache.http.HttpInetConnection;
36  import org.apache.http.params.HttpParams;
37  
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   * @deprecated (4.3) replaced by {@link HttpClientConnectionManager}.
46   */
47  @Deprecated
48  public interface OperatedClientConnection extends HttpClientConnection, HttpInetConnection {
49  
50      /**
51       * Obtains the target host for this connection.
52       * If the connection is to a proxy but not tunnelled, this is
53       * the proxy. If the connection is tunnelled through a proxy,
54       * this is the target of the tunnel.
55       * <br/>
56       * The return value is well-defined only while the connection is open.
57       * It may change even while the connection is open,
58       * because of an {@link #update update}.
59       *
60       * @return  the host to which this connection is opened
61       */
62      HttpHost getTargetHost();
63  
64      /**
65       * Indicates whether this connection is secure.
66       * The return value is well-defined only while the connection is open.
67       * It may change even while the connection is open,
68       * because of an {@link #update update}.
69       *
70       * @return  <code>true</code> if this connection is secure,
71       *          <code>false</code> otherwise
72       */
73      boolean isSecure();
74  
75      /**
76       * Obtains the socket for this connection.
77       * The return value is well-defined only while the connection is open.
78       * It may change even while the connection is open,
79       * because of an {@link #update update}.
80       *
81       * @return  the socket for communicating with the
82       *          {@link #getTargetHost target host}
83       */
84      Socket getSocket();
85  
86      /**
87       * Signals that this connection is in the process of being open.
88       * <p>
89       * By calling this method, the connection can be re-initialized
90       * with a new Socket instance before {@link #openCompleted} is called.
91       * This enabled the connection to close that socket if
92       * {@link org.apache.http.HttpConnection#shutdown shutdown}
93       * is called before it is fully open. Closing an unconnected socket
94       * will interrupt a thread that is blocked on the connect.
95       * Otherwise, that thread will either time out on the connect,
96       * or it returns successfully and then opens this connection
97       * which was just shut down.
98       * <p>
99       * This method can be called multiple times if the connection
100      * is layered over another protocol. <b>Note:</b> This method
101      * will <i>not</i> close the previously used socket. It is
102      * the caller's responsibility to close that socket if it is
103      * no longer required.
104      * <p>
105      * The caller must invoke {@link #openCompleted} in order to complete
106      * the process.
107      *
108      * @param sock      the unconnected socket which is about to
109      *                  be connected.
110      * @param target    the target host of this connection
111      */
112     void opening(Socket sock, HttpHost target)
113         throws IOException;
114 
115     /**
116      * Signals that the connection has been successfully open.
117      * An attempt to call this method on an open connection will cause
118      * an exception.
119      *
120      * @param secure    <code>true</code> if this connection is secure, for
121      *                  example if an <code>SSLSocket</code> is used, or
122      *                  <code>false</code> if it is not secure
123      * @param params    parameters for this connection. The parameters will
124      *                  be used when creating dependent objects, for example
125      *                  to determine buffer sizes.
126      */
127     void openCompleted(boolean secure, HttpParams params)
128         throws IOException;
129 
130     /**
131      * Updates this connection.
132      * A connection can be updated only while it is open.
133      * Updates are used for example when a tunnel has been established,
134      * or when a TLS/SSL connection has been layered on top of a plain
135      * socket connection.
136      * <br/>
137      * <b>Note:</b> Updating the connection will <i>not</i> close the
138      * previously used socket. It is the caller's responsibility to close
139      * that socket if it is no longer required.
140      *
141      * @param sock      the new socket for communicating with the target host,
142      *                  or <code>null</code> to continue using the old socket.
143      *                  If <code>null</code> is passed, helper objects that
144      *                  depend on the socket should be re-used. In that case,
145      *                  some changes in the parameters will not take effect.
146      * @param target    the new target host of this connection
147      * @param secure    <code>true</code> if this connection is now secure,
148      *                  <code>false</code> if it is not secure
149      * @param params    new parameters for this connection
150      */
151     void update(Socket sock, HttpHost target,
152                 boolean secure, HttpParams params)
153         throws IOException;
154 
155 }