mirror of
https://github.com/square/okhttp.git
synced 2026-01-15 20:56:41 +03:00
Merge pull request #4829 from square/jwilson.0330.dokka
Configure Dokka
This commit is contained in:
Jesse Wilson
GitHub
14
build.gradle
14
build.gradle
@@ -40,6 +40,7 @@ buildscript {
|
||||
classpath 'com.vanniktech:gradle-maven-publish-plugin:0.8.0'
|
||||
classpath 'net.ltgt.gradle:gradle-errorprone-plugin:0.7.1'
|
||||
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
|
||||
classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.9.18"
|
||||
}
|
||||
|
||||
repositories {
|
||||
@@ -60,6 +61,9 @@ allprojects {
|
||||
|
||||
repositories {
|
||||
mavenCentral()
|
||||
maven {
|
||||
url 'https://dl.bintray.com/kotlin/dokka'
|
||||
}
|
||||
}
|
||||
|
||||
task downloadDependencies() {
|
||||
@@ -119,6 +123,16 @@ subprojects { project ->
|
||||
errorproneJavac 'com.google.errorprone:javac:9+181-r4173-1'
|
||||
errorprone 'com.google.errorprone:error_prone_core:2.3.3'
|
||||
}
|
||||
|
||||
apply plugin: 'org.jetbrains.dokka'
|
||||
dokka {
|
||||
reportUndocumented = false
|
||||
skipDeprecated = true
|
||||
packageOptions {
|
||||
prefix = "okhttp3.internal"
|
||||
suppress = true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
tasks.wrapper {
|
||||
|
||||
@@ -35,9 +35,7 @@ import java.util.ArrayList
|
||||
import java.util.concurrent.CountDownLatch
|
||||
|
||||
/**
|
||||
* DNS over HTTPS implementation.
|
||||
*
|
||||
* Implementation of https://tools.ietf.org/html/draft-ietf-doh-dns-over-https-13
|
||||
* [DNS over HTTPS implementation][[doh_spec]].
|
||||
*
|
||||
* <blockquote>A DNS API client encodes a single DNS query into an HTTP request
|
||||
* using either the HTTP GET or POST method and the other requirements
|
||||
@@ -46,10 +44,11 @@ import java.util.concurrent.CountDownLatch
|
||||
*
|
||||
* <h3>Warning: This is a non-final API.</h3>
|
||||
*
|
||||
*
|
||||
* As of OkHttp 3.14, this feature is an unstable preview: the API is subject to change,
|
||||
* and the implementation is incomplete. We expect that OkHttp 4.0 or 4.1 will finalize this API.
|
||||
* Until then, expect API and behavior changes when you update your OkHttp dependency.**
|
||||
*
|
||||
* [doh_spec]: https://tools.ietf.org/html/draft-ietf-doh-dns-over-https-13
|
||||
*/
|
||||
class DnsOverHttps internal constructor(builder: Builder) : Dns {
|
||||
private val client: OkHttpClient =
|
||||
|
||||
@@ -22,15 +22,14 @@ import java.io.IOException
|
||||
* **reactive** authentication after receiving a challenge from either an origin web server or proxy
|
||||
* server.
|
||||
*
|
||||
* Preemptive Authentication
|
||||
* -------------------------
|
||||
* ## Preemptive Authentication
|
||||
*
|
||||
* To make HTTPS calls using an HTTP proxy server OkHttp must first negotiate a connection with
|
||||
* the proxy. This proxy connection is called a "TLS Tunnel" and is specified by [RFC
|
||||
* 2817](https://tools.ietf.org/html/rfc2817). The HTTP CONNECT request that creates this tunnel
|
||||
* connection is special: it does not participate in any [interceptors][Interceptor] or [event
|
||||
* listeners][EventListener]. It doesn't include the motivating request's HTTP headers or even its
|
||||
* full URL; only the target server's hostname is sent to the proxy.
|
||||
* the proxy. This proxy connection is called a "TLS Tunnel" and is specified by
|
||||
* [RFC 2817][rfc_2817]. The HTTP CONNECT request that creates this tunnel connection is special: it
|
||||
* does not participate in any [interceptors][Interceptor] or [event listeners][EventListener]. It
|
||||
* doesn't include the motivating request's HTTP headers or even its full URL; only the target
|
||||
* server's hostname is sent to the proxy.
|
||||
*
|
||||
* Prior to sending any CONNECT request OkHttp always calls the proxy authenticator so that it may
|
||||
* prepare preemptive authentication. OkHttp will call [authenticate] with a fake `HTTP/1.1 407
|
||||
@@ -50,8 +49,7 @@ import java.io.IOException
|
||||
* return null; // Didn't find a preemptive auth scheme.
|
||||
* ```
|
||||
*
|
||||
* Reactive Authentication
|
||||
* -----------------------
|
||||
* ## Reactive Authentication
|
||||
*
|
||||
* Implementations authenticate by returning a follow-up request that includes an authorization
|
||||
* header, or they may decline the challenge by returning null. In this case the unauthenticated
|
||||
@@ -94,6 +92,8 @@ import java.io.IOException
|
||||
*
|
||||
* Applications may configure OkHttp with an authenticator for origin servers, or proxy servers,
|
||||
* or both.
|
||||
*
|
||||
* [rfc_2817]: https://tools.ietf.org/html/rfc2817
|
||||
*/
|
||||
interface Authenticator {
|
||||
/**
|
||||
|
||||
@@ -52,8 +52,7 @@ import java.util.NoSuchElementException
|
||||
* Caches HTTP and HTTPS responses to the filesystem so they may be reused, saving time and
|
||||
* bandwidth.
|
||||
*
|
||||
* Cache Optimization
|
||||
* ------------------
|
||||
* ## Cache Optimization
|
||||
*
|
||||
* To measure cache effectiveness, this class tracks three statistics:
|
||||
*
|
||||
@@ -69,11 +68,10 @@ import java.util.NoSuchElementException
|
||||
* is still valid. Such responses increment both the network count and hit count.
|
||||
*
|
||||
* The best way to improve the cache hit rate is by configuring the web server to return cacheable
|
||||
* responses. Although this client honors all [HTTP/1.1 (RFC
|
||||
* 7234)](http://tools.ietf.org/html/rfc7234) cache headers, it doesn't cache partial responses.
|
||||
* responses. Although this client honors all [HTTP/1.1 (RFC 7234)][rfc_7234] cache headers, it
|
||||
* doesn't cache partial responses.
|
||||
*
|
||||
* Force a Network Response
|
||||
* ------------------------
|
||||
* ## Force a Network Response
|
||||
*
|
||||
* In some situations, such as after a user clicks a 'refresh' button, it may be necessary to skip
|
||||
* the cache, and fetch data directly from the server. To force a full refresh, add the `no-cache`
|
||||
@@ -98,8 +96,7 @@ import java.util.NoSuchElementException
|
||||
* .build();
|
||||
* ```
|
||||
*
|
||||
* Force a Cache Response
|
||||
* ----------------------
|
||||
* ## Force a Cache Response
|
||||
*
|
||||
* Sometimes you'll want to show resources if they are available immediately, but not otherwise.
|
||||
* This can be used so your application can show *something* while waiting for the latest data to be
|
||||
@@ -137,6 +134,8 @@ import java.util.NoSuchElementException
|
||||
* The [CacheControl] class can configure request caching directives and parse response caching
|
||||
* directives. It even offers convenient constants [CacheControl.FORCE_NETWORK] and
|
||||
* [CacheControl.FORCE_CACHE] that address the use cases above.
|
||||
*
|
||||
* [rfc_7234]: http://tools.ietf.org/html/rfc7234
|
||||
*/
|
||||
class Cache internal constructor(
|
||||
directory: File,
|
||||
@@ -308,13 +307,13 @@ class Cache internal constructor(
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns an iterator over the URLs in this cache. This iterator doesn't throw `ConcurrentModificationException`, but if new responses are added while iterating, their URLs
|
||||
* Returns an iterator over the URLs in this cache. This iterator doesn't throw
|
||||
* `ConcurrentModificationException`, but if new responses are added while iterating, their URLs
|
||||
* will not be returned. If existing responses are evicted during iteration, they will be absent
|
||||
* (unless they were already returned).
|
||||
*
|
||||
*
|
||||
* The iterator supports [Iterator.remove]. Removing a URL from the iterator evicts
|
||||
* the corresponding response from the cache. Use this to evict selected responses.
|
||||
* The iterator supports [MutableIterator.remove]. Removing a URL from the iterator evicts the
|
||||
* corresponding response from the cache. Use this to evict selected responses.
|
||||
*/
|
||||
@Throws(IOException::class)
|
||||
fun urls(): MutableIterator<String> {
|
||||
|
||||
@@ -27,19 +27,16 @@ import javax.net.ssl.SSLPeerUnverifiedException
|
||||
* Constrains which certificates are trusted. Pinning certificates defends against attacks on
|
||||
* certificate authorities. It also prevents connections through man-in-the-middle certificate
|
||||
* authorities either known or unknown to the application's user.
|
||||
* This class currently pins a certificate's Subject Public Key Info as described on
|
||||
* [Adam Langley's Weblog][langley]. Pins are either base64 SHA-256 hashes as in
|
||||
* [HTTP Public Key Pinning (HPKP)][rfc_7469] or SHA-1 base64 hashes as in Chromium's
|
||||
* [static certificates][static_certificates].
|
||||
*
|
||||
* This class currently pins a certificate's Subject Public Key Info as described on [Adam Langley's
|
||||
* Weblog](http://goo.gl/AIx3e5). Pins are either base64 SHA-256 hashes as in [HTTP Public Key
|
||||
* Pinning (HPKP)](http://tools.ietf.org/html/rfc7469) or SHA-1 base64 hashes as in Chromium's
|
||||
* [static certificates](http://goo.gl/XDh6je).
|
||||
*
|
||||
* Setting up Certificate Pinning
|
||||
* ------------------------------
|
||||
* ## Setting up Certificate Pinning
|
||||
*
|
||||
* The easiest way to pin a host is turn on pinning with a broken configuration and read the
|
||||
* expected configuration when the connection fails. Be sure to do this on a trusted network, and
|
||||
* without man-in-the-middle tools like [Charles](http://charlesproxy.com) or
|
||||
* [Fiddler](http://fiddlertool.com).
|
||||
* without man-in-the-middle tools like [Charles][charles] or [Fiddler][fiddler].
|
||||
*
|
||||
* For example, to pin `https://publicobject.com`, start with a broken configuration:
|
||||
*
|
||||
@@ -104,8 +101,7 @@ import javax.net.ssl.SSLPeerUnverifiedException
|
||||
* For example: `*.example.com` pinned with `pin1` and `a.example.com` pinned with `pin2`, to check
|
||||
* `a.example.com` both `pin1` and `pin2` will be used.
|
||||
*
|
||||
* Warning: Certificate Pinning is Dangerous!
|
||||
* ------------------------------------------
|
||||
* ## Warning: Certificate Pinning is Dangerous!
|
||||
*
|
||||
* Pinning certificates limits your server team's abilities to update their TLS certificates. By
|
||||
* pinning certificates, you take on additional operational complexity and limit your ability to
|
||||
@@ -117,8 +113,14 @@ import javax.net.ssl.SSLPeerUnverifiedException
|
||||
* [CertificatePinner] can not be used to pin self-signed certificate if such certificate is not
|
||||
* accepted by [javax.net.ssl.TrustManager].
|
||||
*
|
||||
* @see [OWASP: Certificate and Public Key
|
||||
* Pinning](https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning)
|
||||
* See also [OWASP: Certificate and Public Key Pinning][owasp].
|
||||
*
|
||||
* [charles]: http://charlesproxy.com
|
||||
* [fiddler]: http://fiddlertool.com
|
||||
* [langley]: http://goo.gl/AIx3e5
|
||||
* [owasp]: https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning
|
||||
* [rfc_7469]: http://tools.ietf.org/html/rfc7469
|
||||
* [static_certificates]: http://goo.gl/XDh6je
|
||||
*/
|
||||
class CertificatePinner internal constructor(
|
||||
private val pins: Set<Pin>,
|
||||
|
||||
@@ -46,7 +46,7 @@ class Challenge(
|
||||
return Challenge(scheme, authParams)
|
||||
}
|
||||
|
||||
/** Returns the authentication scheme, like [Basic]. */
|
||||
/** Returns the authentication scheme, like `Basic`. */
|
||||
fun scheme() = scheme
|
||||
|
||||
/**
|
||||
|
||||
@@ -16,21 +16,24 @@
|
||||
package okhttp3
|
||||
|
||||
/**
|
||||
* [TLS cipher suites](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml).
|
||||
* [TLS cipher suites][iana_tls_parameters].
|
||||
*
|
||||
* **Not all cipher suites are supported on all platforms.** As newer cipher suites are created (for
|
||||
* stronger privacy, better performance, etc.) they will be adopted by the platform and then exposed
|
||||
* here. Cipher suites that are not available on either Android (through API level 24) or Java
|
||||
* (through JDK 9) are omitted for brevity.
|
||||
*
|
||||
* See [Android SSLEngine](https://developer.android.com/reference/javax/net/ssl/SSLEngine.html)
|
||||
* which lists the cipher suites supported by Android.
|
||||
* See [Android SSLEngine][sslengine] which lists the cipher suites supported by Android.
|
||||
*
|
||||
* See [JDK 10 Providers](https://docs.oracle.com/javase/10/security/oracle-providers.htm)
|
||||
* which lists the cipher suites supported by Oracle.
|
||||
* See [JDK Providers][oracle_providers] which lists the cipher suites supported by Oracle.
|
||||
*
|
||||
* See [NativeCrypto.java](https://github.com/google/conscrypt/blob/master/common/src/main/java/org/conscrypt/NativeCrypto.java)
|
||||
* from Conscrypt, which lists the cipher suites supported by Conscrypt.
|
||||
* See [NativeCrypto.java][conscrypt_providers] which lists the cipher suites supported by
|
||||
* Conscrypt.
|
||||
*
|
||||
* [iana_tls_parameters]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml
|
||||
* [sslengine]: https://developer.android.com/reference/javax/net/ssl/SSLEngine.html
|
||||
* [oracle_providers]: https://docs.oracle.com/javase/10/security/oracle-providers.htm
|
||||
* [conscrypt_providers]: https://github.com/google/conscrypt/blob/master/common/src/main/java/org/conscrypt/NativeCrypto.java
|
||||
*/
|
||||
class CipherSuite private constructor(
|
||||
private val javaName: String
|
||||
|
||||
@@ -23,14 +23,13 @@ import java.net.Socket
|
||||
* HTTP request/response exchanges. Connections may be direct to the origin server or via a proxy.
|
||||
*
|
||||
* Typically instances of this class are created, connected and exercised automatically by the HTTP
|
||||
* client. Applications may use this class to monitor HTTP connections as members of a [connection
|
||||
* pool][ConnectionPool].
|
||||
* client. Applications may use this class to monitor HTTP connections as members of a
|
||||
* [connection pool][ConnectionPool].
|
||||
*
|
||||
* Do not confuse this class with the misnamed `HttpURLConnection`, which isn't so much a connection
|
||||
* as a single request/response exchange.
|
||||
*
|
||||
* Modern TLS
|
||||
* ----------
|
||||
* ## Modern TLS
|
||||
*
|
||||
* There are trade-offs when selecting which options to include when negotiating a secure connection
|
||||
* to a remote host. Newer TLS options are quite useful:
|
||||
@@ -45,8 +44,7 @@ import java.net.Socket
|
||||
* avoiding these options entirely, this class allows a connection to be attempted with modern
|
||||
* options and then retried without them should the attempt fail.
|
||||
*
|
||||
* Connection Reuse
|
||||
* ----------------
|
||||
* ## Connection Reuse
|
||||
*
|
||||
* Each connection can carry a varying number of streams, depending on the underlying protocol being
|
||||
* used. HTTP/1.x connections can carry either zero or one streams. HTTP/2 connections can carry any
|
||||
@@ -73,9 +71,9 @@ interface Connection {
|
||||
fun route(): Route
|
||||
|
||||
/**
|
||||
* Returns the socket that this connection is using. Returns an [SSL
|
||||
* socket][javax.net.ssl.SSLSocket] if this connection is HTTPS. If this is an HTTP/2 connection
|
||||
* the socket may be shared by multiple concurrent calls.
|
||||
* Returns the socket that this connection is using. Returns an
|
||||
* [SSL socket][javax.net.ssl.SSLSocket] if this connection is HTTPS. If this is an HTTP/2
|
||||
* connection the socket may be shared by multiple concurrent calls.
|
||||
*/
|
||||
fun socket(): Socket
|
||||
|
||||
|
||||
@@ -40,9 +40,9 @@ import javax.net.ssl.SSLSocket
|
||||
* The configuration of each spec changes with each OkHttp release. This is annoying: upgrading
|
||||
* your OkHttp library can break connectivity to certain web servers! But it’s a necessary annoyance
|
||||
* because the TLS ecosystem is dynamic and staying up to date is necessary to stay secure. See
|
||||
* [OkHttp's TLS
|
||||
* Configuration History](https://github.com/square/okhttp/wiki/TLS-Configuration-History) to track
|
||||
* these changes.
|
||||
* [OkHttp's TLS Configuration History][tls_history] to track these changes.
|
||||
*
|
||||
* [tls_history]: https://github.com/square/okhttp/wiki/TLS-Configuration-History
|
||||
*/
|
||||
class ConnectionSpec internal constructor(builder: Builder) {
|
||||
val isTls: Boolean = builder.tls
|
||||
@@ -196,7 +196,7 @@ class ConnectionSpec internal constructor(builder: Builder) {
|
||||
this.cipherSuites = null
|
||||
}
|
||||
|
||||
fun cipherSuites(vararg cipherSuites: CipherSuite) = apply {
|
||||
fun cipherSuites(vararg cipherSuites: CipherSuite): Builder = apply {
|
||||
require(tls) { "no cipher suites for cleartext connections" }
|
||||
val strings = cipherSuites.map(CipherSuite::javaName).toTypedArray()
|
||||
return cipherSuites(*strings)
|
||||
@@ -214,7 +214,7 @@ class ConnectionSpec internal constructor(builder: Builder) {
|
||||
this.tlsVersions = null
|
||||
}
|
||||
|
||||
fun tlsVersions(vararg tlsVersions: TlsVersion) = apply {
|
||||
fun tlsVersions(vararg tlsVersions: TlsVersion): Builder = apply {
|
||||
require(tls) { "no TLS versions for cleartext connections" }
|
||||
|
||||
val strings = tlsVersions.map(TlsVersion::javaName).toTypedArray()
|
||||
|
||||
@@ -34,8 +34,10 @@ import java.util.regex.Pattern
|
||||
/**
|
||||
* An [RFC 6265](http://tools.ietf.org/html/rfc6265) Cookie.
|
||||
*
|
||||
* This class doesn't support additional attributes on cookies, like [Chromium's Priority=HIGH
|
||||
* extension](https://code.google.com/p/chromium/issues/detail?id=232693).
|
||||
* This class doesn't support additional attributes on cookies, like
|
||||
* [Chromium's Priority=HIGH extension][chromium_extension].
|
||||
*
|
||||
* [chromium_extension]: https://code.google.com/p/chromium/issues/detail?id=232693
|
||||
*/
|
||||
class Cookie private constructor(
|
||||
private val name: String,
|
||||
|
||||
@@ -24,9 +24,10 @@ package okhttp3
|
||||
*
|
||||
* As persistence, implementations of this interface must also provide storage of cookies. Simple
|
||||
* implementations may store cookies in memory; sophisticated ones may use the file system or
|
||||
* database to hold accepted cookies. The [cookie storage
|
||||
* model](https://tools.ietf.org/html/rfc6265#section-5.3) specifies policies for updating and
|
||||
* expiring cookies.
|
||||
* database to hold accepted cookies. The [cookie storage model][rfc_6265_53] specifies policies for
|
||||
* updating and expiring cookies.
|
||||
*
|
||||
* [rfc_6265_53]: https://tools.ietf.org/html/rfc6265#section-5.3
|
||||
*/
|
||||
interface CookieJar {
|
||||
/**
|
||||
|
||||
@@ -89,8 +89,7 @@ import java.util.LinkedHashSet
|
||||
* https://www.youtube.com/watch?v=cbP2N1BQdYc
|
||||
* ```
|
||||
*
|
||||
* What's in a URL?
|
||||
* ----------------
|
||||
* ## What's in a URL?
|
||||
*
|
||||
* A URL has several components.
|
||||
*
|
||||
@@ -98,7 +97,7 @@ import java.util.LinkedHashSet
|
||||
*
|
||||
* Sometimes referred to as *protocol*, A URL's scheme describes what mechanism should be used to
|
||||
* retrieve the resource. Although URLs have many schemes (`mailto`, `file`, `ftp`), this class only
|
||||
* supports `http` and `https`. Use [ java.net.URI][URI] for URLs with arbitrary schemes.
|
||||
* supports `http` and `https`. Use [java.net.URI][URI] for URLs with arbitrary schemes.
|
||||
*
|
||||
* ### Username and Password
|
||||
*
|
||||
@@ -127,16 +126,16 @@ import java.util.LinkedHashSet
|
||||
* ### Path
|
||||
*
|
||||
* The path identifies a specific resource on the host. Paths have a hierarchical structure like
|
||||
* "/square/okhttp/issues/1486" and decompose into a list of segments like ["square", "okhttp",
|
||||
* "issues", "1486"].
|
||||
* "/square/okhttp/issues/1486" and decompose into a list of segments like `["square", "okhttp",
|
||||
* "issues", "1486"]`.
|
||||
*
|
||||
* This class offers methods to compose and decompose paths by segment. It composes each path
|
||||
* from a list of segments by alternating between "/" and the encoded segment. For example the
|
||||
* segments ["a", "b"] build "/a/b" and the segments ["a", "b", ""] build "/a/b/".
|
||||
* segments `["a", "b"]` build "/a/b" and the segments `["a", "b", ""]` build "/a/b/".
|
||||
*
|
||||
* If a path's last segment is the empty string then the path ends with "/". This class always
|
||||
* builds non-empty paths: if the path is omitted it defaults to "/". The default path's segment
|
||||
* list is a single empty string: [""].
|
||||
* list is a single empty string: `[""]`.
|
||||
*
|
||||
* ### Query
|
||||
*
|
||||
@@ -150,8 +149,7 @@ import java.util.LinkedHashSet
|
||||
* The fragment is optional: it can be null, empty, or non-empty. Unlike host, port, path, and
|
||||
* query the fragment is not sent to the webserver: it's private to the client.
|
||||
*
|
||||
* Encoding
|
||||
* --------
|
||||
* ## Encoding
|
||||
*
|
||||
* Each component must be encoded before it is embedded in the complete URL. As we saw above, the
|
||||
* string `cute #puppies` is encoded as `cute%20%23puppies` when used as a query parameter value.
|
||||
@@ -191,22 +189,20 @@ import java.util.LinkedHashSet
|
||||
* Hostnames have different requirements and use a different encoding scheme. It consists of IDNA
|
||||
* mapping and Punycode encoding.
|
||||
*
|
||||
* In order to avoid confusion and discourage phishing attacks, [IDNA
|
||||
* Mapping](http://www.unicode.org/reports/tr46/#ToASCII) transforms names to avoid confusing
|
||||
* characters. This includes basic case folding: transforming shouting `SQUARE.COM` into cool and
|
||||
* casual `square.com`. It also handles more exotic characters. For example, the Unicode trademark
|
||||
* sign (™) could be confused for the letters "TM" in `http://ho™mail.com`. To mitigate this, the
|
||||
* single character (™) maps to the string (tm). There is similar policy for all of the 1.1 million
|
||||
* Unicode code points. Note that some code points such as "\ud83c\udf69" are not mapped and cannot
|
||||
* be used in a hostname.
|
||||
* In order to avoid confusion and discourage phishing attacks, [IDNA Mapping][idna] transforms
|
||||
* names to avoid confusing characters. This includes basic case folding: transforming shouting
|
||||
* `SQUARE.COM` into cool and casual `square.com`. It also handles more exotic characters. For
|
||||
* example, the Unicode trademark sign (™) could be confused for the letters "TM" in
|
||||
* `http://ho™mail.com`. To mitigate this, the single character (™) maps to the string (tm). There
|
||||
* is similar policy for all of the 1.1 million Unicode code points. Note that some code points such
|
||||
* as "\ud83c\udf69" are not mapped and cannot be used in a hostname.
|
||||
*
|
||||
* [Punycode](http://ietf.org/rfc/rfc3492.txt) converts a Unicode string to an ASCII string to make
|
||||
* international domain names work everywhere. For example, "σ" encodes as "xn--4xa". The encoded
|
||||
* string is not human readable, but can be used with classes like [InetAddress] to establish
|
||||
* connections.
|
||||
*
|
||||
* Why another URL model?
|
||||
* ----------------------
|
||||
* ## Why another URL model?
|
||||
*
|
||||
* Java includes both [java.net.URL][URL] and [java.net.URI][URI]. We offer a new URL
|
||||
* model to address problems that the others don't.
|
||||
@@ -287,6 +283,8 @@ import java.util.LinkedHashSet
|
||||
* This class has a modern API. It avoids punitive checked exceptions: [get] throws
|
||||
* [IllegalArgumentException] on invalid input or [parse] returns null if the input is an invalid
|
||||
* URL. You can even be explicit about whether each component has been encoded already.
|
||||
*
|
||||
* [idna]: http://www.unicode.org/reports/tr46/#ToASCII
|
||||
*/
|
||||
class HttpUrl internal constructor(builder: Builder) {
|
||||
|
||||
|
||||
@@ -20,8 +20,10 @@ import java.util.Locale
|
||||
import java.util.regex.Pattern
|
||||
|
||||
/**
|
||||
* An [RFC 2045](http://tools.ietf.org/html/rfc2045) Media Type, appropriate to describe the
|
||||
* content type of an HTTP request or response body.
|
||||
* An [RFC 2045][rfc_2045] Media Type, appropriate to describe the content type of an HTTP request
|
||||
* or response body.
|
||||
*
|
||||
* [rfc_2045]: http://tools.ietf.org/html/rfc2045
|
||||
*/
|
||||
class MediaType private constructor(
|
||||
private val mediaType: String,
|
||||
|
||||
@@ -49,8 +49,7 @@ import kotlin.DeprecationLevel.ERROR
|
||||
/**
|
||||
* Factory for [calls][Call], which can be used to send HTTP requests and read their responses.
|
||||
*
|
||||
* OkHttpClients Should Be Shared
|
||||
* ------------------------------
|
||||
* ## OkHttpClients Should Be Shared
|
||||
*
|
||||
* OkHttp performs best when you create a single `OkHttpClient` instance and reuse it for all of
|
||||
* your HTTP calls. This is because each client holds its own connection pool and thread pools.
|
||||
@@ -74,8 +73,7 @@ import kotlin.DeprecationLevel.ERROR
|
||||
* .build();
|
||||
* ```
|
||||
*
|
||||
* Customize Your Client With newBuilder()
|
||||
* ---------------------------------------
|
||||
* ## Customize Your Client With newBuilder()
|
||||
*
|
||||
* You can customize a shared OkHttpClient instance with [newBuilder]. This builds a client that
|
||||
* shares the same connection pool, thread pools, and configuration. Use the builder methods to
|
||||
@@ -90,8 +88,7 @@ import kotlin.DeprecationLevel.ERROR
|
||||
* Response response = eagerClient.newCall(request).execute();
|
||||
* ```
|
||||
*
|
||||
* Shutdown Isn't Necessary
|
||||
* ------------------------
|
||||
* ## Shutdown Isn't Necessary
|
||||
*
|
||||
* The threads and connections that are held will be released automatically if they remain idle. But
|
||||
* if you are writing a application that needs to aggressively release unused resources you may do
|
||||
@@ -454,8 +451,8 @@ open class OkHttpClient internal constructor(
|
||||
* If the server does not respond to each ping with a pong within `interval`, this client will
|
||||
* assume that connectivity has been lost. When this happens on a web socket the connection is
|
||||
* canceled and its listener is [notified][WebSocketListener.onFailure]. When it happens on an
|
||||
* HTTP/2 connection the connection is closed and any calls it is carrying [will fail with an
|
||||
* IOException][java.io.IOException].
|
||||
* HTTP/2 connection the connection is closed and any calls it is carrying
|
||||
* [will fail with an IOException][java.io.IOException].
|
||||
*
|
||||
* The default value of 0 disables client-initiated pings.
|
||||
*/
|
||||
@@ -471,8 +468,8 @@ open class OkHttpClient internal constructor(
|
||||
* If the server does not respond to each ping with a pong within `interval`, this client will
|
||||
* assume that connectivity has been lost. When this happens on a web socket the connection is
|
||||
* canceled and its listener is [notified][WebSocketListener.onFailure]. When it happens on an
|
||||
* HTTP/2 connection the connection is closed and any calls it is carrying [will fail with an
|
||||
* IOException][java.io.IOException].
|
||||
* HTTP/2 connection the connection is closed and any calls it is carrying
|
||||
* [will fail with an IOException][java.io.IOException].
|
||||
*
|
||||
* The default value of 0 disables client-initiated pings.
|
||||
*/
|
||||
@@ -694,20 +691,24 @@ open class OkHttpClient internal constructor(
|
||||
*
|
||||
* The following protocols are currently supported:
|
||||
*
|
||||
* * [http/1.1](http://www.w3.org/Protocols/rfc2616/rfc2616.html)
|
||||
* * [h2](https://tools.ietf.org/html/rfc7540)
|
||||
* * [h2 with prior knowledge(cleartext only)](https://tools.ietf.org/html/rfc7540#section-3.4)
|
||||
* * [http/1.1][rfc_2616]
|
||||
* * [h2][rfc_7540]
|
||||
* * [h2 with prior knowledge(cleartext only)][rfc_7540_34]
|
||||
*
|
||||
* **This is an evolving set.** Future releases include support for transitional
|
||||
* protocols. The http/1.1 transport will never be dropped.
|
||||
*
|
||||
* If multiple protocols are specified,
|
||||
* [ALPN](http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg) will be used to negotiate
|
||||
* a transport. Protocol negotiation is only attempted for HTTPS URLs.
|
||||
* If multiple protocols are specified, [ALPN][alpn] will be used to negotiate a transport.
|
||||
* Protocol negotiation is only attempted for HTTPS URLs.
|
||||
*
|
||||
* [Protocol.HTTP_1_0] is not supported in this set. Requests are initiated with `HTTP/1.1`. If
|
||||
* the server responds with `HTTP/1.0`, that will be exposed by [Response.protocol].
|
||||
*
|
||||
* [alpn]: http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg
|
||||
* [rfc_2616]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
|
||||
* [rfc_7540]: https://tools.ietf.org/html/rfc7540
|
||||
* [rfc_7540_34]: https://tools.ietf.org/html/rfc7540#section-3.4
|
||||
*
|
||||
* @param protocols the protocols to use, in order of preference. If the list contains
|
||||
* [Protocol.H2_PRIOR_KNOWLEDGE] then that must be the only protocol and HTTPS URLs will not
|
||||
* be supported. Otherwise the list must contain [Protocol.HTTP_1_1]. The list must
|
||||
|
||||
@@ -18,15 +18,15 @@ package okhttp3
|
||||
import java.io.IOException
|
||||
|
||||
/**
|
||||
* Protocols that OkHttp implements for
|
||||
* [ALPN](http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg) selection.
|
||||
* Protocols that OkHttp implements for [ALPN][ietf_alpn] selection.
|
||||
*
|
||||
* Protocol vs Scheme
|
||||
* ------------------
|
||||
* ## Protocol vs Scheme
|
||||
*
|
||||
* Despite its name, [java.net.URL.getProtocol] returns the [scheme][java.net.URI.getScheme] (http,
|
||||
* https, etc.) of the URL, not the protocol (http/1.1, spdy/3.1, etc.). OkHttp uses the word
|
||||
* *protocol* to identify how HTTP messages are framed.
|
||||
*
|
||||
* [ietf_alpn]: http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg
|
||||
*/
|
||||
enum class Protocol(private val protocol: String) {
|
||||
/**
|
||||
@@ -37,8 +37,9 @@ enum class Protocol(private val protocol: String) {
|
||||
/**
|
||||
* A plaintext framing that includes persistent connections.
|
||||
*
|
||||
* This version of OkHttp implements [RFC 7230](https://tools.ietf.org/html/rfc7230), and tracks
|
||||
* revisions to that spec.
|
||||
* This version of OkHttp implements [RFC 7230][rfc_7230], and tracks revisions to that spec.
|
||||
*
|
||||
* [rfc_7230]: https://tools.ietf.org/html/rfc7230
|
||||
*/
|
||||
HTTP_1_1("http/1.1"),
|
||||
|
||||
@@ -66,7 +67,9 @@ enum class Protocol(private val protocol: String) {
|
||||
* Cleartext HTTP/2 with no "upgrade" round trip. This option requires the client to have prior
|
||||
* knowledge that the server supports cleartext HTTP/2.
|
||||
*
|
||||
* @see [Starting HTTP/2 with Prior Knowledge](https://tools.ietf.org/html/rfc7540.section-3.4)
|
||||
* See also [Starting HTTP/2 with Prior Knowledge][rfc_7540_34].
|
||||
*
|
||||
* [rfc_7540_34]: https://tools.ietf.org/html/rfc7540.section-3.4
|
||||
*/
|
||||
H2_PRIOR_KNOWLEDGE("h2_prior_knowledge"),
|
||||
|
||||
@@ -84,7 +87,9 @@ enum class Protocol(private val protocol: String) {
|
||||
* Returns the string used to identify this protocol for ALPN, like "http/1.1", "spdy/3.1" or
|
||||
* "h2".
|
||||
*
|
||||
* @see [IANA tls-extensiontype-values](https://www.iana.org/assignments/tls-extensiontype-values)
|
||||
* See also [IANA tls-extensiontype-values][iana].
|
||||
*
|
||||
* [iana]: https://www.iana.org/assignments/tls-extensiontype-values
|
||||
*/
|
||||
override fun toString() = protocol
|
||||
|
||||
|
||||
@@ -51,7 +51,9 @@ class Route(
|
||||
|
||||
/**
|
||||
* Returns true if this route tunnels HTTPS through an HTTP proxy.
|
||||
* See [RFC 2817, Section 5.2](http://www.ietf.org/rfc/rfc2817.txt).
|
||||
* See [RFC 2817, Section 5.2][rfc_2817].
|
||||
*
|
||||
* [rfc_2817]: http://www.ietf.org/rfc/rfc2817.txt
|
||||
*/
|
||||
fun requiresTunnel(): Boolean {
|
||||
return address.sslSocketFactory() != null && proxy.type() == Proxy.Type.HTTP
|
||||
|
||||
@@ -21,8 +21,7 @@ import okio.ByteString
|
||||
* A non-blocking interface to a web socket. Use the [factory][WebSocket.Factory] to create
|
||||
* instances; usually this is [OkHttpClient].
|
||||
*
|
||||
* Web Socket Lifecycle
|
||||
* --------------------
|
||||
* ## Web Socket Lifecycle
|
||||
*
|
||||
* Upon normal operation each web socket progresses through a sequence of states:
|
||||
*
|
||||
@@ -96,8 +95,8 @@ interface WebSocket {
|
||||
* This returns true if a graceful shutdown was initiated by this call. It returns false if
|
||||
* a graceful shutdown was already underway or if the web socket is already closed or canceled.
|
||||
*
|
||||
* @param code Status code as defined by [Section 7.4 of RFC
|
||||
* 6455](http://tools.ietf.org/html/rfc6455#section-7.4).
|
||||
* @param code Status code as defined by
|
||||
* [Section 7.4 of RFC 6455](http://tools.ietf.org/html/rfc6455#section-7.4).
|
||||
* @param reason Reason for shutting down or null.
|
||||
* @throws IllegalArgumentException if code is invalid.
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user