1 /*
2 * Copyright (C) 2014 Square, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package okhttp3;
17
18 import java.io.IOException;
19
20 /**
21 * Protocols that OkHttp implements for <a
22 * href="http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg">ALPN</a> selection.
23 *
24 * <h3>Protocol vs Scheme</h3> Despite its name, {@link java.net.URL#getProtocol()} returns the
25 * {@linkplain java.net.URI#getScheme() scheme} (http, https, etc.) of the URL, not the protocol
26 * (http/1.1, spdy/3.1, etc.). OkHttp uses the word <i>protocol</i> to identify how HTTP messages
27 * are framed.
28 */
29 public enum Protocol {
30 /**
31 * An obsolete plaintext framing that does not use persistent sockets by default.
32 */
33 HTTP_1_0("http/1.0"),
34
35 /**
36 * A plaintext framing that includes persistent connections.
37 *
38 * <p>This version of OkHttp implements <a href="https://tools.ietf.org/html/rfc7230">RFC
39 * 7230</a>, and tracks revisions to that spec.
40 */
41 HTTP_1_1("http/1.1"),
42
43 /**
44 * Chromium's binary-framed protocol that includes header compression, multiplexing multiple
45 * requests on the same socket, and server-push. HTTP/1.1 semantics are layered on SPDY/3.
46 *
47 * <p>Current versions of OkHttp do not support this protocol.
48 *
49 * @deprecated OkHttp has dropped support for SPDY. Prefer {@link #HTTP_2}.
50 */
51 SPDY_3("spdy/3.1"),
52
53 /**
54 * The IETF's binary-framed protocol that includes header compression, multiplexing multiple
55 * requests on the same socket, and server-push. HTTP/1.1 semantics are layered on HTTP/2.
56 *
57 * <p>HTTP/2 requires deployments of HTTP/2 that use TLS 1.2 support {@linkplain
58 * CipherSuite#TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256} , present in Java 8+ and Android 5+. Servers
59 * that enforce this may send an exception message including the string {@code
60 * INADEQUATE_SECURITY}.
61 */
62 HTTP_2("h2"),
63
64 /**
65 * Cleartext HTTP/2 with no "upgrade" round trip. This option requires the client to have prior
66 * knowledge that the server supports cleartext HTTP/2.
67 *
68 * @see <a href="https://tools.ietf.org/html/rfc7540#section-3.4">Starting HTTP/2 with Prior
69 * Knowledge</a>
70 */
71 H2_PRIOR_KNOWLEDGE("h2_prior_knowledge"),
72
73 /**
74 * QUIC (Quick UDP Internet Connection) is a new multiplexed and secure transport atop UDP,
75 * designed from the ground up and optimized for HTTP/2 semantics.
76 * HTTP/1.1 semantics are layered on HTTP/2.
77 *
78 * <p>QUIC is not natively supported by OkHttp, but provided to allow a theoretical
79 * interceptor that provides support.
80 */
81 QUIC("quic");
82
83 private final String protocol;
84
85 Protocol(String protocol) {
86 this.protocol = protocol;
87 }
88
89 /**
90 * Returns the protocol identified by {@code protocol}.
91 *
92 * @throws IOException if {@code protocol} is unknown.
93 */
94 public static Protocol get(String protocol) throws IOException {
95 // Unroll the loop over values() to save an allocation.
96 if (protocol.equals(HTTP_1_0.protocol)) return HTTP_1_0;
97 if (protocol.equals(HTTP_1_1.protocol)) return HTTP_1_1;
98 if (protocol.equals(H2_PRIOR_KNOWLEDGE.protocol)) return H2_PRIOR_KNOWLEDGE;
99 if (protocol.equals(HTTP_2.protocol)) return HTTP_2;
100 if (protocol.equals(SPDY_3.protocol)) return SPDY_3;
101 if (protocol.equals(QUIC.protocol)) return QUIC;
102 throw new IOException("Unexpected protocol: " + protocol);
103 }
104
105 /**
106 * Returns the string used to identify this protocol for ALPN, like "http/1.1", "spdy/3.1" or
107 * "h2".
108 *
109 * @see <a href="https://www.iana.org/assignments/tls-extensiontype-values">IANA
110 * tls-extensiontype-values</a>
111 */
112 @Override public String toString() {
113 return protocol;
114 }
115 }
116