From 4b9551325474a2b591ecfa52f13a1b18136927fd Mon Sep 17 00:00:00 2001 From: Lisa Jamen <31409174+ljamen@users.noreply.github.com> Date: Fri, 22 Sep 2023 09:20:45 -0400 Subject: [PATCH] DOCS: 4x overview and general intro doc updates (#7571) * updates to intro for 4x * updates to intro.adoc * updates to general overview and intro * added se includes to sse.adoc * updates for sitegen and includes * updates to sitegen icons * fix indent of telemetry * fixed curly apostrophes * removed unused links from intro * updates to achetype and doc overview * updates to benefits and intro * fixed copyright * updates to intro * updates to reactive cards --- docs/about/archetype.adoc | 6 +-- docs/about/benefits.adoc | 76 +++++++++++++++++++++++++++++++++++- docs/about/doc_overview.adoc | 34 +++++++++++----- docs/about/intro.adoc | 47 ++++++++++++++++++++-- docs/about/introduction.adoc | 25 ++++++++---- docs/mp/testing-ng.adoc | 2 + docs/mp/testing.adoc | 2 + docs/se/introduction.adoc | 12 +++--- docs/se/sse/sse.adoc | 3 ++ docs/sitegen.yaml | 8 +++- 10 files changed, 184 insertions(+), 31 deletions(-) diff --git a/docs/about/archetype.adoc b/docs/about/archetype.adoc index 36656c4f747..69c39909551 100644 --- a/docs/about/archetype.adoc +++ b/docs/about/archetype.adoc @@ -45,9 +45,9 @@ This option enables user to create Helidon project of their choice, suitable to == Generated Application Structure -User can scaffold a new Maven project based on these archetypes. See xref:cli.adoc[Helidon CLI] and our xref:../se/guides/quickstart.adoc[Helidon SE QuickStart Guide] or xref:../mp/guides/quickstart.adoc[Helidon MP QuickStart Guide] for details on usage. +You can scaffold a new Maven project based on these archetypes. See xref:cli.adoc[Helidon CLI] and our xref:../se/guides/quickstart.adoc[Helidon SE QuickStart Guide] or xref:../mp/guides/quickstart.adoc[Helidon MP QuickStart Guide] for more information. -Once the archetype is selected the other options have defaults and the project is generated in a directory named after the `artifactId` value. It mainly contains the following: +Once the archetype is selected, the other options have defaults and the project is generated in a directory named after the `artifactId` value. It mainly contains the following: - Maven structure - skeletal application code @@ -58,4 +58,4 @@ Once the archetype is selected the other options have defaults and the project i == Using Generated Application -The easiest way to get started is follow instructions in README file and familiarize with layout and features provided to build upon them esp. look at the pom.xml. You will find the suitable Helidon parent pom, enabling the use of the different dependencies managed/provided by Helidon. +The easiest way to get started is to follow the instructions in the `README` file and familiarize with layout and features provided to build upon them. In addition, look at the `pom.xml` files. You can find a suitable Helidon parent `pom` file that will enable you to use the different dependencies managed and provided by Helidon. diff --git a/docs/about/benefits.adoc b/docs/about/benefits.adoc index fc6f01488a4..05fd617f45e 100644 --- a/docs/about/benefits.adoc +++ b/docs/about/benefits.adoc @@ -16,4 +16,78 @@ /////////////////////////////////////////////////////////////////////////////// -= Features and Benefits of Helidon \ No newline at end of file += Features and Benefits of Helidon + +* <> +* <> +* <> +* <> +* <> + +== Open Source with Support + +Helidon is open-source software, licensed with Apache License, Version 2.0. Its +codebase is kept in GitHub. Its artifacts are published to Maven Central. This +makes it easy for users to inspect, modify, and contribute to its source code. The +Apache license makes it easy for organizations to adopt Helidon from a licensing +perspective. Publishing artifacts to Maven Central makes it easy and natural for +developers and operators to pull Helidon binaries into development +environments and CI/CD pipelines. In short, Helidon is intentionally aligned with +modern mainstream development practices to make it as easy as possible to +adopt and use. + +And yet, enterprise-grade support is also available for Helidon. Oracle offers +cost-competitive commercial support for Helidon, for customers serious about +support SLAs for their production operations. So, customers can get the best of +both worlds: seamless incorporation of Helidon into DevOps practices and third- +party product approvals, and award-winning customer support for high-scale +mission-critical production applications. + + + + + +== Two API Flavors for Two Programming Styles +Helidon offers two API flavors: Helidon SE, and Helidon MP. Both are fun to +program in, but each caters to a different style of programming + + +== Feature Richness +Both API flavors, Helidon SE and Helidon MP, offer a rich and similar set of +features, like configuration and metrics and security, as examples. In Helidon +MP, the APIs for the features are specified by a standards body, whereas in +Helidon SE they are not. In both cases, the +set of features available is complete enough to cover every aspect of the needs +of modern microservices applications. + +== Enterprise Features +Helidon intentionally includes many features required by industrial-strength +enterprise applications – even when they are now architected with microservices. +Among these features are support for data access, messaging, and transactions, +with integrations to existing Oracle products in each category. + +== Integrations +Helidon integrates with many other technologies that are useful in the +implementation of microservices applications, for example: + +* Oracle Coherence and Coherence Community Edition, the leading in- +memory data grid, which can serve as a distributed cache or system of +record for stateful microservices +* The Oracle Cloud Infrastructure (OCI) SDK for Java, for using a wide +variety of OCI services from within Helidon applications +* Oracle WebLogic Server (WLS), including +- Bi-directional REST service invocations +- Helidon-to-WLS SOAP web service invocations +- Helidon consumption and production of messages on WLS- +hosted JMS destinations +- Single sign-on between Helidon and WLS -hosted services +using Oracle Identity Cloud Service +- Distributed transaction coordination between Helidon and WLS +- hosted resources using Oracle MicroTx Free +* Messaging Connectors for JMS, Kafka, and Oracle AQ, to allow Helidon +applications to consume and produce messages with those providers +* HashiCorp Vault for accessing securely stored tokens, passwords, API +keys, PKI certificates, and other secrets +* Micrometer Metrics, for monitoring Helidon applications using +Micrometer +* Neo4j, for using a graph database from within Helidon applications \ No newline at end of file diff --git a/docs/about/doc_overview.adoc b/docs/about/doc_overview.adoc index 43b623a6739..1bb55abcfd4 100644 --- a/docs/about/doc_overview.adoc +++ b/docs/about/doc_overview.adoc @@ -21,7 +21,7 @@ :keywords: helidon, java, microservices, microprofile, documentation :rootdir: {docdir}/.. -Check out the xref:{rootdir}/about/doc_sitemap.adoc[Documentation Overview] for information about this site and the materials we provide. + include::{rootdir}/includes/attributes.adoc[] @@ -38,13 +38,13 @@ New to Helidon? Start here to learn how Helidon's open-source set of Java librar xref:{rootdir}/about/introduction.adoc[What is Helidon?] -xref:{rootdir}/about/benefits.adoc[Features and Benefits] +xref:{rootdir}/about/intro.adoc[What's New in Helidon 4] xref:{rootdir}/about/archetype.adoc[Helidon Archetypes] xref:{rootdir}/about/additional_info.adoc[Helidon Community and Support] -xref:{rootdir}/about/intro.adoc[What's New in Helidon 4] + -- @@ -59,8 +59,6 @@ xref:{rootdir}/about/prerequisites.adoc[Prerequisites and System Requirements] xref:{rootdir}/about/cli.adoc[Using the Helidon CLI] -xref:{rootdir}/about/generating_project.adoc[Using Project Starter] - xref:{rootdir}/mp/guides/quickstart.adoc[Using the MP Quickstart Guide] xref:{rootdir}/se/guides/quickstart.adoc[Using the SE Quick Start Guide] @@ -115,7 +113,7 @@ xref:{rootdir}/mp/guides/overview.adoc[MP Guides] //Advanced Features [CARD] .Advanced Features -[icon=swap_horiz] +[icon=hotel_class] -- -- @@ -124,17 +122,35 @@ xref:{rootdir}/mp/guides/overview.adoc[MP Guides] //Training and Certification [CARD] .Training and Certification -[icon=swap_horiz] +[icon=model_training] -- - +Learn: + https://learn.oracle.com/ols/learning-path/become-a-helidon-microservices-developer-professional/88258/114512[Become a Helidon Microservices Developer Professional] + +Certification: + https://learn.oracle.com/ols/learning-path/become-a-helidon-microservices-developer-professional/88258/114512[Helidon Microservices Developer Professional (1Z0-1113)] -- //Get Involved [CARD] .Get Involved -[icon=swap_horiz] +[icon=groups] -- +Here are some additional resources you can use to get started, get help, and to follow the evolution of Helidon. + +Project website: https://helidon.io + +Medium publication: https://medium.com/helidon + +GitHub repository: https://github.com/helidon-io/helidon + +Public Slack workspace: https://slack.helidon.io/ + +Twitter account: https://twitter.com/helidon_project + +YouTube channel: https://www.youtube.com/channel/UChg00-uTTrCMmPsuzUNaZsA +Stack Overflow tag: https://stackoverflow.com/tags/helidon -- ==== diff --git a/docs/about/intro.adoc b/docs/about/intro.adoc index 973e3f0878f..29f934cb6e9 100644 --- a/docs/about/intro.adoc +++ b/docs/about/intro.adoc @@ -18,18 +18,57 @@ = Introducing Helidon 4 :description: Helidon -:keywords: helidon, java, microservices +:keywords: helidon, java, microservices, Helidon Níma, Project Níma :rootdir: {docdir}/.. + == What's New in This Release -* We have removed the Netty-based Helidon __reactive__ WebServer and WebClient and replaced them with implementations based on virtual threads that have a _blocking_ style API. +* Introduction of the new Helidon WebServer (Project Níma): a virtual threads-based web server implementation based on https://openjdk.org/jeps/444[JDK Project Loom] virtual threads. + +* Removed Helidon's Reactive WebServer and WebClient that were based on Netty. Our new implementations are based on virtual threads that have a blocking style API (Helidon Níma). Learn more: <> + + +* Converted other _reactive_ API modules to _blocking_ style APIs. The `io.helidon.common.reactive` APIs will stay as general purpose reactive utilities and operators. Learn more: <> + +* Upgraded MicroProfile support to MicroProfile 6 and Jakarta 10 Core Profile running on the Helidon Níma WebServer. Learn more: <> + +* Java 21 is required to use Heldon 4. + + + +== Helidon 4 WebServer + +Before Helidon 4, the Helidon WebServer was built on Netty and had a reactive API. In Helidon 4 we have replaced this with a new server implementation (Project Níma) that is written from the ground up to take full advantage of Java 21's virtual threads. With virtual threads, threads are no longer a scarce resource to be carefully pooled and managed. Instead they are an abundant resource that can be created as needed to handle nearly unlimited concurrent requests. + +Because each request runs in its own dedicated thread, it is free to perform blocking operations -- like calling a database, or another service. And it can do so in a simple synchronous way with no fear of blocking a platform thread and starving other requests. You no longer need to resort to complicated asynchronous code to implement a low-overhead, highly concurrent service. + +== Helidon SE +Helidon SE is Helidon's foundational set of APIs. The big change in Helidon 4 is that the use of virtual threads have enabled these APIs to change from asynchronous to blocking. This results in much simpler code that is easier to write, maintain, debug and understand. Existing Helidon 3 SE code will require modification to run on these new APIs, but the effort is well worth the improved performance and simplicity of the resulting code. + +To give a very simple example of the differences between Helidon 3 SE and Helidon 4 SE, let's take a look at extracting a JSON body from an HTTP request and doing something with it: + +.Helidon 3 +[source,java] +---- + +request.content().as(JsonObject.class) + .thenAccept(jo -> doSomething(jo, response)); + +---- + +.Helidon 4 +[source,java] +---- + +doSomething(request.content().as(JsonObject.class), response); -NOTE: Virtual threads are lightweight threads that dramatically reduce the effort of writing, maintaining, and observing high-throughput concurrent applications. Learn more about using virtual threads https://openjdk.org/jeps/444[here]. +---- -* Helidon 4 now supports MicroProfile 5.0-based applications working on virtual threads. This is the first MicroProfile framework that supports virtual threads and uses JDK features on the new Helidon WebServer. +== Helidon MP +Helidon MP is Helidon's MicroProfile implementation and in Helidon 4 it supports MicroProfile 6 and the Jakarta EE 10 Core Profile. Your Helidon 3 MicroProfile application should migrate to Helidon 4 fairly easily (the most significant changes are in MicroProfile Metrics 5.0), and since Helidon's MicroProfile server is based on the new Helidon Níma WebServer, you get all the benefits of running on virtual threads. diff --git a/docs/about/introduction.adoc b/docs/about/introduction.adoc index 0fab74af258..a702e5d9cad 100644 --- a/docs/about/introduction.adoc +++ b/docs/about/introduction.adoc @@ -33,9 +33,9 @@ include::{rootdir}/includes/attributes.adoc[] == What is Helidon? -link:https://helidon.io[Helidon] is a collection of Java libraries for writing microservices that run on a fast web core powered by link:https://netty.io[Netty]. It's small, fast, and fun to use. +link:https://helidon.io[Helidon] is a collection of Java libraries for writing microservices. -Helidon is open source under the Apache 2.0 license. Sources are available on link:{helidon-github-tree-url}[GitHub]. +Helidon is open source under the Apache license. Sources are available on link:{helidon-github-tree-url}[GitHub]. Helidon is cloud-native ready. It provides fast start-up time and has low memory consumption and a small disk footprint. It also comes with a full observability stack out of the box including health checks, metrics, tracing and logging. @@ -55,7 +55,7 @@ Helidon comes in two flavors: *Helidon SE* and *Helidon MP*. Think about these f |Microframework model with a very small footprint and limited functionality (~7 MB). | https://projects.eclipse.org/proposals/eclipse-microprofile[MicroProfile] implementation; slightly larger footprint than SE (~13 MB). -|Functional style, reactive, non-blocking. +|Helidon SE is Helidon’s foundational set of APIs. Virtual threads have enabled these APIs to change from asynchronous to blocking. This results in much simpler code that is easier to write, maintain, debug and understand.. |Declarative style with dependency injection. |Transparent "no magic" development experience; pure java application development with no annotations and no dependency injections. @@ -95,7 +95,6 @@ public class HelloWorld { Use Helidon SE if - Performance is your main goal. -- You are familiar with reactive programming. - Your application is heavily using concurrency. - You are not planning to use any CDI-based components. - You want to use a minimum number of third-party dependencies. @@ -132,16 +131,28 @@ We also strongly suggest installing the xref:cli.adoc[Helidon CLI] (command line In case you need to upgrade the version of Helidon, follow the `Migration Guides`. -For migration from Helidon 1.x to 2.x: +For migration from Helidon 3.x to 4.x: + +* link to SE 4x migration guide [tbd] +* link to MP 4x migration guide [tbd] -* xref:{rootdir}/se/guides/migration.adoc[Helidon SE 2x Migration Guide] -* xref:{rootdir}/mp/guides/migration.adoc[Helidon MP 2x Migration Guide] For migration from Helidon 2.x to 3.x: * xref:{rootdir}/se/guides/migration_3x.adoc[Helidon SE 3x Migration Guide] * xref:{rootdir}/mp/guides/migration_3x.adoc[Helidon MP 3x Migration Guide] +For migration from Helidon 1.x to 2.x: + +* xref:{rootdir}/se/guides/migration.adoc[Helidon SE 2x Migration Guide] +* xref:{rootdir}/mp/guides/migration.adoc[Helidon MP 2x Migration Guide] + + + + + + + == Next Steps Choose a Helidon flavor to explore and start using it. Check out the following: diff --git a/docs/mp/testing-ng.adoc b/docs/mp/testing-ng.adoc index d88e3dbd74c..280d6fb98e5 100644 --- a/docs/mp/testing-ng.adoc +++ b/docs/mp/testing-ng.adoc @@ -22,6 +22,8 @@ :feature-name: Testing with TestNG :rootdir: {docdir}/.. +include::{rootdir}/includes/mp.adoc[] + == Contents - <> diff --git a/docs/mp/testing.adoc b/docs/mp/testing.adoc index c207e4aa268..5387490ec28 100644 --- a/docs/mp/testing.adoc +++ b/docs/mp/testing.adoc @@ -24,6 +24,8 @@ :feature-name: Testing with JUnit :rootdir: {docdir}/.. +include::{rootdir}/includes/mp.adoc[] + == Contents - <> diff --git a/docs/se/introduction.adoc b/docs/se/introduction.adoc index 5532714c021..03da9302b8c 100644 --- a/docs/se/introduction.adoc +++ b/docs/se/introduction.adoc @@ -24,13 +24,11 @@ include::{rootdir}/includes/se.adoc[] -Helidon SE is a compact toolkit that embraces the latest Java SE features: -reactive streams, asynchronous and functional programming, and fluent-style -APIs. +Helidon SE is Helidon's foundational set of APIs and, as of Helidon 4, it uses virtual threads to enable these APIs to change from asynchronous to blocking. == Components -The REST framework for Helidon SE is the Helidon WebServer. It is built on top of Netty and uses a straight forward request routing API. +The REST framework for Helidon SE is the Helidon WebServer. It was built from the ground up to take full advantage of Java 21's virtual threads. Helidon SE supports a number of additional Helidon features: @@ -144,12 +142,14 @@ HTTP client that handles responses to the HTTP requests in a reactive way. .WebServer [icon=settings_ethernet,link=webserver.adoc] -- -A programmatic HTTP API with reactive features, powered by Netty. +A programmatic HTTP API that uses virtual threads to handle nearly unlimited concurrent requests without blocking a platform thread or starving other requests. +// Each request runs in its own dedicated thread so it is free to perform blocking operations in a simple synchronous way without blocking a platform thread or starving other requests. + -- //WebSocket [CARD] .WebSocket -[icon=timeline,link=websocket.adoc] +[icon=sync_alt,link=websocket.adoc] -- Enables Java applications to participate in WebSocket interactions as both servers and clients. -- diff --git a/docs/se/sse/sse.adoc b/docs/se/sse/sse.adoc index fc562a8c09c..14e5dddb832 100644 --- a/docs/se/sse/sse.adoc +++ b/docs/se/sse/sse.adoc @@ -23,6 +23,9 @@ :feature-name: SSE :rootdir: {docdir}/../.. + +include::{rootdir}/includes/se.adoc[] + == Contents - <> diff --git a/docs/sitegen.yaml b/docs/sitegen.yaml index 1f5de95a8b9..6a84d5488d0 100644 --- a/docs/sitegen.yaml +++ b/docs/sitegen.yaml @@ -264,6 +264,12 @@ backend: glyph: type: "icon" value: "settings_ethernet" + - type: "PAGE" + title: "Telemetry" + source: "telemetry.adoc" + glyph: + type: "icon" + value: "analytics" - type: "MENU" title: "Testing" glyph: @@ -471,7 +477,7 @@ backend: source: "websocket.adoc" glyph: type: "icon" - value: "timeline" + value: "sync_alt" - type: "HEADER" title: "Additional resources" - type: "LINK"