michael@0: /*
michael@0:  * ====================================================================
michael@0:  *
michael@0:  *  Licensed to the Apache Software Foundation (ASF) under one or more
michael@0:  *  contributor license agreements.  See the NOTICE file distributed with
michael@0:  *  this work for additional information regarding copyright ownership.
michael@0:  *  The ASF licenses this file to You under the Apache License, Version 2.0
michael@0:  *  (the "License"); you may not use this file except in compliance with
michael@0:  *  the License.  You may obtain a copy of the License at
michael@0:  *
michael@0:  *      http://www.apache.org/licenses/LICENSE-2.0
michael@0:  *
michael@0:  *  Unless required by applicable law or agreed to in writing, software
michael@0:  *  distributed under the License is distributed on an "AS IS" BASIS,
michael@0:  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
michael@0:  *  See the License for the specific language governing permissions and
michael@0:  *  limitations under the License.
michael@0:  * ====================================================================
michael@0:  *
michael@0:  * This software consists of voluntary contributions made by many
michael@0:  * individuals on behalf of the Apache Software Foundation.  For more
michael@0:  * information on the Apache Software Foundation, please see
michael@0:  * <http://www.apache.org/>.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: package ch.boye.httpclientandroidlib.impl.conn;
michael@0: 
michael@0: import java.io.IOException;
michael@0: 
michael@0: import ch.boye.httpclientandroidlib.HttpHost;
michael@0: import ch.boye.httpclientandroidlib.params.HttpParams;
michael@0: import ch.boye.httpclientandroidlib.protocol.HttpContext;
michael@0: import ch.boye.httpclientandroidlib.annotation.NotThreadSafe;
michael@0: import ch.boye.httpclientandroidlib.conn.routing.HttpRoute;
michael@0: import ch.boye.httpclientandroidlib.conn.routing.RouteTracker;
michael@0: import ch.boye.httpclientandroidlib.conn.ClientConnectionOperator;
michael@0: import ch.boye.httpclientandroidlib.conn.OperatedClientConnection;
michael@0: 
michael@0: /**
michael@0:  * A pool entry for use by connection manager implementations.
michael@0:  * Pool entries work in conjunction with an
michael@0:  * {@link AbstractClientConnAdapter adapter}.
michael@0:  * The adapter is handed out to applications that obtain a connection.
michael@0:  * The pool entry stores the underlying connection and tracks the
michael@0:  * {@link HttpRoute route} established.
michael@0:  * The adapter delegates methods for establishing the route to
michael@0:  * its pool entry.
michael@0:  * <p>
michael@0:  * If the managed connections is released or revoked, the adapter
michael@0:  * gets disconnected, but the pool entry still contains the
michael@0:  * underlying connection and the established route.
michael@0:  *
michael@0:  * @since 4.0
michael@0:  */
michael@0: @NotThreadSafe
michael@0: public abstract class AbstractPoolEntry {
michael@0: 
michael@0:     /** The connection operator. */
michael@0:     protected final ClientConnectionOperator connOperator;
michael@0: 
michael@0:     /** The underlying connection being pooled or used. */
michael@0:     protected final OperatedClientConnection connection;
michael@0: 
michael@0:     /** The route for which this entry gets allocated. */
michael@0:     //@@@ currently accessed from connection manager(s) as attribute
michael@0:     //@@@ avoid that, derived classes should decide whether update is allowed
michael@0:     //@@@ SCCM: yes, TSCCM: no
michael@0:     protected volatile HttpRoute route;
michael@0: 
michael@0:     /** Connection state object */
michael@0:     protected volatile Object state;
michael@0: 
michael@0:     /** The tracked route, or <code>null</code> before tracking starts. */
michael@0:     protected volatile RouteTracker tracker;
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Creates a new pool entry.
michael@0:      *
michael@0:      * @param connOperator     the Connection Operator for this entry
michael@0:      * @param route   the planned route for the connection,
michael@0:      *                or <code>null</code>
michael@0:      */
michael@0:     protected AbstractPoolEntry(ClientConnectionOperator connOperator,
michael@0:                                 HttpRoute route) {
michael@0:         super();
michael@0:         if (connOperator == null) {
michael@0:             throw new IllegalArgumentException("Connection operator may not be null");
michael@0:         }
michael@0:         this.connOperator = connOperator;
michael@0:         this.connection = connOperator.createConnection();
michael@0:         this.route = route;
michael@0:         this.tracker = null;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Returns the state object associated with this pool entry.
michael@0:      *
michael@0:      * @return The state object
michael@0:      */
michael@0:     public Object getState() {
michael@0:         return state;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Assigns a state object to this pool entry.
michael@0:      *
michael@0:      * @param state The state object
michael@0:      */
michael@0:     public void setState(final Object state) {
michael@0:         this.state = state;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Opens the underlying connection.
michael@0:      *
michael@0:      * @param route         the route along which to open the connection
michael@0:      * @param context       the context for opening the connection
michael@0:      * @param params        the parameters for opening the connection
michael@0:      *
michael@0:      * @throws IOException  in case of a problem
michael@0:      */
michael@0:     public void open(HttpRoute route,
michael@0:                      HttpContext context, HttpParams params)
michael@0:         throws IOException {
michael@0: 
michael@0:         if (route == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Route must not be null.");
michael@0:         }
michael@0:         if (params == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Parameters must not be null.");
michael@0:         }
michael@0:         if ((this.tracker != null) && this.tracker.isConnected()) {
michael@0:             throw new IllegalStateException("Connection already open.");
michael@0:         }
michael@0: 
michael@0:         // - collect the arguments
michael@0:         // - call the operator
michael@0:         // - update the tracking data
michael@0:         // In this order, we can be sure that only a successful
michael@0:         // opening of the connection will be tracked.
michael@0: 
michael@0:         this.tracker = new RouteTracker(route);
michael@0:         final HttpHost proxy  = route.getProxyHost();
michael@0: 
michael@0:         connOperator.openConnection
michael@0:             (this.connection,
michael@0:              (proxy != null) ? proxy : route.getTargetHost(),
michael@0:              route.getLocalAddress(),
michael@0:              context, params);
michael@0: 
michael@0:         RouteTracker localTracker = tracker; // capture volatile
michael@0: 
michael@0:         // If this tracker was reset while connecting,
michael@0:         // fail early.
michael@0:         if (localTracker == null) {
michael@0:             throw new IOException("Request aborted");
michael@0:         }
michael@0: 
michael@0:         if (proxy == null) {
michael@0:             localTracker.connectTarget(this.connection.isSecure());
michael@0:         } else {
michael@0:             localTracker.connectProxy(proxy, this.connection.isSecure());
michael@0:         }
michael@0: 
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Tracks tunnelling of the connection to the target.
michael@0:      * The tunnel has to be established outside by sending a CONNECT
michael@0:      * request to the (last) proxy.
michael@0:      *
michael@0:      * @param secure    <code>true</code> if the tunnel should be
michael@0:      *                  considered secure, <code>false</code> otherwise
michael@0:      * @param params    the parameters for tunnelling the connection
michael@0:      *
michael@0:      * @throws IOException  in case of a problem
michael@0:      */
michael@0:     public void tunnelTarget(boolean secure, HttpParams params)
michael@0:         throws IOException {
michael@0: 
michael@0:         if (params == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Parameters must not be null.");
michael@0:         }
michael@0: 
michael@0:         if ((this.tracker == null) || !this.tracker.isConnected()) {
michael@0:             throw new IllegalStateException("Connection not open.");
michael@0:         }
michael@0:         if (this.tracker.isTunnelled()) {
michael@0:             throw new IllegalStateException
michael@0:                 ("Connection is already tunnelled.");
michael@0:         }
michael@0: 
michael@0:         this.connection.update(null, tracker.getTargetHost(),
michael@0:                                secure, params);
michael@0:         this.tracker.tunnelTarget(secure);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Tracks tunnelling of the connection to a chained proxy.
michael@0:      * The tunnel has to be established outside by sending a CONNECT
michael@0:      * request to the previous proxy.
michael@0:      *
michael@0:      * @param next      the proxy to which the tunnel was established.
michael@0:      *  See {@link ch.boye.httpclientandroidlib.conn.ManagedClientConnection#tunnelProxy
michael@0:      *                                  ManagedClientConnection.tunnelProxy}
michael@0:      *                  for details.
michael@0:      * @param secure    <code>true</code> if the tunnel should be
michael@0:      *                  considered secure, <code>false</code> otherwise
michael@0:      * @param params    the parameters for tunnelling the connection
michael@0:      *
michael@0:      * @throws IOException  in case of a problem
michael@0:      */
michael@0:     public void tunnelProxy(HttpHost next, boolean secure, HttpParams params)
michael@0:         throws IOException {
michael@0: 
michael@0:         if (next == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Next proxy must not be null.");
michael@0:         }
michael@0:         if (params == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Parameters must not be null.");
michael@0:         }
michael@0: 
michael@0:         //@@@ check for proxy in planned route?
michael@0:         if ((this.tracker == null) || !this.tracker.isConnected()) {
michael@0:             throw new IllegalStateException("Connection not open.");
michael@0:         }
michael@0: 
michael@0:         this.connection.update(null, next, secure, params);
michael@0:         this.tracker.tunnelProxy(next, secure);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Layers a protocol on top of an established tunnel.
michael@0:      *
michael@0:      * @param context   the context for layering
michael@0:      * @param params    the parameters for layering
michael@0:      *
michael@0:      * @throws IOException  in case of a problem
michael@0:      */
michael@0:     public void layerProtocol(HttpContext context, HttpParams params)
michael@0:         throws IOException {
michael@0: 
michael@0:         //@@@ is context allowed to be null? depends on operator?
michael@0:         if (params == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Parameters must not be null.");
michael@0:         }
michael@0: 
michael@0:         if ((this.tracker == null) || !this.tracker.isConnected()) {
michael@0:             throw new IllegalStateException("Connection not open.");
michael@0:         }
michael@0:         if (!this.tracker.isTunnelled()) {
michael@0:             //@@@ allow this?
michael@0:             throw new IllegalStateException
michael@0:                 ("Protocol layering without a tunnel not supported.");
michael@0:         }
michael@0:         if (this.tracker.isLayered()) {
michael@0:             throw new IllegalStateException
michael@0:                 ("Multiple protocol layering not supported.");
michael@0:         }
michael@0: 
michael@0:         // - collect the arguments
michael@0:         // - call the operator
michael@0:         // - update the tracking data
michael@0:         // In this order, we can be sure that only a successful
michael@0:         // layering on top of the connection will be tracked.
michael@0: 
michael@0:         final HttpHost target = tracker.getTargetHost();
michael@0: 
michael@0:         connOperator.updateSecureConnection(this.connection, target,
michael@0:                                              context, params);
michael@0: 
michael@0:         this.tracker.layerProtocol(this.connection.isSecure());
michael@0: 
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Shuts down the entry.
michael@0:      *
michael@0:      * If {@link #open(HttpRoute, HttpContext, HttpParams)} is in progress,
michael@0:      * this will cause that open to possibly throw an {@link IOException}.
michael@0:      */
michael@0:     protected void shutdownEntry() {
michael@0:         tracker = null;
michael@0:         state = null;
michael@0:     }
michael@0: 
michael@0: }
michael@0: