12231db3e6bb54447a9b14cf004a6cb03c373651cjwilson/* 22231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * Licensed to the Apache Software Foundation (ASF) under one or more 32231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * contributor license agreements. See the NOTICE file distributed with 42231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * this work for additional information regarding copyright ownership. 52231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * The ASF licenses this file to You under the Apache License, Version 2.0 62231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * (the "License"); you may not use this file except in compliance with 72231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * the License. You may obtain a copy of the License at 82231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * 92231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * http://www.apache.org/licenses/LICENSE-2.0 102231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * 112231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * Unless required by applicable law or agreed to in writing, software 122231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * distributed under the License is distributed on an "AS IS" BASIS, 132231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 142231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * See the License for the specific language governing permissions and 152231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * limitations under the License. 162231db3e6bb54447a9b14cf004a6cb03c373651cjwilson */ 172231db3e6bb54447a9b14cf004a6cb03c373651cjwilsonpackage com.squareup.okhttp; 182231db3e6bb54447a9b14cf004a6cb03c373651cjwilson 192231db3e6bb54447a9b14cf004a6cb03c373651cjwilsonimport java.net.Socket; 2054cf3446000fdcf88a9e62724f7deb0282e98da1jwilson 212231db3e6bb54447a9b14cf004a6cb03c373651cjwilson/** 226c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * The sockets and streams of an HTTP, HTTPS, or HTTPS+SPDY connection. May be used for multiple 236c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * HTTP request/response exchanges. Connections may be direct to the origin server or via a proxy. 242231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * 256c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <p>Typically instances of this class are created, connected and exercised automatically by the 266c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * HTTP client. Applications may use this class to monitor HTTP connections as members of a 276c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * {@linkplain ConnectionPool connection pool}. 282231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * 296c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <p>Do not confuse this class with the misnamed {@code HttpURLConnection}, which isn't so much a 306c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * connection as a single request/response exchange. 312231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * 322231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * <h3>Modern TLS</h3> 336c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * There are tradeoffs when selecting which options to include when negotiating a secure connection 346c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * to a remote host. Newer TLS options are quite useful: 352231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * <ul> 366c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <li>Server Name Indication (SNI) enables one IP address to negotiate secure connections for 376c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * multiple domain names. 386c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <li>Application Layer Protocol Negotiation (ALPN) enables the HTTPS port (443) to be used for 396c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * different HTTP and SPDY protocols. 402231db3e6bb54447a9b14cf004a6cb03c373651cjwilson * </ul> 416c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * Unfortunately, older HTTPS servers refuse to connect when such options are presented. Rather than 426c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * avoiding these options entirely, this class allows a connection to be attempted with modern 436c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * options and then retried without them should the attempt fail. 446c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * 456c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <h3>Connection Reuse</h3> 466c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <p>Each connection can carry a varying number streams, depending on the underlying protocol being 476c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * used. HTTP/1.x connections can carry either zero or one streams. HTTP/2 connections can carry any 486c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * number of streams, dynamically configured with {@code SETTINGS_MAX_CONCURRENT_STREAMS}. A 496c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * connection currently carrying zero streams is an idle stream. We keep it alive because reusing an 506c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * existing connection is typically faster than establishing a new one. 516c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * 526c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <p>When a single logical call requires multiple streams due to redirects or authorization 536c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * challenges, we prefer to use the same physical connection for all streams in the sequence. There 546c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * are potential performance and behavior consequences to this preference. To support this feature, 556c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * this class separates <i>allocations</i> from <i>streams</i>. An allocation is created by a call, 566c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * used for one or more streams, and then released. An allocated connection won't be stolen by 576c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * other calls while a redirect or authorization challenge is being handled. 586c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * 596c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <p>When the maximum concurrent streams limit is reduced, some allocations will be rescinded. 606c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * Attempting to create new streams on these allocations will fail. 616c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * 626c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <p>Note that an allocation may be released before its stream is completed. This is intended to 636c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * make bookkeeping easier for the caller: releasing the allocation as soon as the terminal stream 646c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * has been found. But only complete the stream once its data stream has been exhausted. 652231db3e6bb54447a9b14cf004a6cb03c373651cjwilson */ 666c251e20f00c7574b217bd4351ac81666f574380Tobias Thiererpublic interface Connection { 67faf49723fb689c626f69876e718c58018eff8ee7Narayan Kamath /** Returns the route used by this connection. */ 686c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer Route getRoute(); 6954cf3446000fdcf88a9e62724f7deb0282e98da1jwilson 7054cf3446000fdcf88a9e62724f7deb0282e98da1jwilson /** 7154cf3446000fdcf88a9e62724f7deb0282e98da1jwilson * Returns the socket that this connection uses, or null if the connection 7254cf3446000fdcf88a9e62724f7deb0282e98da1jwilson * is not currently connected. 7354cf3446000fdcf88a9e62724f7deb0282e98da1jwilson */ 746c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer Socket getSocket(); 75e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 766c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer Handshake getHandshake(); 773c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 783c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 796c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * Returns the protocol negotiated by this connection, or {@link Protocol#HTTP_1_1} if no protocol 806c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * has been negotiated. This method returns {@link Protocol#HTTP_1_1} even if the remote peer is 816c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * using {@link Protocol#HTTP_1_0}. 823c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 836c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer Protocol getProtocol(); 842231db3e6bb54447a9b14cf004a6cb03c373651cjwilson} 85