Не подтверждена Коммит c18eb2bd создал по автору Andrey Aksenov's avatar Andrey Aksenov Зафиксировано автором GitHub
Просмотр файлов

KTOR-4334 api docs for client engines (#3009)

владелец ff13c093
Скрыть пробелы
Построчно Рядом
ktor-client/ktor-client-android/jvm/src/io/ktor/client/engine/android/Android.kt
Просмотр файла @ c18eb2bd
...@@ -8,8 +8,23 @@ import io.ktor.client.* ...@@ -8,8 +8,23 @@ import io.ktor.client.*
import io.ktor.client.engine.* import io.ktor.client.engine.*
/** /**
* [HttpClientEngineFactory] using a [UrlConnection] based backend implementation without additional dependencies * A JVM/Android client engine that uses `HttpURLConnection` under the hood.
* with the associated configuration [AndroidEngineConfig]. * You can use this engine if your application targets old Android versions (1.x+).
*
* To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(Android)
* ```
* To configure the engine, pass settings exposed by [AndroidEngineConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(Android) {
* engine {
* // this: AndroidEngineConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
public object Android : HttpClientEngineFactory<AndroidEngineConfig> { public object Android : HttpClientEngineFactory<AndroidEngineConfig> {
override fun create(block: AndroidEngineConfig.() -> Unit): HttpClientEngine = override fun create(block: AndroidEngineConfig.() -> Unit): HttpClientEngine =
......
ktor-client/ktor-client-android/jvm/src/io/ktor/client/engine/android/AndroidClientEngine.kt
Просмотр файла @ c18eb2bd
...@@ -25,7 +25,7 @@ import kotlin.coroutines.* ...@@ -25,7 +25,7 @@ import kotlin.coroutines.*
private val METHODS_WITHOUT_BODY = listOf(HttpMethod.Get, HttpMethod.Head) private val METHODS_WITHOUT_BODY = listOf(HttpMethod.Get, HttpMethod.Head)
/** /**
* Android client engine * An Android client engine.
*/ */
@OptIn(InternalAPI::class) @OptIn(InternalAPI::class)
public class AndroidClientEngine(override val config: AndroidEngineConfig) : HttpClientEngineBase("ktor-android") { public class AndroidClientEngine(override val config: AndroidEngineConfig) : HttpClientEngineBase("ktor-android") {
......
ktor-client/ktor-client-android/jvm/src/io/ktor/client/engine/android/AndroidEngineConfig.kt
Просмотр файла @ c18eb2bd
...@@ -9,28 +9,30 @@ import java.net.* ...@@ -9,28 +9,30 @@ import java.net.*
import javax.net.ssl.* import javax.net.ssl.*
/** /**
* Configuration for [Android] client engine. * A configuration for the [Android] client engine.
*/ */
public class AndroidEngineConfig : HttpClientEngineConfig() { public class AndroidEngineConfig : HttpClientEngineConfig() {
/** /**
* Max milliseconds to establish an HTTP connection - default 100 seconds. * Specifies a time period (in milliseconds) in which a client should establish a connection with a server.
* A value of 0 represents infinite. *
* Set this value to `0` to use an infinite timeout.
*/ */
public var connectTimeout: Int = 100_000 public var connectTimeout: Int = 100_000
/** /**
* Max milliseconds between TCP packets - default 100 seconds. * Specifies a maximum time (in milliseconds) of inactivity between two data packets when exchanging data with a server.
* A value of 0 represents infinite. *
* Set this value to `0` to use an infinite timeout.
*/ */
public var socketTimeout: Int = 100_000 public var socketTimeout: Int = 100_000
/** /**
* Https connection manipulator. inherited methods are not permitted. * Allows you to configure [HTTPS](https://ktor.io/docs/client-ssl.html) settings for this engine.
*/ */
public var sslManager: (HttpsURLConnection) -> Unit = {} public var sslManager: (HttpsURLConnection) -> Unit = {}
/** /**
* Engine specific request configuration. * Allows you to set engine-specific request configuration.
*/ */
public var requestConfig: HttpURLConnection.() -> Unit = {} public var requestConfig: HttpURLConnection.() -> Unit = {}
} }
ktor-client/ktor-client-apache/jvm/src/io/ktor/client/engine/apache/Apache.kt
Просмотр файла @ c18eb2bd
...@@ -8,10 +8,22 @@ import io.ktor.client.* ...@@ -8,10 +8,22 @@ import io.ktor.client.*
import io.ktor.client.engine.* import io.ktor.client.engine.*
/** /**
* [HttpClientEngineFactory] using `org.apache.httpcomponents.httpasyncclient` * A JVM client engine that uses the Apache HTTP client.
* with the associated configuration [ApacheEngineConfig].
* *
* Supports HTTP/2 and HTTP/1.x requests. * To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(Apache)
* ```
* To configure the engine, pass settings exposed by [ApacheEngineConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(Apache) {
* engine {
* // this: ApacheEngineConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
public object Apache : HttpClientEngineFactory<ApacheEngineConfig> { public object Apache : HttpClientEngineFactory<ApacheEngineConfig> {
override fun create(block: ApacheEngineConfig.() -> Unit): HttpClientEngine { override fun create(block: ApacheEngineConfig.() -> Unit): HttpClientEngine {
......
ktor-client/ktor-client-apache/jvm/src/io/ktor/client/engine/apache/ApacheEngineConfig.kt
Просмотр файла @ c18eb2bd
...@@ -10,47 +10,51 @@ import org.apache.http.impl.nio.client.* ...@@ -10,47 +10,51 @@ import org.apache.http.impl.nio.client.*
import javax.net.ssl.* import javax.net.ssl.*
/** /**
* Configuration for [Apache] implementation of [HttpClientEngineFactory]. * A configuration for the [Apache] client engine.
*/ */
public class ApacheEngineConfig : HttpClientEngineConfig() { public class ApacheEngineConfig : HttpClientEngineConfig() {
/** /**
* Whether or not, it will follow `Location` headers. `false` by default. * Specifies whether to follow redirects automatically.
* It uses the default number of redirects defined by Apache's HttpClient that is 50. * Disabled by default.
*
* _Note: By default, the Apache client allows `50` redirects._
*/ */
public var followRedirects: Boolean = false public var followRedirects: Boolean = false
/** /**
* Max milliseconds between TCP packets - default 10 seconds. * Specifies a maximum time (in milliseconds) of inactivity between two data packets when exchanging data with a server.
* A value of 0 represents infinite, while -1 represents system's default value. *
* Set this value to `0` to use an infinite timeout.
*/ */
public var socketTimeout: Int = 10_000 public var socketTimeout: Int = 10_000
/** /**
* Max milliseconds to establish an HTTP connection - default 10 seconds. * Specifies a time period (in milliseconds) in which a client should establish a connection with a server.
* A value of 0 represents infinite, while -1 represents system's default value. *
* A `0` value represents an infinite timeout, while `-1` represents a system's default value.
*/ */
public var connectTimeout: Int = 10_000 public var connectTimeout: Int = 10_000
/** /**
* Max milliseconds for the connection manager to start a request - default 20 seconds. * Specifies a time period (in milliseconds) in which a client should start a request.
* A value of 0 represents infinite, while -1 represents system's default value. *
* A `0` value represents an infinite timeout, while `-1` represents a system's default value.
*/ */
public var connectionRequestTimeout: Int = 20_000 public var connectionRequestTimeout: Int = 20_000
/** /**
* Optional Java's SSLContext allowing to set custom keys, * Allows you to configure [SSL](https://ktor.io/docs/client-ssl.html) settings for this engine.
* trust manager or custom source for secure random data
*/ */
public var sslContext: SSLContext? = null public var sslContext: SSLContext? = null
/** /**
* Custom processor for [RequestConfig.Builder]. * Specifies a custom processor for [RequestConfig.Builder].
*/ */
public var customRequest: (RequestConfig.Builder.() -> RequestConfig.Builder) = { this } public var customRequest: (RequestConfig.Builder.() -> RequestConfig.Builder) = { this }
private set private set
/** /**
* Custom processor for [HttpAsyncClientBuilder]. * Specifies a custom processor for [HttpAsyncClientBuilder].
*/ */
public var customClient: (HttpAsyncClientBuilder.() -> HttpAsyncClientBuilder) = { this } public var customClient: (HttpAsyncClientBuilder.() -> HttpAsyncClientBuilder) = { this }
private set private set
......
ktor-client/ktor-client-cio/jvmAndNix/src/io/ktor/client/engine/cio/CIOCommon.kt
Просмотр файла @ c18eb2bd
...@@ -9,10 +9,22 @@ import io.ktor.client.engine.* ...@@ -9,10 +9,22 @@ import io.ktor.client.engine.*
import io.ktor.util.* import io.ktor.util.*
/** /**
* [HttpClientEngineFactory] using a Coroutine based I/O implementation without additional dependencies * An asynchronous coroutine-based engine that can be used on JVM, Android, and Kotlin/Native.
* with the associated configuration [CIOEngineConfig].
* *
* Just supports HTTP/1.x and HTTPS requests. * To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(CIO)
* ```
* To configure the engine, pass settings exposed by [CIOEngineConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(CIO) {
* engine {
* // this: CIOEngineConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
public object CIO : HttpClientEngineFactory<CIOEngineConfig> { public object CIO : HttpClientEngineFactory<CIOEngineConfig> {
init { init {
......
ktor-client/ktor-client-cio/jvmAndNix/src/io/ktor/client/engine/cio/CIOEngineConfig.kt
Просмотр файла @ c18eb2bd
...@@ -9,73 +9,75 @@ import io.ktor.client.plugins.* ...@@ -9,73 +9,75 @@ import io.ktor.client.plugins.*
import io.ktor.network.tls.* import io.ktor.network.tls.*
/** /**
* Configuration for [CIO] client engine. * A configuration for the [CIO] client engine.
*/ */
public class CIOEngineConfig : HttpClientEngineConfig() { public class CIOEngineConfig : HttpClientEngineConfig() {
/** /**
* [Endpoint] settings. * Provides access to [Endpoint] settings.
*/ */
public val endpoint: EndpointConfig = EndpointConfig() public val endpoint: EndpointConfig = EndpointConfig()
/** /**
* [https] settings. * Allows you to configure [HTTPS](https://ktor.io/docs/client-ssl.html) settings for this engine.
*/ */
public val https: TLSConfigBuilder = TLSConfigBuilder() public val https: TLSConfigBuilder = TLSConfigBuilder()
/** /**
* Maximum allowed connections count. * Specifies the maximum number of connections used to make [requests](https://ktor.io/docs/request.html).
*/ */
public var maxConnectionsCount: Int = 1000 public var maxConnectionsCount: Int = 1000
/** /**
* Timeout to get send request headers and get first response bytes(in millis). * Specifies a time period (in milliseconds) required to process an HTTP call: from sending a request to receiving first response bytes.
* *
* Use 0 to disable. * To disable this timeout, set its value to `0`.
*/ */
public var requestTimeout: Long = 15000 public var requestTimeout: Long = 15000
/** /**
* [https] settings. * Allows you to configure [HTTPS](https://ktor.io/docs/client-ssl.html) settings for this engine.
*/ */
public fun https(block: TLSConfigBuilder.() -> Unit): TLSConfigBuilder = https.apply(block) public fun https(block: TLSConfigBuilder.() -> Unit): TLSConfigBuilder = https.apply(block)
} }
/** /**
* Configure [endpoint] settings. * Provides access to [Endpoint] settings.
*/ */
public fun CIOEngineConfig.endpoint(block: EndpointConfig.() -> Unit): EndpointConfig = endpoint.apply(block) public fun CIOEngineConfig.endpoint(block: EndpointConfig.() -> Unit): EndpointConfig = endpoint.apply(block)
/** /**
* [Endpoint] settings. * Contains [Endpoint] settings.
*/ */
public class EndpointConfig { public class EndpointConfig {
/** /**
* Maximum connections per single route. * Specifies the maximum number of connections for each host.
*
* @see [CIOEngineConfig.maxConnectionsCount]
*/ */
public var maxConnectionsPerRoute: Int = 100 public var maxConnectionsPerRoute: Int = 100
/** /**
* Connection keep-alive time in millis. * Specifies a connection keep-alive time (in milliseconds).
*/ */
public var keepAliveTime: Long = 5000 public var keepAliveTime: Long = 5000
/** /**
* Maximum number of requests per single pipeline. * Specifies a maximum number of requests to be sent over a single connection without waiting for the corresponding responses (HTTP pipelining).
*/ */
public var pipelineMaxSize: Int = 20 public var pipelineMaxSize: Int = 20
/** /**
* Connect timeout in millis. * Specifies a time period (in milliseconds) in which a client should establish a connection with a server.
*/ */
public var connectTimeout: Long = 5000 public var connectTimeout: Long = 5000
/** /**
* Socket timeout in millis. * Specifies a maximum time (in milliseconds) of inactivity between two data packets when exchanging data with a server.
*/ */
public var socketTimeout: Long = HttpTimeout.INFINITE_TIMEOUT_MS public var socketTimeout: Long = HttpTimeout.INFINITE_TIMEOUT_MS
/** /**
* Maximum number of connection attempts. * Specifies a maximum number of connection attempts.
*/ */
@Deprecated( @Deprecated(
"This is deprecated due to the misleading name. Use connectAttempts instead.", "This is deprecated due to the misleading name. Use connectAttempts instead.",
...@@ -89,13 +91,13 @@ public class EndpointConfig { ...@@ -89,13 +91,13 @@ public class EndpointConfig {
} }
/** /**
* Maximum number of connection attempts. * Specifies a maximum number of connection attempts.
* Note: this property affects only connection retries, but not request retries * Note: this property affects only connection retries, but not request retries.
*/ */
public var connectAttempts: Int = 1 public var connectAttempts: Int = 1
/** /**
* Allow socket to close output channel immediately on writing completion (TCP connection half close). * Allows a socket to close an output channel immediately on writing completion (half-closed TCP connection).
*/ */
public var allowHalfClose: Boolean = false public var allowHalfClose: Boolean = false
@Deprecated("Half closed TCP connection is not supported by all servers, use it at your own risk.") @Deprecated("Half closed TCP connection is not supported by all servers, use it at your own risk.")
......
ktor-client/ktor-client-cio/jvmAndNix/src/io/ktor/client/engine/cio/Endpoint.kt
Просмотр файла @ c18eb2bd
...@@ -206,7 +206,7 @@ internal class Endpoint( ...@@ -206,7 +206,7 @@ internal class Endpoint(
} }
/** /**
* Defines exact type of exception based on [connectAttempts] and [timeoutFails]. * Defines the exact type of exception based on [connectAttempts] and [timeoutFails].
*/ */
private fun getTimeoutException( private fun getTimeoutException(
connectAttempts: Int, connectAttempts: Int,
...@@ -218,8 +218,8 @@ internal class Endpoint( ...@@ -218,8 +218,8 @@ internal class Endpoint(
} }
/** /**
* Take timeout attributes from [config] and [HttpTimeout.HttpTimeoutCapabilityConfiguration] and returns a pair of * Takes timeout attributes from [config] and [HttpTimeout.HttpTimeoutCapabilityConfiguration] and returns a pair of
* connect timeout and socket timeout to be applied. * connection timeout and socket timeout to be applied.
*/ */
private fun retrieveTimeouts(requestData: HttpRequestData): Pair<Long, Long> { private fun retrieveTimeouts(requestData: HttpRequestData): Pair<Long, Long> {
val default = config.endpoint.connectTimeout to config.endpoint.socketTimeout val default = config.endpoint.connectTimeout to config.endpoint.socketTimeout
......
ktor-client/ktor-client-cio/jvmAndNix/src/io/ktor/client/engine/cio/EngineTasks.kt
Просмотр файла @ c18eb2bd
...@@ -27,7 +27,7 @@ internal data class ConnectionResponseTask( ...@@ -27,7 +27,7 @@ internal data class ConnectionResponseTask(
) )
/** /**
* Return true if request task contains timeout attributes specified using [HttpTimeout] plugin. * Returns `true` if a request task contains timeout attributes specified using the [HttpTimeout] plugin.
*/ */
private fun HttpRequestData.containsCustomTimeouts() = getCapabilityOrNull(HttpTimeout)?.let { private fun HttpRequestData.containsCustomTimeouts() = getCapabilityOrNull(HttpTimeout)?.let {
it.connectTimeoutMillis != null || it.socketTimeoutMillis != null it.connectTimeoutMillis != null || it.socketTimeoutMillis != null
......
ktor-client/ktor-client-core/js/src/io/ktor/client/engine/js/Js.kt
Просмотр файла @ c18eb2bd
...@@ -7,12 +7,26 @@ package io.ktor.client.engine.js ...@@ -7,12 +7,26 @@ package io.ktor.client.engine.js
import io.ktor.client.engine.* import io.ktor.client.engine.*
/** /**
* [HttpClientEngineFactory] using a fetch API to execute requests. * A JavaScript client engine that uses the fetch API to execute requests.
*
* To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(Js)
* ```
* You can also call the [JsClient] function to get the [Js] engine singleton:
* ```kotlin
* val client = JsClient()
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
public object Js : HttpClientEngineFactory<HttpClientEngineConfig> { public object Js : HttpClientEngineFactory<HttpClientEngineConfig> {
override fun create(block: HttpClientEngineConfig.() -> Unit): HttpClientEngine = override fun create(block: HttpClientEngineConfig.() -> Unit): HttpClientEngine =
JsClientEngine(HttpClientEngineConfig().apply(block)) JsClientEngine(HttpClientEngineConfig().apply(block))
} }
/**
* Creates a [Js] client engine.
*/
@JsName("JsClient") @JsName("JsClient")
public fun JsClient(): HttpClientEngineFactory<HttpClientEngineConfig> = Js public fun JsClient(): HttpClientEngineFactory<HttpClientEngineConfig> = Js
ktor-client/ktor-client-curl/desktop/src/io/ktor/client/engine/curl/Curl.kt
Просмотр файла @ c18eb2bd
...@@ -27,8 +27,22 @@ internal fun curlInitBridge(): Int = curl_global_init(CURL_GLOBAL_ALL.convert()) ...@@ -27,8 +27,22 @@ internal fun curlInitBridge(): Int = curl_global_init(CURL_GLOBAL_ALL.convert())
private val initHook = Curl private val initHook = Curl
/** /**
* [HttpClientEngineFactory] using a curl library in implementation * A Kotlin/Native client engine that can be used on desktop platforms.
* with the associated configuration [HttpClientEngineConfig]. *
* To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(Curl)
* ```
* To configure the engine, pass settings exposed by [CurlClientEngineConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(Curl) {
* engine {
* // this: CurlClientEngineConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
@OptIn(InternalAPI::class) @OptIn(InternalAPI::class)
public object Curl : HttpClientEngineFactory<CurlClientEngineConfig> { public object Curl : HttpClientEngineFactory<CurlClientEngineConfig> {
......
ktor-client/ktor-client-curl/desktop/src/io/ktor/client/engine/curl/CurlClientEngineConfig.kt
Просмотр файла @ c18eb2bd
...@@ -6,21 +6,21 @@ package io.ktor.client.engine.curl ...@@ -6,21 +6,21 @@ package io.ktor.client.engine.curl
import io.ktor.client.engine.* import io.ktor.client.engine.*
/**
* A configuration for the [Curl] client engine.
*/
public class CurlClientEngineConfig : HttpClientEngineConfig() { public class CurlClientEngineConfig : HttpClientEngineConfig() {
/** /**
* Forces proxy tunneling by setting CURLOPT_HTTPPROXYTUNNEL * Forces proxy tunneling by setting `CURLOPT_HTTPPROXYTUNNEL`.
*/ */
internal var forceProxyTunneling: Boolean = false internal var forceProxyTunneling: Boolean = false
/** /**
* Enable TLS host and certificate verification by setting options * Enables TLS host and certificate verification by setting the
* CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST. * `CURLOPT_SSL_VERIFYPEER` and `CURLOPT_SSL_VERIFYHOST` options.
* Similar to `-k/--insecure` curl option. * Similar to `-k/--insecure` curl option.
* *
* Setting this to `false` disables TLS verification so all connections will be insecure. * Setting this property to `false` is recommended only for testing purposes.
*
* While this is generally suitable for testing purpose,
* we do not recommend using this in production.
*/ */
public var sslVerify: Boolean = true public var sslVerify: Boolean = true
} }
ktor-client/ktor-client-darwin/darwin/src/io/ktor/client/engine/darwin/Darwin.kt
Просмотр файла @ c18eb2bd
...@@ -14,8 +14,23 @@ import platform.Foundation.* ...@@ -14,8 +14,23 @@ import platform.Foundation.*
private val initHook = Darwin private val initHook = Darwin
/** /**
* [HttpClientEngineFactory] using a [NSURLRequest] in implementation * A Kotlin/Native client engine that targets Darwin-based operating systems
* with the associated requestConfig [HttpClientEngineConfig]. * (such as macOS, iOS, tvOS, and so on) and uses `NSURLSession` internally.
*
* To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(Darwin)
* ```
* To configure the engine, pass settings exposed by [DarwinClientEngineConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(Darwin) {
* engine {
* // this: DarwinClientEngineConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
@OptIn(InternalAPI::class) @OptIn(InternalAPI::class)
public object Darwin : HttpClientEngineFactory<DarwinClientEngineConfig> { public object Darwin : HttpClientEngineFactory<DarwinClientEngineConfig> {
......
ktor-client/ktor-client-darwin/darwin/src/io/ktor/client/engine/darwin/DarwinClientEngineConfig.kt
Просмотр файла @ c18eb2bd
...@@ -9,7 +9,7 @@ import kotlinx.cinterop.* ...@@ -9,7 +9,7 @@ import kotlinx.cinterop.*
import platform.Foundation.* import platform.Foundation.*
/** /**
* Challenge handler type for [NSURLSession]. * A challenge handler type for [NSURLSession].
*/ */
@OptIn(UnsafeNumber::class) @OptIn(UnsafeNumber::class)
public typealias ChallengeHandler = ( public typealias ChallengeHandler = (
...@@ -20,11 +20,11 @@ public typealias ChallengeHandler = ( ...@@ -20,11 +20,11 @@ public typealias ChallengeHandler = (
) -> Unit ) -> Unit
/** /**
* Custom [DarwinClientEngine] config. * A configuration for the [Darwin] client engine.
*/ */
public class DarwinClientEngineConfig : HttpClientEngineConfig() { public class DarwinClientEngineConfig : HttpClientEngineConfig() {
/** /**
* Request configuration. * A request configuration.
*/ */
public var requestConfig: NSMutableURLRequest.() -> Unit = {} public var requestConfig: NSMutableURLRequest.() -> Unit = {}
@Deprecated( @Deprecated(
...@@ -36,7 +36,7 @@ public class DarwinClientEngineConfig : HttpClientEngineConfig() { ...@@ -36,7 +36,7 @@ public class DarwinClientEngineConfig : HttpClientEngineConfig() {
} }
/** /**
* Session configuration. * A session configuration.
*/ */
public var sessionConfig: NSURLSessionConfiguration.() -> Unit = {} public var sessionConfig: NSURLSessionConfiguration.() -> Unit = {}
@Deprecated( @Deprecated(
...@@ -55,7 +55,7 @@ public class DarwinClientEngineConfig : HttpClientEngineConfig() { ...@@ -55,7 +55,7 @@ public class DarwinClientEngineConfig : HttpClientEngineConfig() {
private set private set
/** /**
* Appends block with [NSMutableURLRequest] configuration to [requestConfig]. * Appends a block with the [NSMutableURLRequest] configuration to [requestConfig].
*/ */
public fun configureRequest(block: NSMutableURLRequest.() -> Unit) { public fun configureRequest(block: NSMutableURLRequest.() -> Unit) {
val old = requestConfig val old = requestConfig
...@@ -68,7 +68,7 @@ public class DarwinClientEngineConfig : HttpClientEngineConfig() { ...@@ -68,7 +68,7 @@ public class DarwinClientEngineConfig : HttpClientEngineConfig() {
} }
/** /**
* Appends block with [NSURLSessionConfiguration] configuration to [sessionConfig]. * Appends a block with the [NSURLSessionConfiguration] configuration to [sessionConfig].
*/ */
public fun configureSession(block: NSURLSessionConfiguration.() -> Unit) { public fun configureSession(block: NSURLSessionConfiguration.() -> Unit) {
val old = sessionConfig val old = sessionConfig
......
ktor-client/ktor-client-java/jvm/src/io/ktor/client/engine/java/Java.kt
Просмотр файла @ c18eb2bd
...@@ -9,8 +9,22 @@ import io.ktor.client.engine.* ...@@ -9,8 +9,22 @@ import io.ktor.client.engine.*
import io.ktor.util.* import io.ktor.util.*
/** /**
* [HttpClientEngineFactory] using a [Java] based backend implementation * A JVM client engine that uses the Java HTTP Client introduced in Java 11.
* with the associated configuration [JavaHttpConfig]. *
* To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(Java)
* ```
* To configure the engine, pass settings exposed by [JavaHttpConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(Java) {
* engine {
* // this: JavaHttpConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
public object Java : HttpClientEngineFactory<JavaHttpConfig> { public object Java : HttpClientEngineFactory<JavaHttpConfig> {
@OptIn(InternalAPI::class) @OptIn(InternalAPI::class)
......
ktor-client/ktor-client-java/jvm/src/io/ktor/client/engine/java/JavaHttpConfig.kt
Просмотр файла @ c18eb2bd
...@@ -8,7 +8,7 @@ import io.ktor.client.engine.* ...@@ -8,7 +8,7 @@ import io.ktor.client.engine.*
import java.net.http.* import java.net.http.*
/** /**
* Configuration for [Java] client engine. * A configuration for the [Java] client engine.
*/ */
public class JavaHttpConfig : HttpClientEngineConfig() { public class JavaHttpConfig : HttpClientEngineConfig() {
......
ktor-client/ktor-client-jetty/jvm/src/io/ktor/client/engine/jetty/Jetty.kt
Просмотр файла @ c18eb2bd
...@@ -9,10 +9,22 @@ import io.ktor.client.engine.* ...@@ -9,10 +9,22 @@ import io.ktor.client.engine.*
import io.ktor.util.* import io.ktor.util.*
/** /**
* [HttpClientEngineFactory] using `org.eclipse.jetty.http2:http2-client` * A JVM client engine that uses the Jetty HTTP client.
* with the associated configuration [JettyEngineConfig].
* *
* Just supports HTTP/2 requests. * To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(Jetty)
* ```
* To configure the engine, pass settings exposed by [JettyEngineConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(Jetty) {
* engine {
* // this: JettyEngineConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
public object Jetty : HttpClientEngineFactory<JettyEngineConfig> { public object Jetty : HttpClientEngineFactory<JettyEngineConfig> {
override fun create(block: JettyEngineConfig.() -> Unit): HttpClientEngine = override fun create(block: JettyEngineConfig.() -> Unit): HttpClientEngine =
......
ktor-client/ktor-client-jetty/jvm/src/io/ktor/client/engine/jetty/JettyEngineConfig.kt
Просмотр файла @ c18eb2bd
...@@ -9,23 +9,23 @@ import org.eclipse.jetty.http2.client.* ...@@ -9,23 +9,23 @@ import org.eclipse.jetty.http2.client.*
import org.eclipse.jetty.util.ssl.* import org.eclipse.jetty.util.ssl.*
/** /**
* Configuration for [Jetty] implementation of [HttpClientEngineFactory]. * A configuration for the [Jetty] client engine.
*/ */
public class JettyEngineConfig : HttpClientEngineConfig() { public class JettyEngineConfig : HttpClientEngineConfig() {
internal var config: (HTTP2Client) -> Unit = {} internal var config: (HTTP2Client) -> Unit = {}
/** /**
* A Jetty's [SslContextFactory]. By default, it trusts all the certificates. * Allows you to configure [SSL](https://ktor.io/docs/client-ssl.html) settings for this engine.
*/ */
public var sslContextFactory: SslContextFactory = SslContextFactory.Client() public var sslContextFactory: SslContextFactory = SslContextFactory.Client()
/** /**
* Size of the cache that keeps least recently used [JettyHttp2Engine] instances. * Specifies the size of cache that keeps recently used [JettyHttp2Engine] instances.
*/ */
public var clientCacheSize: Int = 10 public var clientCacheSize: Int = 10
/** /**
* Configure raw Jetty client. * Configures a raw Jetty client.
*/ */
public fun configureClient(block: (HTTP2Client) -> Unit) { public fun configureClient(block: (HTTP2Client) -> Unit) {
val current = config val current = config
......
ktor-client/ktor-client-okhttp/jvm/src/io/ktor/client/engine/okhttp/OkHttp.kt
Просмотр файла @ c18eb2bd
...@@ -8,8 +8,23 @@ import io.ktor.client.* ...@@ -8,8 +8,23 @@ import io.ktor.client.*
import io.ktor.client.engine.* import io.ktor.client.engine.*
/** /**
* [HttpClientEngineFactory] using a [OkHttp] based backend implementation * A JVM/Android client engine that uses the OkHttp HTTP client.
* with the associated configuration [OkHttpConfig]. * This engine supports Android 5.0 and newer.
*
* To create the client with this engine, pass it to the `HttpClient` constructor:
* ```kotlin
* val client = HttpClient(OkHttp)
* ```
* To configure the engine, pass settings exposed by [OkHttpConfig] to the `engine` method:
* ```kotlin
* val client = HttpClient(OkHttp) {
* engine {
* // this: OkHttpConfig
* }
* }
* ```
*
* You can learn more about client engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/ */
public object OkHttp : HttpClientEngineFactory<OkHttpConfig> { public object OkHttp : HttpClientEngineFactory<OkHttpConfig> {
override fun create(block: OkHttpConfig.() -> Unit): HttpClientEngine = override fun create(block: OkHttpConfig.() -> Unit): HttpClientEngine =
......
ktor-client/ktor-client-okhttp/jvm/src/io/ktor/client/engine/okhttp/OkHttpConfig.kt
Просмотр файла @ c18eb2bd
...@@ -8,7 +8,7 @@ import io.ktor.client.engine.* ...@@ -8,7 +8,7 @@ import io.ktor.client.engine.*
import okhttp3.* import okhttp3.*
/** /**
* Configuration for [OkHttp] client engine. * A configuration for the [OkHttp] client engine.
*/ */
public class OkHttpConfig : HttpClientEngineConfig() { public class OkHttpConfig : HttpClientEngineConfig() {
...@@ -20,23 +20,24 @@ public class OkHttpConfig : HttpClientEngineConfig() { ...@@ -20,23 +20,24 @@ public class OkHttpConfig : HttpClientEngineConfig() {
} }
/** /**
* Preconfigured [OkHttpClient] instance instead of configuring one. * Allows you to specify a preconfigured [OkHttpClient] instance.
*/ */
public var preconfigured: OkHttpClient? = null public var preconfigured: OkHttpClient? = null
/** /**
* Size of the cache that keeps least recently used [OkHttpClient] instances. Set "0" to avoid caching. * Specifies the size of cache that keeps recently used [OkHttpClient] instances.
* Set this property to `0` to disable caching.
*/ */
public var clientCacheSize: Int = 10 public var clientCacheSize: Int = 10
/** /**
* If provided, this [WebSocket.Factory] will be used to create [WebSocket] instances. * Specifies the [WebSocket.Factory] used to create a [WebSocket] instance.
* Otherwise, [OkHttpClient] is used directly. * Otherwise, [OkHttpClient] is used directly.
*/ */
public var webSocketFactory: WebSocket.Factory? = null public var webSocketFactory: WebSocket.Factory? = null
/** /**
* Configure [OkHttpClient] using [OkHttpClient.Builder]. * Configures [OkHttpClient] using [OkHttpClient.Builder].
*/ */
public fun config(block: OkHttpClient.Builder.() -> Unit) { public fun config(block: OkHttpClient.Builder.() -> Unit) {
val oldConfig = config val oldConfig = config
...@@ -47,7 +48,7 @@ public class OkHttpConfig : HttpClientEngineConfig() { ...@@ -47,7 +48,7 @@ public class OkHttpConfig : HttpClientEngineConfig() {
} }
/** /**
* Add [Interceptor] to [OkHttp] client. * Adds an [Interceptor] to the [OkHttp] client.
*/ */
public fun addInterceptor(interceptor: Interceptor) { public fun addInterceptor(interceptor: Interceptor) {
config { config {
...@@ -56,7 +57,7 @@ public class OkHttpConfig : HttpClientEngineConfig() { ...@@ -56,7 +57,7 @@ public class OkHttpConfig : HttpClientEngineConfig() {
} }
/** /**
* Add network [Interceptor] to [OkHttp] client. * Adds a network [Interceptor] to the [OkHttp] client.
*/ */
public fun addNetworkInterceptor(interceptor: Interceptor) { public fun addNetworkInterceptor(interceptor: Interceptor) {
config { config {
......
Поддерживает Markdown
0% или .
You are about to add 0 people to the discussion. Proceed with caution.
Сначала завершите редактирование этого сообщения!
Пожалуйста, зарегистрируйтесь или чтобы прокомментировать