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 package org.apache.http.impl.conn;
28
29 import java.io.IOException;
30 import java.io.InterruptedIOException;
31
32 import org.apache.http.HttpHost;
33 import org.apache.http.conn.ClientConnectionOperator;
34 import org.apache.http.conn.OperatedClientConnection;
35 import org.apache.http.conn.routing.HttpRoute;
36 import org.apache.http.conn.routing.RouteTracker;
37 import org.apache.http.params.HttpParams;
38 import org.apache.http.protocol.HttpContext;
39 import org.apache.http.util.Args;
40 import org.apache.http.util.Asserts;
41
42 /**
43 * A pool entry for use by connection manager implementations.
44 * Pool entries work in conjunction with an
45 * {@link AbstractClientConnAdapter adapter}.
46 * The adapter is handed out to applications that obtain a connection.
47 * The pool entry stores the underlying connection and tracks the
48 * {@link HttpRoute route} established.
49 * The adapter delegates methods for establishing the route to
50 * its pool entry.
51 * <p>
52 * If the managed connections is released or revoked, the adapter
53 * gets disconnected, but the pool entry still contains the
54 * underlying connection and the established route.
55 *
56 * @since 4.0
57 *
58 * @deprecated (4.2) do not use
59 */
60 @Deprecated
61 public abstract class AbstractPoolEntry {
62
63 /** The connection operator. */
64 protected final ClientConnectionOperator connOperator;
65
66 /** The underlying connection being pooled or used. */
67 protected final OperatedClientConnection connection;
68
69 /** The route for which this entry gets allocated. */
70 //@@@ currently accessed from connection manager(s) as attribute
71 //@@@ avoid that, derived classes should decide whether update is allowed
72 //@@@ SCCM: yes, TSCCM: no
73 protected volatile HttpRoute route;
74
75 /** Connection state object */
76 protected volatile Object state;
77
78 /** The tracked route, or {@code null} before tracking starts. */
79 protected volatile RouteTracker tracker;
80
81
82 /**
83 * Creates a new pool entry.
84 *
85 * @param connOperator the Connection Operator for this entry
86 * @param route the planned route for the connection,
87 * or {@code null}
88 */
89 protected AbstractPoolEntry(final ClientConnectionOperator connOperator,
90 final HttpRoute route) {
91 super();
92 Args.notNull(connOperator, "Connection operator");
93 this.connOperator = connOperator;
94 this.connection = connOperator.createConnection();
95 this.route = route;
96 this.tracker = null;
97 }
98
99 /**
100 * Returns the state object associated with this pool entry.
101 *
102 * @return The state object
103 */
104 public Object getState() {
105 return state;
106 }
107
108 /**
109 * Assigns a state object to this pool entry.
110 *
111 * @param state The state object
112 */
113 public void setState(final Object state) {
114 this.state = state;
115 }
116
117 /**
118 * Opens the underlying connection.
119 *
120 * @param route the route along which to open the connection
121 * @param context the context for opening the connection
122 * @param params the parameters for opening the connection
123 *
124 * @throws IOException in case of a problem
125 */
126 public void open(final HttpRoute route,
127 final HttpContext context, final HttpParams params)
128 throws IOException {
129
130 Args.notNull(route, "Route");
131 Args.notNull(params, "HTTP parameters");
132 if (this.tracker != null) {
133 Asserts.check(!this.tracker.isConnected(), "Connection already open");
134 }
135 // - collect the arguments
136 // - call the operator
137 // - update the tracking data
138 // In this order, we can be sure that only a successful
139 // opening of the connection will be tracked.
140
141 this.tracker = new RouteTracker(route);
142 final HttpHost proxy = route.getProxyHost();
143
144 connOperator.openConnection
145 (this.connection,
146 (proxy != null) ? proxy : route.getTargetHost(),
147 route.getLocalAddress(),
148 context, params);
149
150 final RouteTracker localTracker = tracker; // capture volatile
151
152 // If this tracker was reset while connecting,
153 // fail early.
154 if (localTracker == null) {
155 throw new InterruptedIOException("Request aborted");
156 }
157
158 if (proxy == null) {
159 localTracker.connectTarget(this.connection.isSecure());
160 } else {
161 localTracker.connectProxy(proxy, this.connection.isSecure());
162 }
163
164 }
165
166 /**
167 * Tracks tunnelling of the connection to the target.
168 * The tunnel has to be established outside by sending a CONNECT
169 * request to the (last) proxy.
170 *
171 * @param secure {@code true} if the tunnel should be
172 * considered secure, {@code false} otherwise
173 * @param params the parameters for tunnelling the connection
174 *
175 * @throws IOException in case of a problem
176 */
177 public void tunnelTarget(final boolean secure, final HttpParams params)
178 throws IOException {
179
180 Args.notNull(params, "HTTP parameters");
181 Asserts.notNull(this.tracker, "Route tracker");
182 Asserts.check(this.tracker.isConnected(), "Connection not open");
183 Asserts.check(!this.tracker.isTunnelled(), "Connection is already tunnelled");
184
185 this.connection.update(null, tracker.getTargetHost(),
186 secure, params);
187 this.tracker.tunnelTarget(secure);
188 }
189
190 /**
191 * Tracks tunnelling of the connection to a chained proxy.
192 * The tunnel has to be established outside by sending a CONNECT
193 * request to the previous proxy.
194 *
195 * @param next the proxy to which the tunnel was established.
196 * See {@link org.apache.http.conn.ManagedClientConnection#tunnelProxy
197 * ManagedClientConnection.tunnelProxy}
198 * for details.
199 * @param secure {@code true} if the tunnel should be
200 * considered secure, {@code false} otherwise
201 * @param params the parameters for tunnelling the connection
202 *
203 * @throws IOException in case of a problem
204 */
205 public void tunnelProxy(final HttpHost next, final boolean secure, final HttpParams params)
206 throws IOException {
207
208 Args.notNull(next, "Next proxy");
209 Args.notNull(params, "Parameters");
210
211 Asserts.notNull(this.tracker, "Route tracker");
212 Asserts.check(this.tracker.isConnected(), "Connection not open");
213
214 this.connection.update(null, next, secure, params);
215 this.tracker.tunnelProxy(next, secure);
216 }
217
218 /**
219 * Layers a protocol on top of an established tunnel.
220 *
221 * @param context the context for layering
222 * @param params the parameters for layering
223 *
224 * @throws IOException in case of a problem
225 */
226 public void layerProtocol(final HttpContext context, final HttpParams params)
227 throws IOException {
228
229 //@@@ is context allowed to be null? depends on operator?
230 Args.notNull(params, "HTTP parameters");
231 Asserts.notNull(this.tracker, "Route tracker");
232 Asserts.check(this.tracker.isConnected(), "Connection not open");
233 Asserts.check(this.tracker.isTunnelled(), "Protocol layering without a tunnel not supported");
234 Asserts.check(!this.tracker.isLayered(), "Multiple protocol layering not supported");
235 // - collect the arguments
236 // - call the operator
237 // - update the tracking data
238 // In this order, we can be sure that only a successful
239 // layering on top of the connection will be tracked.
240
241 final HttpHost target = tracker.getTargetHost();
242
243 connOperator.updateSecureConnection(this.connection, target,
244 context, params);
245
246 this.tracker.layerProtocol(this.connection.isSecure());
247
248 }
249
250 /**
251 * Shuts down the entry.
252 *
253 * If {@link #open(HttpRoute, HttpContext, HttpParams)} is in progress,
254 * this will cause that open to possibly throw an {@link IOException}.
255 */
256 protected void shutdownEntry() {
257 tracker = null;
258 state = null;
259 }
260
261 }
262