Merge pull request #7618 from OpenLiberty/staging

Staging to vNext 24.0.0.10 docs

modules/ROOT/nav.adoc

@@ -35,6 +35,7 @@
   ** xref:microprofile-config-properties.adoc[MicroProfile Config properties]
   ** https://openliberty.io/guides/#configuration[Guides: Configuration]
 * xref:cdi-beans.adoc[Context and Dependency Injection]
+  ** xref:cdi-extension-user-feature.adoc[Creating a CDI extension inside a user feature]
   ** xref:jaxrs-integration-cdi.adoc[RESTful Web Services integration with CDI]
   ** https://openliberty.io/guides/cdi-intro.html[Guide: Injecting dependencies into microservices]
 * xref:data-persistence.adoc[Data persistence]

modules/ROOT/pages/cdi-extension-user-feature.adoc

@@ -0,0 +1,67 @@
+// Copyright (c) 2024 IBM Corporation and others.
+// Licensed under Creative Commons Attribution-NoDerivatives
+// 4.0 International (CC BY-ND 4.0)
+//   https://creativecommons.org/licenses/by-nd/4.0/
+//
+// Contributors:
+//     IBM Corporation
+//
+:page-description:
+:seo-title: Creating a CDI Extension inside a User Feature
+:seo-description:
+:page-layout: general-reference
+:page-type: general
+= Creating a CDI extension inside an Open Liberty user feature
+
+Contexts and Dependency Injection (CDI) provides powerful extensions to augment, extend, or override the behavior of CDI. To enable CDI to find the extensions inside an Open Liberty user feature, you must implement an Open Liberty-specific SPI: `io.openliberty.cdi.spi.CDIExtensionMetadata`.
+
+The link:https://openliberty.io/docs/latest/reference/javadoc/spi/cdi-1.2.html?path=24.0.0.8/com.ibm.websphere.appserver.spi.cdi_1.1-javadoc/io/openliberty/cdi/spi/package-summary.html[CDIExtensionMetadata] class also provides shortcuts for the two most common uses of a CDI Extension: registering a class as a CDI bean, and registering an annotation as a bean defining annotation (BDA).
+
+The `CDIExtensionMetadata` class includes three possible methods to extend the class:
+
+
+getBeanClasses::
+The `CDIBean` class becomes a CDI bean that can be injected with `@Inject CDIBean cdiBean`. If it does not have a scope, the scope defaults to `@Dependent`.
+
+getBeanDefiningAnnotationClasses::
+The `CDIAnnotation` class becomes a bean defining annotation. Any class that is annotated with `@CDIAnnotation` can be injected through CDI. Unless `CDIAnnotation` defines otherwise, the default scope is `@Dependent`. For more information about how annotations define their scope, see link:https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#scopes[Scopes in CDI 4.0].
+
+getExtensions::
+The `CDIExtension` class is processed as a full CDI extension.
+
+
+The following example shows an implementation of the `CDIExtensionMetadata` class. Each of the three methods has a default implementation that returns an empty set, so you can implement only the ones that are relevant to your needs.
+
+[source,java]
+----
+package com.ibm.example.cdi;
+
+import static org.osgi.service.component.annotations.ConfigurationPolicy.IGNORE;
+
+import java.util.Set;
+import jakarta.enterprise.inject.spi.Extension;
+
+import io.openliberty.cdi.spi.CDIExtensionMetadata;
+import org.osgi.service.component.annotations.Component;
+
+@Component(service = CDIExtensionMetadata.class, configurationPolicy = IGNORE)
+public class CDIIntegrationMetaData implements CDIExtensionMetadata
+{
+    public Set<Class<?>> getBeanClasses() {
+        return Set.of(CDIBean.class);
+    }
+
+    public Set<Class<? extends Annotation>> getBeanDefiningAnnotationClasses() {
+        return Set.of(CDIAnnotation.class);
+    }
+
+    public Set<Class<? extends Extension>> getExtensions() {
+        return Set.of(CDIExtension.class);
+    }
+
+}
+----
+
+The `@Component` annotation is required so that Open Liberty processes your implementation of the `CDIExtensionMetadata` class.
+
+This configuration is all that you need to make your user extension extend CDI. For a step-by-step guide to creating a user feature that extends CDI, see the link:https://openliberty.io/blog/2024/06/28/liberty-user-feature-tutorial.html[How to package a library as an Open Liberty user feature] blog post.

modules/ROOT/pages/java-se.adoc

@@ -72,12 +72,12 @@ The following table lists the Java SE versions that Open Liberty supports and pr
 |https://adoptium.net/temurin/releases/?version=21[Eclipse Temurin 21]
 |https://docs.oracle.com/en/java/javase/21/migrate/toc.htm[Java SE 21 migration guide]
 
