1 //
2 // ========================================================================
3 // Copyright (c) 1995-2013 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
8 //
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
11 //
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
14 //
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
17 //
18
19 package org.eclipse.jetty.client;
20
21 import java.net.SocketAddress;
22
23 import org.eclipse.jetty.client.api.Connection;
24 import org.eclipse.jetty.util.Promise;
25
26 /**
27 * {@link HttpClientTransport} represents what transport implementations should provide
28 * in order to plug-in a different transport for {@link HttpClient}.
29 * <p/>
30 * While the {@link HttpClient} APIs define the HTTP semantic (request, response, headers, etc.)
31 * <em>how</em> a HTTP exchange is carried over the network depends on implementations of this class.
32 * <p/>
33 * The default implementation uses the HTTP protocol to carry over the network the HTTP exchange,
34 * but the HTTP exchange may also be carried using the SPDY protocol or the FCGI protocol or, in future,
35 * other protocols.
36 */
37 public interface HttpClientTransport
38 {
39 /**
40 * Sets the {@link HttpClient} instance on this transport.
41 * <p />
42 * This is needed because of a chicken-egg problem: in order to create the {@link HttpClient}
43 * a {@link HttpClientTransport} is needed, that therefore cannot have a reference yet to the
44 * {@link HttpClient}.
45 *
46 * @param client the {@link HttpClient} that uses this transport.
47 */
48 public void setHttpClient(HttpClient client);
49
50 /**
51 * Creates a new, transport-specific, {@link HttpDestination} object.
52 * <p />
53 * {@link HttpDestination} controls the destination-connection cardinality: protocols like
54 * HTTP have 1-N cardinality, while multiplexed protocols like SPDY have a 1-1 cardinality.
55 *
56 * @param scheme the destination scheme
57 * @param host the destination host
58 * @param port the destination port
59 * @return a new, transport-specific, {@link HttpDestination} object
60 */
61 public HttpDestination newHttpDestination(String scheme, String host, int port);
62
63 /**
64 * Establishes a physical connection to the given {@code address}.
65 *
66 * @param destination the destination
67 * @param address the address to connect to
68 * @param promise the promise to notify when the connection succeeds or fails
69 */
70 public void connect(HttpDestination destination, SocketAddress address, Promise<Connection> promise);
71
72 /**
73 * Establishes an encrypted tunnel over the given {@code connection}
74 *
75 * @param connection the connection to tunnel
76 * @return the tunnelled connection
77 */
78 public Connection tunnel(Connection connection);
79 }