This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 11.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/11.0.x by this push:
new 617eafaa12 BZ 68876 sequence diagrams for request processing and
authentication
617eafaa12 is described below
commit 617eafaa120b37c2a5418dc573376bdd5fbd187a
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Apr 29 20:18:32 2025 +0100
BZ 68876 sequence diagrams for request processing and authentication
https://bz.apache.org/bugzilla/show_bug.cgi?id=68876
---
webapps/docs/architecture/requestProcess.xml | 80 ++++++++++-----
.../architecture/requestProcess/11_nio.plantuml | 97 ++++++++++++++++++
.../docs/architecture/requestProcess/11_nio.png | Bin 0 -> 116516 bytes
.../architecture/requestProcess/21_http11.plantuml | 38 +++++++
.../docs/architecture/requestProcess/21_http11.png | Bin 0 -> 18334 bytes
.../requestProcess/31_synchronous.plantuml | 109 +++++++++++++++++++++
.../architecture/requestProcess/31_synchronous.png | Bin 0 -> 209355 bytes
.../architecture/requestProcess/41_basic.plantuml | 78 +++++++++++++++
.../docs/architecture/requestProcess/41_basic.png | Bin 0 -> 114556 bytes
.../requestProcess/authentication-process.png | Bin 42682 -> 0 bytes
.../requestProcess/request-process.png | Bin 109471 -> 0 bytes
webapps/docs/changelog.xml | 10 ++
12 files changed, 387 insertions(+), 25 deletions(-)
diff --git a/webapps/docs/architecture/requestProcess.xml
b/webapps/docs/architecture/requestProcess.xml
index 1d8adbceb3..cec2844cd4 100644
--- a/webapps/docs/architecture/requestProcess.xml
+++ b/webapps/docs/architecture/requestProcess.xml
@@ -29,46 +29,76 @@
<body>
-
-<section name="Request Process Flow">
-
+<section name="Introduction">
<p>
-This page describes the process used by Tomcat to handle
-an incoming request. This process is largely defined by
-the Servlet Specification, which outlines the order
-of events that must take place.
+This page describes how requests flow through Tomcat during processing.
Requests
+start processing in an endpoint, then get passed to the protocol and then the
+Coyote adapter which is the common entry point for all servlet request
+processing.
</p>
-
-<subsection name="description">
<p>
-TODO
+The UML diagrams do not show every detail of Tomcat's internal processing. They
+are intended to show the key elements of the processing chain.
</p>
-</subsection>
+</section>
-<subsection name="diagrams">
+<section name="Endpoint implementations">
<p>
-A UML sequence diagram of the request process is available
-<a href="requestProcess/request-process.png">here.</a>
+UML diagrams have been created for each Endpoint implementation to show how
+requests flow from the endpoint to the protocol.
</p>
<p>
-A UML sequence diagram of the authentication process is available
-<a href="requestProcess/authentication-process.png">here.</a>
+<a href="requestProcess/11_nio.png">Diagram 1.1</a> shows how requests
received via
+an NIO based endpoint are processed upto the point they reach the processor
+instance.
</p>
-
-</subsection>
-
-<subsection name="comments">
<p>
-The Servlet Specification provides many opportunities for
-listening in (using Listeners) or modifying (using Filters)
-the request handling process even before the request arrives
-at the servlet that will handle it.
+NIO2 - TBD.
</p>
+</section>
-</subsection>
+<section name="Protocols">
+<p>
+UML diagrams have been created for each protocol to show how requests flow from
+the processor instance to the CoyoteAdapter.
+</p>
+<p>
+<a href="requestProcess/21_http11.png">Diagram 2.1</a> shows how HTTP/0.9,
HTTP/1.0
+and HTTP/1.1 requests are processed.
+</p>
+<p>
+HTTP/2 - TBD.
+</p>
+<p>
+AJP - TBD.
+</p>
+</section>
+<section name="Servlet engine">
+<p>
+<a href="requestProcess/31_synchronous.png">Diagram 3.1</a> shows synchronous
+Servlet requests are processed.
+</p>
+<p>
+Asynchronous - TBD.
+</p>
</section>
+<section name="Authentication">
+<p>
+<a href="requestProcess/41_basic.png">Diagram 4.1</a> shows how BASIC
+authentication is processed.
+</p>
+<p>
+DIGEST - TBD.
+</p>
+<p>
+FORM - TBD.
+</p>
+<p>
+Jakarta Authentication (JASPIC) - TBD.
+</p>
+</section>
</body>
</document>
diff --git a/webapps/docs/architecture/requestProcess/11_nio.plantuml
b/webapps/docs/architecture/requestProcess/11_nio.plantuml
new file mode 100644
index 0000000000..171171aef7
--- /dev/null
+++ b/webapps/docs/architecture/requestProcess/11_nio.plantuml
@@ -0,0 +1,97 @@
+@startuml
+
+' Licensed to the Apache Software Foundation (ASF) under one or more
+' contributor license agreements. See the NOTICE file distributed with
+' this work for additional information regarding copyright ownership.
+' The ASF licenses this file to You 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.
+
+hide footbox
+skinparam style strictuml
+
+activate Acceptor
+participant NioEndpoint
+participant ServerSocket
+participant SocketChannel
+activate Poller
+participant Selector
+participant Executor
+activate Worker
+
+group Acceptor Loop
+Acceptor -> NioEndpoint ++: serverSocketAccept()
+NioEndpoint -> ServerSocket ++: accept()
+note right of ServerSocket
+ This is where Tomcat
+ waits for incoming
+ connections
+end note
+ServerSocket -->> SocketChannel **:
+return
+return
+
+Acceptor -> NioEndpoint ++: setSocketOptions()
+NioEndpoint -> Poller ++: register()
+return
+return
+end
+
+group Poller Loop (simplified)
+Poller -> Poller ++: events()
+Poller -> SocketChannel ++: register(OP_READ)
+return
+return
+
+Poller -> Selector ++: select()
+return
+
+Poller -> Poller ++: processKey()
+Poller -> NioEndpoint ++: processSocket()
+NioEndpoint -> NioEndpoint ++: createSocketProcessor()
+NioEndpoint -->> SocketProcessor **:
+NioEndpoint -> Executor ++: execute()
+Executor -> Worker ++: run()
+return
+return
+return
+return
+return
+end
+
+Worker -> SocketProcessor ++: run()
+SocketProcessor -> SocketChannel ++: handshake()
+note right of SocketChannel
+ TLS handshake
+end note
+return
+SocketProcessor -> ConnectionHandler ++: process()
+ConnectionHandler -> Protocol ++: createProcessor()
+Protocol -->> Processor **:
+activate Processor
+Processor -->> CoyoteRequest **:
+Processor -->> CoyoteResponse **:
+return
+return
+ConnectionHandler -> Processor ++: process()
+Processor -> Processor ++: service()
+note right of Processor
+ More detail of this
+ processing in the
+ protocol specific
+ diagrams
+end note
+return
+return
+return
+return
+
+@enduml
\ No newline at end of file
diff --git a/webapps/docs/architecture/requestProcess/11_nio.png
b/webapps/docs/architecture/requestProcess/11_nio.png
new file mode 100644
index 0000000000..058941858c
Binary files /dev/null and
b/webapps/docs/architecture/requestProcess/11_nio.png differ
diff --git a/webapps/docs/architecture/requestProcess/21_http11.plantuml
b/webapps/docs/architecture/requestProcess/21_http11.plantuml
new file mode 100644
index 0000000000..4060b80084
--- /dev/null
+++ b/webapps/docs/architecture/requestProcess/21_http11.plantuml
@@ -0,0 +1,38 @@
+@startuml
+
+' Licensed to the Apache Software Foundation (ASF) under one or more
+' contributor license agreements. See the NOTICE file distributed with
+' this work for additional information regarding copyright ownership.
+' The ASF licenses this file to You 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.
+
+hide footbox
+skinparam style strictuml
+
+activate Processor
+
+Processor -> InputBuffer ++: parseRequestLine()
+return
+Processor -> Processor ++: prepareRequestProtocol()
+return
+Processor -> InputBuffer ++: parseHeaders()
+return
+Processor -> Processor ++: prepareRequest()
+return
+Processor -> CoyoteAdapter ++: service()
+note right of CoyoteAdapter
+ Servlet request processing
+ happens here
+end note
+return
+
+@enduml
\ No newline at end of file
diff --git a/webapps/docs/architecture/requestProcess/21_http11.png
b/webapps/docs/architecture/requestProcess/21_http11.png
new file mode 100644
index 0000000000..dd59be2b2b
Binary files /dev/null and
b/webapps/docs/architecture/requestProcess/21_http11.png differ
diff --git a/webapps/docs/architecture/requestProcess/31_synchronous.plantuml
b/webapps/docs/architecture/requestProcess/31_synchronous.plantuml
new file mode 100644
index 0000000000..645fd328f8
--- /dev/null
+++ b/webapps/docs/architecture/requestProcess/31_synchronous.plantuml
@@ -0,0 +1,109 @@
+@startuml
+
+' Licensed to the Apache Software Foundation (ASF) under one or more
+' contributor license agreements. See the NOTICE file distributed with
+' this work for additional information regarding copyright ownership.
+' The ASF licenses this file to You 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.
+
+hide footbox
+skinparam style strictuml
+
+participant CoyoteRequest
+participant CoyoteResponse
+activate CoyoteAdapter
+
+CoyoteAdapter -> Connector ++: createRequest()
+return
+
+CoyoteAdapter -> Connector ++: createResponse()
+return
+
+CoyoteAdapter -> Request ++: setRequest()
+return
+CoyoteAdapter -> Response ++: setResponse()
+return
+CoyoteAdapter -> CoyoteRequest ++: setNote()
+return
+CoyoteAdapter -> CoyoteResponse ++: setNote()
+return
+
+CoyoteAdapter -> CoyoteAdapter ++: postParseRequest()
+return
+
+CoyoteAdapter -> Connector ++: getService()
+return
+CoyoteAdapter -> Service ++: getContainer()
+return
+CoyoteAdapter -> Engine ++: getPipeline()
+return
+CoyoteAdapter -> "StandardPipeline\n(Engine)" ++: getFirst()
+return
+CoyoteAdapter -> StandardEngineValve ++: invoke()
+StandardEngineValve -> Request ++: getHost()
+return
+StandardEngineValve -> Host ++: getPipeline()
+return
+StandardEngineValve -> "StandardPipeline\n(Host)" ++: getFirst()
+return
+StandardEngineValve -> AccessLogValve ++: invoke()
+AccessLogValve -> AccessLogValve ++: getNext()
+return
+AccessLogValve -> ErrorReportValve ++: invoke()
+ErrorReportValve -> ErrorReportValve ++: getNext()
+return
+ErrorReportValve -> StandardHostValve ++: invoke()
+StandardHostValve -> Request ++: getContext()
+return
+StandardHostValve -> Context ++: bind()
+return
+StandardHostValve -> Context ++: getPipeline()
+return
+StandardHostValve -> "StandardPipeline\n(Context)" ++: getFirst()
+return
+StandardHostValve -> StandardContextValve ++: invoke()
+StandardContextValve -> Request ++: getWrapper()
+return
+StandardContextValve -> Wrapper ++: getPipeline()
+return
+StandardContextValve -> "StandardPipeline\n(Wrapper)" ++: getFirst()
+return
+StandardContextValve -> StandardWrapperValve ++: invoke()
+StandardWrapperValve -> Wrapper ++: allocate()
+return
+StandardWrapperValve -> ApplicationFilterFactory ++: createFilterChain
+ApplicationFilterFactory --> FilterChain **:
+return
+StandardWrapperValve -> FilterChain ++: doFilter()
+FilterChain -> "Filter\nA" ++: doFilter()
+"Filter\nA" -> FilterChain ++: doFilter()
+FilterChain -> "Filter\nB" ++: doFilter()
+"Filter\nB" -> FilterChain ++: doFilter()
+FilterChain -> Servlet ++: service()
+|||
+return
+return
+return
+return
+return
+return
+StandardWrapperValve -> FilterChain ++: release()
+return
+StandardWrapperValve -> Wrapper ++: deallocate()
+return
+return
+return
+return
+return
+return
+return
+@enduml
\ No newline at end of file
diff --git a/webapps/docs/architecture/requestProcess/31_synchronous.png
b/webapps/docs/architecture/requestProcess/31_synchronous.png
new file mode 100644
index 0000000000..c91fc5024d
Binary files /dev/null and
b/webapps/docs/architecture/requestProcess/31_synchronous.png differ
diff --git a/webapps/docs/architecture/requestProcess/41_basic.plantuml
b/webapps/docs/architecture/requestProcess/41_basic.plantuml
new file mode 100644
index 0000000000..fd779110ac
--- /dev/null
+++ b/webapps/docs/architecture/requestProcess/41_basic.plantuml
@@ -0,0 +1,78 @@
+@startuml
+
+' Licensed to the Apache Software Foundation (ASF) under one or more
+' contributor license agreements. See the NOTICE file distributed with
+' this work for additional information regarding copyright ownership.
+' The ASF licenses this file to You 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.
+
+hide footbox
+skinparam style strictuml
+
+participant MimeHeaders
+participant CoyoteRequest
+participant Request
+activate ErrorReportValve
+
+ErrorReportValve -> StandardHostValve ++: invoke()
+StandardHostValve -> Request ++: getContext()
+return
+StandardHostValve -> Context ++: bind()
+return
+StandardHostValve -> Context ++: getPipeline()
+return
+StandardHostValve -> "StandardPipeline\n(Context)" ++: getFirst()
+return
+StandardHostValve -> BasicAuthenticator ++: invoke()
+BasicAuthenticator -> Context ++: getRealm()
+return
+BasicAuthenticator -> LockoutRealm ++: findSecurityContraints()
+return
+BasicAuthenticator -> LockoutRealm ++: hasUserDataPermission()
+return
+BasicAuthenticator -> BasicAuthenticator ++: doAuthenticate()
+BasicAuthenticator -> Request ++: getCoyoteRequest()
+return
+BasicAuthenticator -> CoyoteRequest ++: getMimeHeaders()
+return
+BasicAuthenticator -> MimeHeaders ++: getValue("authorization")
+return
+BasicAuthenticator --> BasicCredentials **:
+BasicAuthenticator -> BasicCredentials ++: getUserName()
+return
+BasicAuthenticator -> BasicCredentials ++: getPassword()
+return
+BasicAuthenticator -> Context ++: getRealm()
+return
+BasicAuthenticator -> LockoutRealm ++: authenticate()
+LockoutRealm -> UserDatabaseRealm ++: authenticate()
+UserDatabaseRealm -> UserDatabaseRealm ++: getPassword(username)
+UserDatabaseRealm -> CredentialHandler ++: matches()
+return
+UserDatabaseRealm -> UserDatabaseRealm ++: getPrincipal()
+return
+return
+return
+return
+return
+BasicAuthenticator -> Realm ++: hasResourcePermission()
+return
+BasicAuthenticator -> BasicAuthenticator ++: getNext()
+return
+BasicAuthenticator -> StandardContextValve ++: invoke()
+note right of StandardContextValve
+ Standard Servlet request
+ processing continues from
+ this point
+end note
+
+@enduml
\ No newline at end of file
diff --git a/webapps/docs/architecture/requestProcess/41_basic.png
b/webapps/docs/architecture/requestProcess/41_basic.png
new file mode 100644
index 0000000000..ea6bbe70b0
Binary files /dev/null and
b/webapps/docs/architecture/requestProcess/41_basic.png differ
diff --git
a/webapps/docs/architecture/requestProcess/authentication-process.png
b/webapps/docs/architecture/requestProcess/authentication-process.png
deleted file mode 100644
index e23c33359c..0000000000
Binary files
a/webapps/docs/architecture/requestProcess/authentication-process.png and
/dev/null differ
diff --git a/webapps/docs/architecture/requestProcess/request-process.png
b/webapps/docs/architecture/requestProcess/request-process.png
deleted file mode 100644
index 33ae3c3766..0000000000
Binary files a/webapps/docs/architecture/requestProcess/request-process.png and
/dev/null differ
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index ff7a4a2feb..8923d04f36 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -152,6 +152,16 @@
</add>
</changelog>
</subsection>
+ <subsection name="Web applications">
+ <changelog>
+
+ <fix>
+ <bug>68876</bug>: Documentation. Update the UML diagrams for server
+ start-up, request processing and authentication using PlantUML and
+ include the source files for each diagram. (markt)
+ </fix>
+ </changelog>
+ </subsection>
<subsection name="Other">
<changelog>
<update>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
