From 34b0726eb1993aaa1712d2b44be0f8d56940bf76 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Mon, 30 Mar 2020 12:20:23 +0200 Subject: [PATCH] A little bit of work on the new Jetty 10 documentation. Signed-off-by: Simone Bordet --- jetty-documentation/pom.xml | 1 - .../embedded-guide/.asciidoctorconfig | 3 ++ .../client/client-concepts.adoc | 30 +++++++++---------- .../main/asciidoc/embedded-guide/io-arch.adoc | 25 +++++++++------- ...Snippets.java => SelectorManagerDocs.java} | 6 ++-- ...Snippets.java => ClientConnectorDocs.java} | 6 ++-- 6 files changed, 40 insertions(+), 31 deletions(-) create mode 100644 jetty-documentation/src/main/asciidoc/embedded-guide/.asciidoctorconfig rename jetty-documentation/src/main/java/embedded/{SelectorManagerDocSnippets.java => SelectorManagerDocs.java} (98%) rename jetty-documentation/src/main/java/embedded/client/{ClientConnectorDocSnippets.java => ClientConnectorDocs.java} (97%) diff --git a/jetty-documentation/pom.xml b/jetty-documentation/pom.xml index 460b4b34f93..4661ac8c479 100644 --- a/jetty-documentation/pom.xml +++ b/jetty-documentation/pom.xml @@ -125,7 +125,6 @@ http://central.maven.org/maven2 ${project.version} ${maven.build.timestamp} - ${basedir}/src/main/java diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/.asciidoctorconfig b/jetty-documentation/src/main/asciidoc/embedded-guide/.asciidoctorconfig new file mode 100644 index 00000000000..b1785c722ed --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/embedded-guide/.asciidoctorconfig @@ -0,0 +1,3 @@ +// Asciidoctor IDE configuration file. +// See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-project-specific-configurations +:doc_code: ../../java diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/client/client-concepts.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/client/client-concepts.adoc index bf7dae893b1..bf63bce5013 100644 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/client/client-concepts.adoc +++ b/jetty-documentation/src/main/asciidoc/embedded-guide/client/client-concepts.adoc @@ -31,9 +31,9 @@ There are conceptually three layers that compose the Jetty client libraries, fro more abstract to more concrete: . The API layer, that exposes semantic APIs to applications so that they can write -code such as "GET me the resource at this URI" +code such as "GET me the resource at this URI". . The protocol layer, where the API request is converted into the appropriate -protocol bytes, for example encrypted HTTP/2 +protocol bytes, for example encrypted HTTP/2. . The infrastructure layer, that handles the low level I/O and deals with network, buffer, threads, etc. @@ -50,26 +50,31 @@ link:{JDURL}/org/eclipse/jetty/io/ClientConnector.html[`ClientConnector`]. The `ClientConnector` primarily wraps the link:{JDURL}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`] -and aggregates other four components: the thread pool (in form of an `Executor`), -the `Scheduler`, the `ByteBufferPool` and the `SslContextFactory.Client`. +and aggregates other four components: + +* a thread pool (in form of an `java.util.concurrent.Executor`) +* a scheduler (in form of `org.eclipse.jetty.util.thread.Scheduler`) +* a byte buffer pool (in form of `org.eclipse.jetty.io.ByteBufferPool`) +* a TLS factory (in form of `org.eclipse.jetty.util.ssl.SslContextFactory.Client`) The `ClientConnector` is where you want to set those components after you have configured them. If you don't explicitly set those components on the `ClientConnector`, then appropriate defaults will be chosen when the `ClientConnector` starts. -The simplest example that creates and starts a `ClientConnector`: +The simplest example that creates and starts a `ClientConnector` is the +following: [source,java,indent=0] ---- -include::{docbits}/embedded/client/ClientConnectorDocSnippets.java[tags=simplest] +include::../{doc_code}/embedded/client/ClientConnectorDocs.java[tags=simplest] ---- A more typical example: [source,java,indent=0] ---- -include::{docbits}/embedded/client/ClientConnectorDocSnippets.java[tags=typical] +include::../{doc_code}/embedded/client/ClientConnectorDocs.java[tags=typical] ---- A more advanced example that customizes the `ClientConnector` by overriding @@ -77,12 +82,11 @@ factory methods: [source,java,indent=0] ---- -include::{docbits}/embedded/client/ClientConnectorDocSnippets.java[tags=advanced] +include::../{doc_code}/embedded/client/ClientConnectorDocs.java[tags=advanced] ---- Since `ClientConnector` is the component that handles the low-level network, it -is also the component where you want to configure the parameters that control -how it should handle the low-level network. +is also the component where you want to configure the low-leven network configuration. The most common parameters are: @@ -122,9 +126,6 @@ Once the `ClientConnector` is configured and started, it can be used to connect to the server via `ClientConnector.connect(SocketAddress, Map)` which in turn will call `SocketChannel.connect(SocketAddress)`. - -// TODO: from down here, moved to io-arch.adoc - When establishing a TCP connection to a server, applications need to tell `ClientConnector` how to create the `Connection` for that particular TCP connection. @@ -134,10 +135,9 @@ that must be passed in the context `Map` as follows: [source,java,indent=0] ---- -include::{docbits}/embedded/client/ClientConnectorDocSnippets.java[tags=connect] +include::../{doc_code}/embedded/client/ClientConnectorDocs.java[tags=connect] ---- - TODO: expand on what is the API to use, what parameters the context Map must have, and basically how we can write a generic network client with it. diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/io-arch.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/io-arch.adoc index e0106e8059b..e083aa1d6ee 100644 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/io-arch.adoc +++ b/jetty-documentation/src/main/asciidoc/embedded-guide/io-arch.adoc @@ -40,26 +40,26 @@ NOTE: TODO: add image to a server and by a network server when accepting connections from network clients. In both cases the `SocketChannel` instance is passed to `SelectorManager` -(and to `ManagedSelector` and eventually to `java.nio.channels.Selector`) -to be registered for use within Jetty. +(which passes it to `ManagedSelector` and eventually to +`java.nio.channels.Selector`) to be registered for use within Jetty. -It is therefore possible for an application to create the `SocketChannel` +It is possible for an application to create the `SocketChannel` instances outside Jetty, even perform some initial network traffic also outside Jetty (for example for authentication purposes), and then pass the `SocketChannel` instance to `SelectorManager` for use within Jetty. -This example shows how to connect to a server: +This example shows how a client can connect to a server: [source,java,indent=0] ---- -include::{docbits}/embedded/SelectorManagerDocSnippets.java[tags=connect] +include::{doc_code}/embedded/SelectorManagerDocs.java[tags=connect] ---- -This example shows how to accept a client connection: +This example shows how a server accepts a client connection: [source,java,indent=0] ---- -include::{docbits}/embedded/SelectorManagerDocSnippets.java[tags=accept] +include::{doc_code}/embedded/SelectorManagerDocs.java[tags=accept] ---- [[io-arch-endpoint-connection]] @@ -193,7 +193,7 @@ extends `AbstractConnection`: [source,java,indent=0] ---- -include::{docbits}/embedded/SelectorManagerDocSnippets.java[tags=connection] +include::{doc_code}/embedded/SelectorManagerDocs.java[tags=connection] ---- [[io-arch-echo]] @@ -207,7 +207,7 @@ A naive, but wrong, implementation may be the following: [source,java,indent=0] ---- -include::{docbits}/embedded/SelectorManagerDocSnippets.java[tags=echo-wrong] +include::{doc_code}/embedded/SelectorManagerDocs.java[tags=echo-wrong] ---- WARNING: The implementation above is wrong and leads to `StackOverflowError`. @@ -231,11 +231,16 @@ which leads to `StackOverflowError`. This is a typical side effect of asynchronous programming using non-blocking APIs, and happens in the Jetty I/O library as well. +NOTE: The callback is invoked synchronously for efficiency reasons. +Submitting the invocation of the callback to an `Executor` to be invoked in +a different thread would cause a context switch and make simple writes +extremely inefficient. + A correct implementation is the following: [source,java,indent=0] ---- -include::{docbits}/embedded/SelectorManagerDocSnippets.java[tags=echo-correct] +include::{doc_code}/embedded/SelectorManagerDocs.java[tags=echo-correct] ---- The correct implementation performs consecutive reads in a loop (rather than diff --git a/jetty-documentation/src/main/java/embedded/SelectorManagerDocSnippets.java b/jetty-documentation/src/main/java/embedded/SelectorManagerDocs.java similarity index 98% rename from jetty-documentation/src/main/java/embedded/SelectorManagerDocSnippets.java rename to jetty-documentation/src/main/java/embedded/SelectorManagerDocs.java index 3844c4f9dab..8350b6c120b 100644 --- a/jetty-documentation/src/main/java/embedded/SelectorManagerDocSnippets.java +++ b/jetty-documentation/src/main/java/embedded/SelectorManagerDocs.java @@ -34,7 +34,7 @@ import org.eclipse.jetty.io.SelectorManager; import org.eclipse.jetty.util.BufferUtil; import org.eclipse.jetty.util.Callback; -public class SelectorManagerDocSnippets +public class SelectorManagerDocs { // tag::connect[] public void connect(SelectorManager selectorManager, Map context) throws IOException @@ -101,9 +101,9 @@ public class SelectorManagerDocSnippets // tag::echo-wrong[] class WrongEchoConnection extends AbstractConnection implements Callback { - public WrongEchoConnection(EndPoint endp, Executor executor) + public WrongEchoConnection(EndPoint endPoint, Executor executor) { - super(endp, executor); + super(endPoint, executor); } @Override diff --git a/jetty-documentation/src/main/java/embedded/client/ClientConnectorDocSnippets.java b/jetty-documentation/src/main/java/embedded/client/ClientConnectorDocs.java similarity index 97% rename from jetty-documentation/src/main/java/embedded/client/ClientConnectorDocSnippets.java rename to jetty-documentation/src/main/java/embedded/client/ClientConnectorDocs.java index 41f92da336f..840bb63a0b2 100644 --- a/jetty-documentation/src/main/java/embedded/client/ClientConnectorDocSnippets.java +++ b/jetty-documentation/src/main/java/embedded/client/ClientConnectorDocs.java @@ -36,7 +36,7 @@ import org.eclipse.jetty.util.thread.Scheduler; import static java.lang.System.Logger.Level.INFO; -public class ClientConnectorDocSnippets +public class ClientConnectorDocs { public void simplest() throws Exception { @@ -107,6 +107,7 @@ public class ClientConnectorDocSnippets public void connect() throws Exception { + // tag::connect[] class CustomHTTPConnection extends AbstractConnection { public CustomHTTPConnection(EndPoint endPoint, Executor executor) @@ -141,10 +142,11 @@ public class ClientConnectorDocSnippets Map context = new HashMap<>(); context.put(ClientConnector.CLIENT_CONNECTION_FACTORY_CONTEXT_KEY, connectionFactory); clientConnector.connect(address, context); + // end::connect[] } public static void main(String[] args) throws Exception { - new ClientConnectorDocSnippets().connect(); + new ClientConnectorDocs().connect(); } }