-|22
+|23
 |No
-|Because Java 22 is not an LTS release, Open Liberty supports it only until Java 23 is released.
-|link:https://developer.ibm.com/languages/java/semeru-runtimes/downloads/?version=22[IBM Semeru 22]
-|https://adoptium.net/temurin/releases/?version=22[Eclipse Temurin 22]
-|https://docs.oracle.com/en/java/javase/22/migrate/getting-started.html[Java SE 22 migration guide]
+|Because Java 23 is not an LTS release, Open Liberty supports it only until the next Java version is released.
+|link:https://developer.ibm.com/languages/java/semeru-runtimes/downloads/?version=23[IBM Semeru 23]
+|https://adoptium.net/temurin/releases/?version=23[Eclipse Temurin 23]
+|https://docs.oracle.com/en/java/javase/23/migrate/getting-started.html[Java SE 23 migration guide]
 |===
 
 

modules/ROOT/pages/telemetry-trace.adoc

@@ -15,38 +15,16 @@
 After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code. You can instrument your code automatically, manually, or by using the Java agent.
 
 * <<#auto, Automatic instrumentation>>, which automatically traces your JAX-RS or RESTful web services.
-* <<#manual, Manual instrumentation>>, which allows you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services.
+* <<#manual, Manual instrumentation>>, which enables you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services.
 * <<#agent, Agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>.
 
 [#auto]
 == Automatic instrumentation
 
-With automatic instrumentation, you can observe traces without modifying the source code in your applications. All you need to do is configure runtime as described in xref:microprofile-telemetry.adoc#traces[Configuring Open Liberty to use MicroProfile Telemetry to collect traces]. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications.
+With automatic instrumentation, you can observe traces without modifying the source code in your applications. All that you need to do is configure runtime as described in xref:microprofile-telemetry.adoc#traces[Configuring Open Liberty to use MicroProfile Telemetry to collect traces]. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications.
 
 In Open Liberty version 23.0.0.11 and later, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs.
 
-////
-To start emitting traces with automatic instrumentation, enable the MicroProfile Telemetry feature in your `server.xml` file by adding `<feature>mpTelemetry-1.0</feature>` or `<feature>mpTelemetry-1.1</feature>` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service requires.
-
-For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file.
-
-[source,properties]
-----
-otel.sdk.disabled=false
-otel.traces.exporter=otlp
-otel.exporter.otlp.endpoint=http://localhost:4317/
-----
-
-To export traces to a Zipkin server, you can use the following properties instead:
-
-[source,properties]
-----
-otel.sdk.disabled=false
-otel.traces.exporter=zipkin
-otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans
-----
-////
-
 [#manual]
 == Manual instrumentation
 
@@ -56,7 +34,7 @@ However, before you manually instrument your code, you must enable MicroProfile
 
 After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API.
 
-- Add extra information, such as the user ID, to the current span. Any information that you add to a span is visible when you look at traces on your trace server.
+- Add extra information, such as the user ID, to the current span. Any information that you add to a span is visible when you look at the traces on your trace server.
 +
 [source,java]
 ----
@@ -72,6 +50,27 @@ public String myMethod() {
 }
 ----
 
+- Annotate methods in any Jakarta CDI beans by using the `@WithSpan` annotation. This annotation creates a span and establishes any required relationships with the current trace context. You can annotate method parameters with the `@SpanAttribute` annotation to indicate which method parameters are part of the trace, as shown in the following example.
++
+[source,java]
+----
+@ApplicationScoped
+class SpanBean {
+
+    @WithSpan("name")
+    void spanName() {
+       ...
+    }
+
+    @WithSpan
+    void spanArgs(@SpanAttribute(value = "arg") String arg) {
+       ...
+    }
+}
+----
++
+However, you cannot create a child span with the `@WithSpan` annotation by calling an internal method in the same class as the parent span. Instead, you can manually create a subspan in the child method, as shown in the next example.
+
 - Create a subspan around a particular operation, such as querying a database. This subspan shows you how long it took and the order in which it occurred relative to other spans.
 +
 [source,java]
@@ -91,35 +90,20 @@ public String myMethod() {
 }
 ----
 
-- Annotate methods in any Jakarta CDI beans by using the `@WithSpan` annotation. This annotation creates a new Span and establishes any required relationships with the current trace context. You can annotate method parameters with the `@SpanAttribute` annotation to indicate which method parameters are part of the trace, as shown in the following example.
-+
-[source,java]
-----
-@ApplicationScoped
-class SpanBean {
-
-    @WithSpan("name")
-    void spanName() {
-       ...
-    }
+This example creates a span that is named `QueryDatabase` that can be used to track the execution time and other attributes of the `queryDatabase()` method.
 
-    @WithSpan
-    void spanArgs(@SpanAttribute(value = "arg") String arg) {
-       ...
-    }
-}
-----
+// Assisted by WCA@IBM
+// Latest GenAI contribution: ibm/granite-8b-code-instruct
 
 === Considerations for manual instrumentation
 
 The following important considerations apply to manual instrumentation.
 
-- You must call the `.end()` method on any span you create, otherwise the span is not recorded.
-- The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the  `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan.
-- Because Liberty supports per-application configuration, it does not support `GlobalOpenTelemetry`. Using that class does not produce any telemetry data.
-- If you set any properties by using environment variables, including those in the `server.env` file, the keys must be in uppercase and all punctuation must be replaced by an underscore. Values must be written normally.
+- Call the `.end()` method on any span that you create, otherwise the span is not recorded.
+- The current span is used as the parent for any new spans that are created. Therefore, when you create a span, in most cases you also want to make it current. However, you must close the `Scope` instance that is returned by the `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan.
+- If you set any properties by using environment variables, including those in the `server.env` file, specify the keys in uppercase and replace all punctuation with an underscore. Write values normally.
 
-For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry.
+For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own.
 
 [#agent]
 == Agent instrumentation

modules/reference/nav.adoc

@@ -12,7 +12,8 @@ include::reference:partial$config-nav.adoc[]
 
 include::reference:partial$feature-nav.adoc[]
 
-* xref:feature/versionless-features.adoc[Versionless features]
+include::reference:partial$platform-nav.adoc[]
+
 * xref:command/command-overview.adoc[Commands]
   ** xref:command/auditUtility-auditReader.adoc[auditUtility auditReader]
   ** xref:command/featureUtility-commands.adoc[featureUtility commands]

modules/reference/pages/feature/restConnector/examples.adoc

@@ -1,8 +1,14 @@
 == Examples
 
 === Configure REST API management roles
-When the REST connector feature is enabled, you can configure management roles for your Open Liberty server to grant users and groups that are defined in a user registry access to select administrative REST APIs. You can use any supported user registry. The administrator role provides read and write access to administrative REST APIs. The reader role provides read-only access to administrative REST APIs. Users who are in the reader role can monitor the server but do not have permission to modify it in any way. 
-The following example maps users  and groups that are defined in a basic user registry to reader and administrator roles.
+When the REST connector feature is enabled, you can configure management roles for your Open Liberty server. These roles grant users and groups that are defined in a user registry access to select administrative REST APIs. You can use any supported user registry.
+
+- Administrator role: Grants users read and write access to administrative REST APIs, including the ability to modify their configuration or settings.
+
+- Reader role: Grants users the same permissions to monitor the server as in the administrator role, but without the ability to modify any configuration or settings. The reader role provides access to REST APIs that are considered read-only. Users in this role can monitor the server, but cannot modify it in any way.
+
+The following example maps users and groups that are defined in a basic user registry to the reader and administrator roles.
+
 
 [source,xml]
 ----

modules/reference/pages/feature/versionless-features.adoc

@@ -108,11 +108,20 @@ However, this strategy does not work if you declare a feature version that is pa
 
 == Available platforms and versionless features
 
-The following tables list the currently available MicroProfile, Jakarta EE, and Java EE platform versions and their corresponding versionless features. You can declare up to 2 platform elements, one for MicroProfile and another for either Jakarta EE or Java EE.
+The currently available MicroProfile, Jakarta EE, and Java EE platform versions and their corresponding versionless features are documented on the following pages:
+
+- xref:reference:platform/MicroProfile.adoc[MicroProfile platforms]
+- xref:reference:platform/JavaEE.adoc[Java EE platforms]
+- xref:reference:platform/JakartaEE.adoc[Jakarta EE platforms]
+
+
+You can declare up to 2 platform elements, one for MicroProfile and another for either Jakarta EE or Java EE.
 
 Only features that are included in the supported platforms are available in versionless format.
 For example, because the `springBoot-3.0` feature is not specifically included in the MicroProfile, Jakarta EE, or JavaEE platforms, no `springBoot` versionless feature is available.
 
+////
+removing in 240010 for automated tables
 
 [#mp]
 === MicroProfile
@@ -463,3 +472,5 @@ Declare a platform version by using any of the three strategies that are describ
 |`wasJmsSecurity`
 
 |===
+
+////