Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/*
* Copyright (C) 2017 Square, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package okhttp3
import java.io.IOException
import java.net.InetAddress
import java.net.InetSocketAddress
import java.net.Proxy
/**
* Listener for metrics events. Extend this class to monitor the quantity, size, and duration of
* your application's HTTP calls.
*
* All start/connect/acquire events will eventually receive a matching end/release event, either
* successful (non-null parameters), or failed (non-null throwable). The first common parameters of
* each event pair are used to link the event in case of concurrent or repeated events e.g.
* `dnsStart(call, domainName)` → `dnsEnd(call, domainName, inetAddressList)`.
*
* Events are typically nested with this structure:
*
* * call ([callStart], [callEnd], [callFailed])
* * proxy selection ([proxySelectStart], [proxySelectEnd])
* * dns ([dnsStart], [dnsEnd])
* * connect ([connectStart], [connectEnd], [connectFailed])
* * secure connect ([secureConnectStart], [secureConnectEnd])
* * connection held ([connectionAcquired], [connectionReleased])
* * request ([requestFailed])
* * headers ([requestHeadersStart], [requestHeadersEnd])
* * body ([requestBodyStart], [requestBodyEnd])
* * response ([responseFailed])
* * headers ([responseHeadersStart], [responseHeadersEnd])
* * body ([responseBodyStart], [responseBodyEnd])
*
* This nesting is typical but not strict. For example, when calls use "Expect: continue" the
* request body start and end events occur within the response header events. Similarly,
* [duplex calls][RequestBody.isDuplex] interleave the request and response bodies.
*
* Since connections may be reused, the proxy selection, DNS, and connect events may not be present
* for a call. In future releases of OkHttp these events may also occur concurrently to permit
* multiple routes to be attempted simultaneously.
*
* Events and sequences of events may be repeated for retries and follow-ups.
*
* All event methods must execute fast, without external locking, cannot throw exceptions, attempt
* to mutate the event parameters, or be re-entrant back into the client. Any IO - writing to files
* or network should be done asynchronously.
*/
abstract class EventListener {
/**
* Invoked as soon as a call is enqueued or executed by a client. In case of thread or stream
* limits, this call may be executed well before processing the request is able to begin.
*
* This will be invoked only once for a single [Call]. Retries of different routes or redirects
* will be handled within the boundaries of a single [callStart] and [callEnd]/[callFailed] pair.
*/
open fun callStart(call: Call) {
}
/**
* Invoked prior to a proxy selection.
*
* This will be invoked for route selection regardless of whether the client
* is configured with a single proxy, a proxy selector, or neither.
*
* @param url a URL with only the scheme, hostname, and port specified.
*/
open fun proxySelectStart(
call: Call,
url: HttpUrl,
) {
}
/**
* Invoked after proxy selection.
*
* Note that the list of proxies is never null, but it may be a list containing
* only [Proxy.NO_PROXY]. This comes up in several situations:
*
* * If neither a proxy nor proxy selector is configured.
* * If the proxy is configured explicitly as [Proxy.NO_PROXY].
* * If the proxy selector returns only [Proxy.NO_PROXY].
* * If the proxy selector returns an empty list or null.
*
* Otherwise it lists the proxies in the order they will be attempted.
*
* @param url a URL with only the scheme, hostname, and port specified.
*/
open fun proxySelectEnd(
call: Call,
url: HttpUrl,
proxies: List<@JvmSuppressWildcards Proxy>,
) {
}
/**
* Invoked just prior to a DNS lookup. See [Dns.lookup].
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response to the
* [Call.request] is a redirect to a different host.
*
* If the [Call] is able to reuse an existing pooled connection, this method will not be invoked.
* See [ConnectionPool].
*/
open fun dnsStart(
call: Call,
domainName: String,
) {
}
/**
* Invoked immediately after a DNS lookup.
*
* This method is invoked after [dnsStart].
*/
open fun dnsEnd(
call: Call,
domainName: String,
inetAddressList: List<@JvmSuppressWildcards InetAddress>,
) {
}
/**
* Invoked just prior to initiating a socket connection.
*
* This method will be invoked if no existing connection in the [ConnectionPool] can be reused.
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response to the
* [Call.request] is a redirect to a different address, or a connection is retried.
*/
open fun connectStart(
call: Call,
inetSocketAddress: InetSocketAddress,
proxy: Proxy,
) {
}
/**
* Invoked just prior to initiating a TLS connection.
*
* This method is invoked if the following conditions are met:
*
* * The [Call.request] requires TLS.
*
* * No existing connection from the [ConnectionPool] can be reused.
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response to the
* [Call.request] is a redirect to a different address, or a connection is retried.
*/
open fun secureConnectStart(call: Call) {
}
/**
* Invoked immediately after a TLS connection was attempted.
*
* This method is invoked after [secureConnectStart].
*/
open fun secureConnectEnd(
call: Call,
handshake: Handshake?,
) {
}
/**
* Invoked immediately after a socket connection was attempted.
*
* If the `call` uses HTTPS, this will be invoked after [secureConnectEnd], otherwise it will
* invoked after [connectStart].
*/
open fun connectEnd(
call: Call,
inetSocketAddress: InetSocketAddress,
proxy: Proxy,
protocol: Protocol?,
) {
}
/**
* Invoked when a connection attempt fails. This failure is not terminal if further routes are
* available and failure recovery is enabled.
*
* If the `call` uses HTTPS, this will be invoked after [secureConnectStart], otherwise it will
* invoked after [connectStart].
*/
open fun connectFailed(
call: Call,
inetSocketAddress: InetSocketAddress,
proxy: Proxy,
protocol: Protocol?,
ioe: IOException,
) {
}
/**
* Invoked after a connection has been acquired for the `call`.
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response
* to the [Call.request] is a redirect to a different address.
*/
open fun connectionAcquired(
call: Call,
connection: Connection,
) {
}
/**
* Invoked after a connection has been released for the `call`.
*
* This method is always invoked after [connectionAcquired].
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response to the
* [Call.request] is a redirect to a different address.
*/
open fun connectionReleased(
call: Call,
connection: Connection,
) {
}
/**
* Invoked just prior to sending request headers.
*
* The connection is implicit, and will generally relate to the last [connectionAcquired] event.
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response to the
* [Call.request] is a redirect to a different address.
*/
open fun requestHeadersStart(call: Call) {
}
/**
* Invoked immediately after sending request headers.
*
* This method is always invoked after [requestHeadersStart].
*
* @param request the request sent over the network. It is an error to access the body of this
* request.
*/
open fun requestHeadersEnd(
call: Call,
request: Request,
) {
}
/**
* Invoked just prior to sending a request body. Will only be invoked for request allowing and
* having a request body to send.
*
* The connection is implicit, and will generally relate to the last [connectionAcquired] event.
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response to the
* [Call.request] is a redirect to a different address.
*/
open fun requestBodyStart(call: Call) {
}
/**
* Invoked immediately after sending a request body.
*
* This method is always invoked after [requestBodyStart].
*/
open fun requestBodyEnd(
call: Call,
byteCount: Long,
) {
}
/**
* Invoked when a request fails to be written.
*
* This method is invoked after [requestHeadersStart] or [requestBodyStart]. Note that request
* failures do not necessarily fail the entire call.
*/
open fun requestFailed(
call: Call,
ioe: IOException,
) {
}
/**
* Invoked when response headers are first returned from the server.
*
* The connection is implicit, and will generally relate to the last [connectionAcquired] event.
*
* This can be invoked more than 1 time for a single [Call]. For example, if the response to the
* [Call.request] is a redirect to a different address.
*
* Prior to OkHttp 4.3 this was incorrectly invoked when the client was ready to read headers.
* This was misleading for tracing because it was too early.
*/
open fun responseHeadersStart(call: Call) {
}
/**
* Invoked immediately after receiving response headers.
*
* This method is always invoked after [responseHeadersStart].
*
* @param response the response received over the network. It is an error to access the body of
* this response.
*/
open fun responseHeadersEnd(
call: Call,
response: Response,
) {
}
/**
* Invoked when data from the response body is first available to the application.
*
* This is typically invoked immediately before bytes are returned to the application. If the
* response body is empty this is invoked immediately before returning that to the application.
*
* If the application closes the response body before attempting a read, this is invoked at the
* time it is closed.
*
* The connection is implicit, and will generally relate to the last [connectionAcquired] event.
*
* This will usually be invoked only 1 time for a single [Call], exceptions are a limited set of
* cases including failure recovery.
*
* Prior to OkHttp 4.3 this was incorrectly invoked when the client was ready to read the response
* body. This was misleading for tracing because it was too early.
*/
open fun responseBodyStart(call: Call) {
}
/**
* Invoked immediately after receiving a response body and completing reading it.
*
* Will only be invoked for requests having a response body e.g. won't be invoked for a web socket
* upgrade.
*
* If the response body is closed before the response body is exhausted, this is invoked at the
* time it is closed. In such calls [byteCount] is the number of bytes returned to the
* application. This may be smaller than the resource's byte count if were read to completion.
*
* This method is always invoked after [responseBodyStart].
*/
open fun responseBodyEnd(
call: Call,
byteCount: Long,
) {
}
/**
* Invoked when a response fails to be read.
*
* Note that response failures do not necessarily fail the entire call.
*
* Starting with OkHttp 4.3 this may be invoked without a prior call to [responseHeadersStart]
* or [responseBodyStart]. In earlier releases this method was documented to only be invoked after
* one of those methods.
*/
open fun responseFailed(
call: Call,
ioe: IOException,
) {
}
/**
* Invoked immediately after a call has completely ended. This includes delayed consumption
* of response body by the caller.
*
* This method is always invoked after [callStart].
*/
open fun callEnd(call: Call) {
}
/**
* Invoked when a call fails permanently.
*
* This method is always invoked after [callStart].
*/
open fun callFailed(
call: Call,
ioe: IOException,
) {
}
/**
* Invoked when a call is canceled.
*
* Like all methods in this interface, this is invoked on the thread that triggered the event. But
* while other events occur sequentially; cancels may occur concurrently with other events. For
* example, thread A may be executing [responseBodyStart] while thread B executes [canceled].
* Implementations must support such concurrent calls.
*
* Note that cancellation is best-effort and that a call may proceed normally after it has been
* canceled. For example, happy-path events like [requestHeadersStart] and [requestHeadersEnd] may
* occur after a call is canceled. Typically cancellation takes effect when an expensive I/O
* operation is required.
*
* This is invoked at most once, even if [Call.cancel] is invoked multiple times. It may be
* invoked at any point in a call's life, including before [callStart] and after [callEnd].
*/
open fun canceled(call: Call) {
}
/**
* Invoked when a call fails due to cache rules.
* For example, we're forbidden from using the network and the cache is insufficient
*/
open fun satisfactionFailure(
call: Call,
response: Response,
) {
}
/**
* Invoked when a result is served from the cache. The Response provided is the top level
* Response and normal event sequences will not be received.
*
* This event will only be received when a Cache is configured for the client.
*/
open fun cacheHit(
call: Call,
response: Response,
) {
}
/**
* Invoked when a response will be served from the network. The Response will be
* available from normal event sequences.
*
* This event will only be received when a Cache is configured for the client.
*/
open fun cacheMiss(call: Call) {
}
/**
* Invoked when a response will be served from the cache or network based on validating the
* cached Response freshness. Will be followed by cacheHit or cacheMiss after the network
* Response is available.
*
* This event will only be received when a Cache is configured for the client.
*/
open fun cacheConditionalHit(
call: Call,
cachedResponse: Response,
) {
}
fun interface Factory {
/**
* Creates an instance of the [EventListener] for a particular [Call]. The returned
* [EventListener] instance will be used during the lifecycle of [call].
*
* This method is invoked after [call] is created. See [OkHttpClient.newCall].
*
* **It is an error for implementations to issue any mutating operations on the [call] instance
* from this method.**
*/
fun create(call: Call): EventListener
}
companion object {
@JvmField
val NONE: EventListener =
object : EventListener() {
}
}
}
