Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

A little bit of work on the new Jetty 10 documentation. 

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2020-03-30 12:20:23 +02:00
parent 4d612b077f
commit 34b0726eb1
6 changed files with 40 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
jetty-documentation/pom.xml
View File

@ -125,7 +125,6 @@
<MVNCENTRAL>http://central.maven.org/maven2</MVNCENTRAL>
<VERSION>${project.version}</VERSION>
<TIMESTAMP>${maven.build.timestamp}</TIMESTAMP>
<docbits>${basedir}/src/main/java</docbits>
</attributes>
</configuration>
<executions>

3
jetty-documentation/src/main/asciidoc/embedded-guide/.asciidoctorconfig Normal file
View File

@ -0,0 +1,3 @@
// Asciidoctor IDE configuration file.
// See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-project-specific-configurations
:doc_code: ../../java

30
jetty-documentation/src/main/asciidoc/embedded-guide/client/client-concepts.adoc
View File

@ -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<String, Object>)`
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.

25
jetty-documentation/src/main/asciidoc/embedded-guide/io-arch.adoc
View File

@ -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

6
jetty-documentation/src/main/java/embedded/SelectorManagerDocSnippets.java → jetty-documentation/src/main/java/embedded/SelectorManagerDocs.java
View File

@ -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<String, Object> 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

6
jetty-documentation/src/main/java/embedded/client/ClientConnectorDocSnippets.java → jetty-documentation/src/main/java/embedded/client/ClientConnectorDocs.java
View File

@ -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<String, Object> 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();
}
}