Merge branch 'master' into write-message-lock-free

src/main/asciidoc/datagrams.adoc

@@ -26,7 +26,7 @@ and NetClient (see above).
 
 === Creating a DatagramSocket
 
-To use UDP you first need t create a {@link io.vertx.core.datagram.DatagramSocket}. It does not matter here if you only want to send data or send
+To use UDP you first need to create a {@link io.vertx.core.datagram.DatagramSocket}. It does not matter here if you only want to send data or send
 and receive.
 
 [source,$lang]
@@ -54,7 +54,7 @@ Sending packets is as easy as shown here:
 === Receiving Datagram packets
 
 If you want to receive packets you need to bind the {@link io.vertx.core.datagram.DatagramSocket} by calling
-`listen(...)}` on it.
+`listen(...)` on it.
 
 This way you will be able to receive {@link io.vertx.core.datagram.DatagramPacket}s that were sent to the address and port on
 which the {@link io.vertx.core.datagram.DatagramSocket} listens.

src/main/asciidoc/http.adoc

@@ -562,7 +562,7 @@ Or use {@link io.vertx.core.http.HttpServerResponse#putTrailer}.
 If you were writing a web server, one way to serve a file from disk would be to open it as an {@link io.vertx.core.file.AsyncFile}
 and pipe it to the HTTP response.
 
-Or you could load it it one go using {@link io.vertx.core.file.FileSystem#readFile} and write it straight to the response.
+Or you could load it in one go using {@link io.vertx.core.file.FileSystem#readFile} and write it straight to the response.
 
 Alternatively, Vert.x provides a method which allows you to serve a file from disk or the filesystem to an HTTP response
 in one operation.
@@ -580,7 +580,7 @@ Here's a very simple web server that serves files from the file system using sen
 ----
 
 Sending a file is asynchronous and may not complete until some time after the call has returned. If you want to
-be notified when the file has been written you can use {@link io.vertx.core.http.HttpServerResponse#sendFile(String)}
+be notified when the file has been written you can use {@link io.vertx.core.http.HttpServerResponse#sendFile(String)}.
 
 Please see the chapter about <<classpath, serving files from the classpath>> for restrictions about the classpath resolution or disabling it.
 
@@ -850,6 +850,26 @@ When a clients connects to an HTTP/2 server, it sends to the server its {@link i
 The settings define how the server can use the connection, the default initial settings for a client are the default
 values defined by the HTTP/2 RFC.
 
+=== Pool configuration
+
+ For performance purpose, the client uses connection pooling when interacting with HTTP/1.1 servers. The pool creates up
+ to 5 connections per server. You can override the pool configuration like this:
+
+ [source,$lang]
+ ----
+ {@link examples.HTTPExamples#examplePoolConfiguration}
+ ----
+
+ You can configure various pool {@link io.vertx.core.http.PoolOptions options} as follows
+
+- {@link io.vertx.core.http.PoolOptions options#setHttp1MaxSize} the maximum number of opened per HTTP/1.x server (5 by default)
+- {@link io.vertx.core.http.PoolOptions options#setHttp2MaxSize} the maximum number of opened per HTTP/2 server (1 by default), you *should* not change this value since a single HTTP/2 connection is capable of delivering the same performance level than multiple HTTP/1.x connections
+- {@link io.vertx.core.http.PoolOptions options#setCleanerPeriod} the period in milliseconds at which the pool checks expired connections (1 second by default)
+- {@link io.vertx.core.http.PoolOptions options#setEventLoopSize} sets the number of event loops the pool use (0 by default)
+- a value of 0 configures the pool to use the event loop of the caller
+- a positive value configures the pool load balance the creation of connection over a list of event loops determined by the value
+- {@link io.vertx.core.http.PoolOptions options#setMaxWaitQueueSize} the maximum number of HTTP requests waiting until a connection is available, when the queue is full, the request is rejected
+
 === Logging network client activity
 
 For debugging purposes, network activity can be logged.
@@ -861,6 +881,23 @@ For debugging purposes, network activity can be logged.
 
 See the chapter on <<logging_network_activity, logging network activity>> for a detailed explanation.
 
+=== Advanced HTTP client creation
+
+You can pass options {@link io.vertx.core.Vertx#createHttpClient} methods to configure the HTTP client.
+
+Alternatively you can build a client with the builder {@link io.vertx.core.http.HttpClientBuilder API} :
+
+[source,$lang]
+----
+{@link examples.HTTPExamples#exampleClientBuilder01}
+----
+
+In addition to {@link io.vertx.core.http.HttpClientOptions} and {@link io.vertx.core.http.PoolOptions}, you
+can set
+
+- a connection event handler notified when the client <<_client_connections,connects>> to a server
+- a redirection handler to implement an alternative HTTP <<_30x_redirection_handling,redirect>> behavior
+
 === Making requests
 
 The http client is very flexible and there are various ways you can make requests with it.
@@ -1020,7 +1057,7 @@ An {@link io.vertx.core.http.HttpClientRequest} instance is also a {@link io.ver
 
 You can pipe to it from any {@link io.vertx.core.streams.ReadStream} instance.
 
-For, example, you could pipe a file on disk to a http request body as follows:
+For, example, you could pipe a file on disk to an http request body as follows:
 
 [source,$lang]
 ----
@@ -1229,7 +1266,7 @@ Alternatively you can just parse the `Set-Cookie` headers yourself in the respon
 
 The client can be configured to follow HTTP redirections provided by the `Location` response header when the client receives:
 
-* a `301`, `302`, `307` or `308` status code along with a HTTP GET or HEAD method
+* a `301`, `302`, `307` or `308` status code along with an HTTP GET or HEAD method
 * a `303` status code, in addition the directed request perform an HTTP GET method
 
 Here's an example:
@@ -1413,7 +1450,7 @@ When keep alive is enabled. Vert.x will add a `Connection: Keep-Alive` header to
 When keep alive is disabled. Vert.x will add a `Connection: Close` header to each HTTP/1.1 request sent to signal
 that the connection will be closed after completion of the response.
 
-The maximum number of connections to pool *for each server* is configured using {@link io.vertx.core.http.HttpClientOptions#setMaxPoolSize(int)}
+The maximum number of connections to pool *for each server* is configured using {@link io.vertx.core.http.PoolOptions#setHttp1MaxSize(int)}
 
 When making a request with pooling enabled, Vert.x will create a new connection if there are less than the maximum number of
 connections already created for that server, otherwise it will add the request to a queue.
@@ -1449,7 +1486,7 @@ fairness of the distribution of the client requests over the connections to the
 HTTP/2 advocates to use a single connection to a server, by default the http client uses a single
 connection for each server, all the streams to the same server are multiplexed over the same connection.
 
-When the clients needs to use more than a single connection and use pooling, the {@link io.vertx.core.http.HttpClientOptions#setHttp2MaxPoolSize(int)}
+When the clients needs to use more than a single connection and use pooling, the {@link io.vertx.core.http.PoolOptions#setHttp2MaxSize(int)}
 shall be used.
 
 When it is desirable to limit the number of multiplexed streams per connection and use a connection
@@ -1507,7 +1544,7 @@ The {@link io.vertx.core.http.HttpClientRequest#connection()} method returns the
 {@link examples.HTTP2Examples#example18}
 ----
 
-A connection handler can be set on the client to be notified when a connection has been established happens:
+A connection handler can be set on a client builder to be notified when a connection has been established happens:
 
 [source,$lang]
 ----
@@ -1621,7 +1658,7 @@ NOTE: this only applies to the HTTP/2 protocol
 Connection {@link io.vertx.core.http.HttpConnection#close} closes the connection:
 
 - it closes the socket for HTTP/1.x
-- a shutdown with no delay for HTTP/2, the {@literal GOAWAY} frame will still be sent before the connection is closed. *
+- a shutdown with no delay for HTTP/2, the {@literal GOAWAY} frame will still be sent before the connection is closed.
 
 The {@link io.vertx.core.http.HttpConnection#closeHandler} notifies when a connection is closed.
 
@@ -1660,7 +1697,7 @@ You can assign a number of event loop a client will use independently of the cli
 When several HTTP servers listen on the same port, vert.x orchestrates the request handling using a
 round-robin strategy.
 
-Let's take a verticle creating a HTTP server such as:
+Let's take a verticle creating an HTTP server such as:
 
 .io.vertx.examples.http.sharing.HttpServerVerticle
 [source,$lang]
@@ -1798,18 +1835,24 @@ The {@link io.vertx.core.http.ServerWebSocket} instance enables you to retrieve
 
 ==== WebSockets on the client
 
-The Vert.x {@link io.vertx.core.http.HttpClient} supports WebSockets.
-
-You can connect a WebSocket to a server using one of the {@link io.vertx.core.http.HttpClient#webSocket} operations and
-providing a handler.
+e Vert.x {@link io.vertx.core.http.WebSocketClient} supports WebSockets.
 
-The handler will be called with an instance of {@link io.vertx.core.http.WebSocket} when the connection has been made:
+ You can connect a WebSocket to a server using one of the {@link io.vertx.core.http.WebSocketClient#connect} operations.
 
+ The returned future will be completed with an instance of {@link io.vertx.core.http.WebSocket} when the connection has been made:
 [source,$lang]
 ----
 {@link examples.HTTPExamples#example54}
 ----
 
+en connecting from a non Vert.x thread, you can create a {@link io.vertx.core.http.ClientWebSocket}, configure its handlers and
+then connect to the server:
+
+ [source,$lang]
+ ----
+ {@link examples.HTTPExamples#example54_bis}
+ ----
+
 By default, the client sets the `origin` header to the server host, e.g http://www.example.com. Some servers will refuse
 such request, you can configure the client to not set this header.
 
@@ -1839,7 +1882,7 @@ If you wish to write a single WebSocket message to the WebSocket you can do this
 ----
 
 If the WebSocket message is larger than the maximum WebSocket frame size as configured with
-{@link io.vertx.core.http.HttpClientOptions#setMaxWebSocketFrameSize(int)}
+{@link io.vertx.core.http.WebSocketClientOptions#setMaxFrameSize(int)}
 then Vert.x will split it into multiple WebSocket frames before sending it on the wire.
 
 ==== Writing frames to WebSockets
@@ -1912,7 +1955,7 @@ The addresses of the handlers are given by {@link io.vertx.core.http.WebSocket#b
 
 === Using a proxy for HTTP/HTTPS connections
 
-The http client supports accessing http/https URLs via a HTTP proxy (e.g. Squid) or _SOCKS4a_ or _SOCKS5_ proxy.
+The http client supports accessing http/https URLs via an HTTP proxy (e.g. Squid) or _SOCKS4a_ or _SOCKS5_ proxy.
 The CONNECT protocol uses HTTP/1.x but can connect to HTTP/1.x and HTTP/2 servers.
 
 Connecting to h2c (unencrypted HTTP/2 servers) is likely not supported by http proxies since they will support

src/main/asciidoc/index.adoc

@@ -903,7 +903,7 @@ may have not consumed the complete payload (the connection was cut before you we
 Vert.x uses an an address resolver for resolving host name into IP addresses instead of
 the JVM built-in blocking resolver.
 
-An host name resolves to an IP address using:
+A host name resolves to an IP address using:
 
 - the _hosts_ file of the operating system
 - otherwise DNS queries against a list of servers
@@ -944,7 +944,7 @@ Failover still applies and will use the next server in the list.
 
 === Hosts mapping
 
-The _hosts_ file of the operating system is used to perform an hostname lookup for an ipaddress.
+The _hosts_ file of the operating system is used to perform a hostname lookup for an ipaddress.
 
 An alternative _hosts_ file can be used instead:
 
@@ -968,8 +968,7 @@ on Linux, it can be configured to a specific value with {@link io.vertx.core.dns
 
 === MacOS configuration
 
-MacOS has a specific native extension to get the name server configuration of the system based on
-<a href="https://opensource.apple.com/tarballs/mDNSResponder/">Apple's open source mDNSResponder</a>. When this extension is not present,
+MacOS has a specific native extension to get the name server configuration of the system based on https://opensource.apple.com/tarballs/mDNSResponder/[Apple's open source mDNSResponder]. When this extension is not present,
 Netty logs the following warning.
 
 ----
@@ -978,7 +977,7 @@ Netty logs the following warning.
 
 This extension is not required as its absence does not prevent Vert.x to execute, yet is *recommended*.
 
-You can use add it to your classpath to improve the integration and remove the warning.
+You can add it to your classpath to improve the integration and remove the warning.
 
 .Intel-based Mac
 [source,xml]
@@ -1192,4 +1191,4 @@ directory and serves it from there. Do not use this setting in production, it ca
 
 Finally, you can disable completely the cache by using `-Dvertx.disableFileCPResolving=true`. This setting is not
 without consequences. Vert.x would be unable to read any files from the classpath (only from the file system). Be
-very careful when using this settings.
+very careful when using this setting.

src/main/asciidoc/net.adoc

@@ -347,9 +347,15 @@ TCP server (Net/Http) can be configured with traffic shaping options to enable b
 bandwidth can be limited through {@link io.vertx.core.net.TrafficShapingOptions}. For NetServer, traffic shaping options can be set
 through {@link io.vertx.core.net.NetServerOptions} and for HttpServer it can be set through {@link io.vertx.core.http.HttpServerOptions}.
 
+[source,$lang]
+----
 {@link examples.NetExamples#configureTrafficShapingForNetServer}
+----
 
+[source,$lang]
+----
 {@link examples.NetExamples#configureTrafficShapingForHttpServer}
+----
 
 [[ssl]]
 === Configuring servers and clients to work with SSL/TLS
@@ -369,7 +375,7 @@ By default it is disabled.
 
 ==== Specifying key/certificate for the server
 
-SSL/TLS servers usually provide certificates to clients in order verify their identity to clients.
+SSL/TLS servers usually provide certificates to clients in order to verify their identity to clients.
 
 Certificates/keys can be configured for servers in several ways:
 
@@ -807,7 +813,7 @@ OpenSSL to be installed on your OS depending on the tcnative implementation.
 
 === Using a proxy for client connections
 
-The {@link io.vertx.core.net.NetClient} supports either a HTTP/1.x _CONNECT_, _SOCKS4a_ or _SOCKS5_ proxy.
+The {@link io.vertx.core.net.NetClient} supports either an HTTP/1.x _CONNECT_, _SOCKS4a_ or _SOCKS5_ proxy.
 
 The proxy can be configured in the {@link io.vertx.core.net.NetClientOptions} by setting a
 {@link io.vertx.core.net.ProxyOptions} object containing proxy type, hostname, port and optionally username and password.

src/main/asciidoc/shareddata.adoc

@@ -143,6 +143,16 @@ If your application doesn't need the lock to be shared with every other node, yo
 {@link examples.SharedDataExamples#localLock}
 ----
 
+Sometimes, you use the lock API to retrieve an asynchronous result and apply the acquire/release pattern around the asynchronous call. Vert.x provides a simplified lock API to simplify this pattern.
+
+[source,$lang]
+----
+{@link examples.SharedDataExamples#withLock}
+----
+
+The lock is acquired before calling the supplier and released when the future returned by the supplier
+completes.
+
 === Asynchronous counters
 
 It's often useful to maintain an atomic counter locally or across the different nodes of your application.

src/main/asciidoc/streams.adoc

@@ -119,7 +119,7 @@ Let's now look at the methods on `ReadStream` and `WriteStream` in more detail:
 `ReadStream` is implemented by {@link io.vertx.core.http.HttpClientResponse}, {@link io.vertx.core.datagram.DatagramSocket},
 {@link io.vertx.core.http.HttpClientRequest}, {@link io.vertx.core.http.HttpServerFileUpload},
 {@link io.vertx.core.http.HttpServerRequest}, {@link io.vertx.core.eventbus.MessageConsumer},
-{@link io.vertx.core.net.NetSocket}, {@link io.vertx.core.http.WebSocket}, {@link io.vertx.core.file.AsyncFile}.
+{@link io.vertx.core.net.NetSocket}, {@link io.vertx.core.http.WebSocket} and {@link io.vertx.core.file.AsyncFile}.
 
 - {@link io.vertx.core.streams.ReadStream#handler}:
 set a handler which will receive items from the ReadStream.

src/main/generated/io/vertx/core/DeploymentOptionsConverter.java

@@ -25,6 +25,11 @@ static void fromJson(Iterable<java.util.Map.Entry<String, Object>> json, Deploym
             obj.setConfig(((JsonObject)member.getValue()).copy());
           }
           break;
+        case "worker":
+          if (member.getValue() instanceof Boolean) {
+            obj.setWorker((Boolean)member.getValue());
+          }
+          break;
         case "ha":
           if (member.getValue() instanceof Boolean) {
             obj.setHa((Boolean)member.getValue());
@@ -35,21 +40,6 @@ static void fromJson(Iterable<java.util.Map.Entry<String, Object>> json, Deploym
             obj.setInstances(((Number)member.getValue()).intValue());
           }
           break;
-        case "maxWorkerExecuteTime":
-          if (member.getValue() instanceof Number) {
-            obj.setMaxWorkerExecuteTime(((Number)member.getValue()).longValue());
-          }
-          break;
-        case "maxWorkerExecuteTimeUnit":
-          if (member.getValue() instanceof String) {
-            obj.setMaxWorkerExecuteTimeUnit(java.util.concurrent.TimeUnit.valueOf((String)member.getValue()));
-          }
-          break;
-        case "worker":
-          if (member.getValue() instanceof Boolean) {
-            obj.setWorker((Boolean)member.getValue());
-          }
-          break;
         case "workerPoolName":
           if (member.getValue() instanceof String) {
             obj.setWorkerPoolName((String)member.getValue());
@@ -60,6 +50,16 @@ static void fromJson(Iterable<java.util.Map.Entry<String, Object>> json, Deploym
             obj.setWorkerPoolSize(((Number)member.getValue()).intValue());
           }
           break;
+        case "maxWorkerExecuteTime":
+          if (member.getValue() instanceof Number) {
+            obj.setMaxWorkerExecuteTime(((Number)member.getValue()).longValue());
+          }
+          break;
+        case "maxWorkerExecuteTimeUnit":
+          if (member.getValue() instanceof String) {
+            obj.setMaxWorkerExecuteTimeUnit(java.util.concurrent.TimeUnit.valueOf((String)member.getValue()));
+          }
+          break;
       }
     }
   }
@@ -72,16 +72,16 @@ static void toJson(DeploymentOptions obj, java.util.Map<String, Object> json) {
     if (obj.getConfig() != null) {
       json.put("config", obj.getConfig());
     }
+    json.put("worker", obj.isWorker());
     json.put("ha", obj.isHa());
     json.put("instances", obj.getInstances());
-    json.put("maxWorkerExecuteTime", obj.getMaxWorkerExecuteTime());
-    if (obj.getMaxWorkerExecuteTimeUnit() != null) {
-      json.put("maxWorkerExecuteTimeUnit", obj.getMaxWorkerExecuteTimeUnit().name());
-    }
-    json.put("worker", obj.isWorker());
     if (obj.getWorkerPoolName() != null) {
       json.put("workerPoolName", obj.getWorkerPoolName());
     }
     json.put("workerPoolSize", obj.getWorkerPoolSize());
+    json.put("maxWorkerExecuteTime", obj.getMaxWorkerExecuteTime());
+    if (obj.getMaxWorkerExecuteTimeUnit() != null) {
+      json.put("maxWorkerExecuteTimeUnit", obj.getMaxWorkerExecuteTimeUnit().name());
+    }
   }
 }