From 7115936f722cfdfe9ffa82d630f913e511bb48f5 Mon Sep 17 00:00:00 2001 From: Joe Di Pol Date: Fri, 20 Oct 2023 14:56:14 -0700 Subject: [PATCH] Docs updates: fix github links, microprofile version, SE upgrade guide --- docs/includes/attributes.adoc | 4 +- .../security/providers/http-basic-auth.adoc | 2 +- .../security/providers/http-signatures.adoc | 2 +- .../security/providers/provider-template.adoc | 2 +- docs/mp/graphql.adoc | 4 +- docs/se/guides/upgrade_4x.adoc | 105 ++++++++++++++++-- docs/se/observability.adoc | 2 +- 7 files changed, 102 insertions(+), 19 deletions(-) diff --git a/docs/includes/attributes.adoc b/docs/includes/attributes.adoc index 5b4814ada90..90caab69d2c 100644 --- a/docs/includes/attributes.adoc +++ b/docs/includes/attributes.adoc @@ -27,7 +27,7 @@ ifndef::attributes-included[] :helidon-version-is-release: false ifeval::["{helidon-version-is-release}" != "true"] -:helidon-github-tree-url: https://github.com/oracle/helidon/tree/master +:helidon-github-tree-url: https://github.com/oracle/helidon/tree/main endif::[] ifeval::["{helidon-version-is-release}" == "true"] @@ -37,7 +37,7 @@ endif::[] // versions :version-plugin-helidon: 3.0.5 -:version-lib-microprofile-api: 5.0 +:version-lib-microprofile-api: 6.0 // microprofile specifications :version-lib-microprofile-lra-api: 2.0 diff --git a/docs/includes/security/providers/http-basic-auth.adoc b/docs/includes/security/providers/http-basic-auth.adoc index 5816c60f96f..7c14afb8d96 100644 --- a/docs/includes/security/providers/http-basic-auth.adoc +++ b/docs/includes/security/providers/http-basic-auth.adoc @@ -42,7 +42,7 @@ include::{rootdir}/config/io_helidon_security_providers_httpauth_HttpBasicAuthPr ==== Example code -See the link:{helidon-github-tree-url}/master/examples/security/outbound-override[example] on GitHub. +See the link:{helidon-github-tree-url}/examples/security/outbound-override[example] on GitHub. [source,yaml] .Configuration example diff --git a/docs/includes/security/providers/http-signatures.adoc b/docs/includes/security/providers/http-signatures.adoc index 414092347e2..2912c829ad3 100644 --- a/docs/includes/security/providers/http-signatures.adoc +++ b/docs/includes/security/providers/http-signatures.adoc @@ -43,7 +43,7 @@ include::{rootdir}/config/io_helidon_security_providers_httpsign_HttpSignProvide ==== Example code -See the link:{helidon-github-tree-url}/master/examples/security/webserver-signatures[example] on GitHub. +See the link:{helidon-github-tree-url}/examples/security/webserver-signatures[example] on GitHub. [source,yaml] .Configuration example diff --git a/docs/includes/security/providers/provider-template.adoc b/docs/includes/security/providers/provider-template.adoc index 840c500a569..88236fcfe92 100644 --- a/docs/includes/security/providers/provider-template.adoc +++ b/docs/includes/security/providers/provider-template.adoc @@ -48,7 +48,7 @@ provider-config-key ---- ==== Example code -See the link:{helidon-github-tree-url}/master/examples/security/[example] on GitHub. +See the link:{helidon-github-tree-url}/examples/security/[example] on GitHub. [source,yaml] .Configuration example diff --git a/docs/mp/graphql.adoc b/docs/mp/graphql.adoc index 4c97223a0d4..b30f22e11af 100644 --- a/docs/mp/graphql.adoc +++ b/docs/mp/graphql.adoc @@ -169,7 +169,7 @@ additional information on how to change the location of these resources. If you wish to use the link:https://github.com/graphql/graphiql[GraphQL UI] then please see the -link:{helidon-github-tree-url}/master/examples/microprofile/graphql[GraphQL MP Example]. +link:{helidon-github-tree-url}/examples/microprofile/graphql[GraphQL MP Example]. == Configuration @@ -191,7 +191,7 @@ include::{rootdir}/includes/graphql.adoc[] == Examples For a complete example, see -link:{helidon-github-tree-url}/master/examples/microprofile/graphql[GraphQL MP Example]. +link:{helidon-github-tree-url}/examples/microprofile/graphql[GraphQL MP Example]. == Additional Information diff --git a/docs/se/guides/upgrade_4x.adoc b/docs/se/guides/upgrade_4x.adoc index 1d05108525b..650b1982d8f 100644 --- a/docs/se/guides/upgrade_4x.adoc +++ b/docs/se/guides/upgrade_4x.adoc @@ -21,6 +21,8 @@ :keywords: helidon, porting, migration, upgrade, incompatibilities :rootdir: {docdir}/../.. +include::{rootdir}/includes/attributes.adoc[] + In Helidon 4.x we have made some major changes to Helidon. Reactive engine has been removed. APIS and implementations are rewritten in "blocking" paradigm. This guide will help you upgrade a Helidon MP 3.x application to 4.x. @@ -28,7 +30,7 @@ In Helidon 4.x we have made some major changes to Helidon. Reactive engine has b Java 17 is no longer supported in Helidon 4. Java 21 or newer is required. Please follow the instructions in xref:{rootdir}/about/prerequisites.adoc[Prerequisites] for proper installation. -Helidon 4 no more uses Netty. Helidon SE is now running on Helidon WebServer which is based on Virtual threads technology, available in Java 21. +Helidon 4 no longer uses Netty. Helidon SE is now running on Helidon WebServer which is based on virtual threads technology, available in Java 21. == Programming paradigm @@ -37,7 +39,7 @@ Helidon SE has changed from an asynchronous style API to an imperative/blocking == Server Initialization and Start Up -In Helidon 1.x-3.x to star a server, the following actions should be done: +In Helidon 1.x-3.x you started a server like this: [source, java] .Start Helidon SE 3.x Server @@ -71,7 +73,7 @@ static Single startServer() { Since Helidon SE in 3.x was reactive, during the start a `Single` object is returned, the server has been started in asynchronous way. We have to use reactive methods like `thenAccept` to wait for the server to start and then to perform the desired action. The exception handling should also be done in reactive way using the corresponding method. -In Helidon 4.x there are no more Reactive APIs, so the Server startup is much simpler: +In Helidon 4.x asynchronous programming is no longer required so the server startup is much simpler: [source, java] .Start Helidon SE 4.x Server @@ -96,6 +98,19 @@ public static void main(String[] args) { 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 Features and Media Support Discovery + +In previous versions of Helidon you had to explicitly register WebServer features (`register(MetricsSupport.create())`) and +explicitly add media support (`addMediaSupport(JsonpSupport.create())`). In Helidon 4 the default behavior is +to automatically discover these components from the classpath. So all you need to do is add the +dependencies to your pom.xml and optionally add configuration to customize them. + +If you want full control using the API, you still have that option. + +For more information see: + +* xref:../observability.adoc[Observability feature support] +* xref:../webserver.adoc#_media_types_support[Media types support] == Routing Configuration @@ -133,16 +148,15 @@ In Helidon 4, the routing is configured the following way: .Start Helidon SE 4.x Server ---- static void routing(HttpRouting.Builder routing) { - Config config = Config.global(); - - routing.register("/greet", new GreetService()) <1> - .addFeature(OpenApiFeature.create(config.get("openapi"))) <2> - .addFeature(ObserveFeature.create(config.get("observe"))); + routing.register("/greet", new GreetService()); <1> } ---- <1> Register Greeting service as in previous versions of Helidon. -<2> Add `Feature` for Observability and OpenAPI. +As described previously, the Metrics and Health features will be discovered automatically as long as you have +added the dependencies for them to your project. + +If you wanteded to add these features to the server programatically you would do so using `WebServer.builder().addFeature()` method. `Feature` encapsulates a set of endpoints, services and/or filters. It is similar to `HttpService` but gives more freedom in setup. Main difference is that a feature can add `Filters` and it cannot be registered on a path. Features are not registered immediately—each feature can define a `Weight` or implement `Weighted` to order features according to their weight. Higher-weighted features are registered first. This is to allow ordering of features in a meaningful way (e.g. Context should be first, Tracing second, Security third etc.). @@ -204,11 +218,41 @@ public class GreetService implements HttpService { <1> Helidon 4 introduced `HttpService` that should be implemented in order to process HTTP requests. To set up routing, the method `routing(HttpRules rules)` should now be used. It receives `HttpRules` object with routes description. +`ServerRequest` and `ServerResponse` are now in the `io.helidon.webserver.http` package; + +`Http.Status` is now `io.helidon.http.Status` + WARNING: These changes make Helidon 4 incompatible with previous versions. Learn more about `HttpService` and `Routing` at xref:../webserver.adoc[Helidon SE WebServer] -=== Significant Changes +=== Other Significant Changes + +==== Media Support + +Media support has moved from the `io.helidon.media` Java package to `io.helidon.http.media` and has new dependency coordinates. For example: + +[source, xml] +---- + + io.helidon.http.media + helidon-http-media-jsonp + +---- + +In Helidon 4 media support is discovered by default, so you simple need to add the dependency. +You no longer need to explicitly add media support using the `WebServer` builder. + +Media support no long transitively brings the Jakarta API dependencies. So you might need to add these explicitly. For example: + +[source, xml] +---- + + jakarta.json + jakarta.json-api + +---- + ==== Testing @@ -253,6 +297,19 @@ For System Metrics, please use: ---- +By default Observability features are discovered automatically if you add the above dependencies. +If you choose to add them programmatically (using `addFeature`) you will need to add the following dependency: + +[source, xml] +---- + + io.helidon.webserver.observe + helidon-webserver-observe + +---- + +Metrics has changed significantly in Helidon 4. See xref:../metrics/metrics.adoc[Helidon SE Metrics] for more information. + ==== Security * Changed modules: @@ -272,7 +329,14 @@ For System Metrics, please use: The global configuration represents a single instance of the `Config` class, which is implicitly employed by certain Helidon components. Furthermore, it offers a handy approach for your application to access configuration information from any part of your code. -You can utilize the global configuration for easy retrieval of your application's configuration: +It is recommended that you explicitly initialize global configuration before using any Helidon components: + +``` +Config config = Config.create(); // Uses default config sources +Config.global(config); +``` + +You can then utilize the global configuration for easy retrieval of your application's configuration: ``` Config config = Config.global(); @@ -280,7 +344,26 @@ Config config = Config.global(); More information at xref:../config/introduction.adoc[Helidon SE Config]. +=== Logging + +The class `LogConfig` has moved to the `io.helidon.logging.common` Java package. + +The Helidon console handler has changed from `io.helidon.common.HelidonConsoleHandler` to `io.helidon.logging.jul.HelidonConsoleHandler`. + +If you use this handler in your `logging.properties` you will need to update it and add the following dependency: + +[source, xml] +---- + + io.helidon.logging + helidon-logging-jul + runtime + +---- == Conclusion Please proceed to xref:../introduction.adoc[Helidon SE Introduction] to find more information and documentation about each module. + +Also, the +link:{helidon-github-tree-url}/examples/[Helidon examples] are a good resource for seeing how things are done in Helidon 4. diff --git a/docs/se/observability.adoc b/docs/se/observability.adoc index 66deebf96aa..cd23112cff2 100644 --- a/docs/se/observability.adoc +++ b/docs/se/observability.adoc @@ -16,7 +16,7 @@ /////////////////////////////////////////////////////////////////////////////// -= Tracing += Observability :description: Helidon SE Observability :feature-name: Helidon Observability :keywords: helidon, observability