4.x: Document ServerLifecycle beforeStart and afterStop (#9629)

* Document ServerLifecycle beforeStart and afterStop. See 7956
* Mention server lifecycle in webserver SE docs. Fix toc.

docs/src/main/asciidoc/se/guides/upgrade_4x.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+    Copyright (c) 2023, 2025 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -72,6 +72,25 @@ include::{sourcedir}/se/guides/Upgrade4xSnippets.java[tag=snippet_2, indent=0]
 
 Just create it, configure it, and wait for it to start. If any exceptions happen, they are handled the traditional way using available language constructions.
 
+== Server Lifecycle
+
+In Helidon 3.x you provided code to run after WebServer startup and after WebServer shutdown using asynchronous constructs:
+
+[source,java]
+.Helidon 3.x server lifecycle
+----
+include::{sourcedir}/se/guides/Upgrade4xSnippets.java[tag=snippet_9, indent=0]
+----
+
+In Helidon 4 your `HttpService` can interpose on the server lifecycle by overriding the `beforeStart` and `afterStop` methods:
+[source,java]
+.Helidon 4.x server lifecycle
+----
+include::{sourcedir}/se/guides/Upgrade4xSnippets.java[tag=snippet_10, indent=0]
+----
+
+No special API is needed for after server starup since the server starts sycnhronously as described in the previous section.
+
 == Server Features and Media Support Discovery
 
 In previous versions of Helidon you had to explicitly register WebServer features (`register(MetricsSupport.create())`) and

docs/src/main/asciidoc/se/webserver.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2018, 2024 Oracle and/or its affiliates.
+    Copyright (c) 2018, 2025 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -34,9 +34,9 @@ include::{rootdir}/includes/se.adoc[]
 ** <<Configuring the WebServer in a Configuration File, Configuring the WebServer in a Configuration File>>
 ** <<Configuring TLS, Configuring TLS>>
 ** <<Configuration Options, Configuration Options>>
-*** <<Routing, Routing>>
-*** <<Request Handling, Request Handling>>
-*** <<Error Handling, Error Handling>>
+- <<Routing, Routing>>
+** <<Request Handling, Request Handling>>
+** <<Error Handling, Error Handling>>
 - <<Server Features, Server Features>>
 ** <<Access Log, Access Log>>
 ** <<Context, Context>>
@@ -291,6 +291,16 @@ include::{sourcedir}/se/WebServerSnippets.java[tag=snippet_7, indent=0]
 In this example, the `GET` handler matches requests to `/hello/subpath`.
 
 [[anchor-http-feature]]
+
+=== Server Lifecycle
+
+In Helidon 4 your `HttpService` can interpose on the server lifecycle by overriding the `beforeStart` and `afterStop` methods:
+[source,java]
+.Helidon 4.x server lifecycle
+----
+include::{sourcedir}/se/guides/Upgrade4xSnippets.java[tag=snippet_10, indent=0]
+----
+
 === Using `HttpFeature`
 
 By implementing the `io.helidon.webserver.http.HttpFeature` interface, you can organize multiple routes and/or filters into

docs/src/main/java/io/helidon/docs/se/guides/Upgrade4xSnippets.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2024, 2025 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -170,4 +170,46 @@ void snippet_8() {
         Config config = Config.global();
         // end::snippet_8[]
     }
+
+    /* Helidon 3 code
+    static Single<WebServer> startServer() {
+        Config config = Config.create();
+
+        WebServer server = WebServer.builder(createRouting(config))
+                .config(config.get("server"))
+                .addMediaSupport(JsonpSupport.create())
+                .build();
+
+        // tag::snippet_9[]
+        Single<WebServer> webserver = server.start();
+
+        webserver.thenAccept(ws -> {
+                    System.out.println("WEB server is up! http://localhost:" + ws.port() + "/greet");
+                    ws.whenShutdown().thenRun(() -> System.out.println("Helidon WebServer has stopped"));
+                })
+                .exceptionallyAccept(t -> {
+                    System.err.println("Startup failed: " + t.getMessage());
+                    t.printStackTrace(System.err);
+                });
+        // end::snippet_9[]
+        return webserver;
+    }
+     */
+
+    // tag::snippet_10[]
+    static class MyService implements HttpService {
+        @Override
+        public void beforeStart() {
+            System.out.println("MyService: Helidon WebServer is starting!");
+        }
+
+        @Override
+        public void afterStop() {
+            System.out.println("MyService: Helidon WebServer has stopped.");
+        }
+        // end::snippet_10[]
+        @Override
+        public void routing(HttpRules rules) {
+        }
+    }
 }