FISH-651 FISH-667 FISH-868 FISH-1372 MicroProfile 4.1

docs/antora.yml

@@ -10,19 +10,19 @@ asciidoc:
     glassfishVersion: '5'
     payaraWebDtd: 'https://raw.githubusercontent.com/payara/Payara-Enterprise-Documentation/master/docs/modules/ROOT/pages/schemas/payara-web-app_4.dtd'
     payaraResourcesDtd: 'https://raw.githubusercontent.com/payara/Payara-Enterprise-Documentation/master/docs/modules/ROOT/pages/schemas/payara-resources_1_6.dtd'
-    mpConfigVersion: '1.4'
-    mpConfigSpecUrl: 'https://github.com/eclipse/microprofile-config/releases/tag/1.4'
-    mpMetricsVersion: '2.3'
-    mpMetricsSpecUrl: 'https://github.com/eclipse/microprofile-metrics/releases/tag/2.3'
-    mpHealthVersion: '2.2'
-    mpHealthSpecUrl: 'https://github.com/eclipse/microprofile-health/releases/tag/2.2'
-    mpFaultToleranceVersion: '2.1'
-    mpFaultToleranceSpecUrl: 'https://github.com/eclipse/microprofile-fault-tolerance/releases/tag/2.1'
-    mpJwtVersion: '1.1.1'
-    mpJwtSpecUrl: 'https://github.com/eclipse/microprofile-jwt-auth/releases/tag/1.1.1'
-    mpOpenTracingVersion: '1.3'
-    mpOpenTracingSpecUrl: 'https://github.com/eclipse/microprofile-opentracing/releases/tag/1.3'
-    mpOpenAPIVersion: '1.1'
-    mpOpenAPISpecUrl: 'https://github.com/eclipse/microprofile-open-api/releases/tag/1.1'
-    mpRestClientVersion: '1.4'
-    mpRestClientSpecUrl: 'https://github.com/eclipse/microprofile-rest-client/releases/tag/1.4.1'
+    mpConfigVersion: '2.0'
+    mpConfigSpecUrl: 'https://github.com/eclipse/microprofile-config/releases/tag/2.0'
+    mpMetricsVersion: '3.0'
+    mpMetricsSpecUrl: 'https://github.com/eclipse/microprofile-metrics/releases/tag/3.0'
+    mpHealthVersion: '3.1'
+    mpHealthSpecUrl: 'https://github.com/eclipse/microprofile-health/releases/tag/3.1'
+    mpFaultToleranceVersion: '3.0'
+    mpFaultToleranceSpecUrl: 'https://github.com/eclipse/microprofile-fault-tolerance/releases/tag/3.0'
+    mpJwtVersion: '1.2.1'
+    mpJwtSpecUrl: 'https://github.com/eclipse/microprofile-jwt-auth/releases/tag/1.2.1'
+    mpOpenTracingVersion: '2.0'
+    mpOpenTracingSpecUrl: 'https://github.com/eclipse/microprofile-opentracing/releases/tag/2.0'
+    mpOpenAPIVersion: '2.0'
+    mpOpenAPISpecUrl: 'https://github.com/eclipse/microprofile-open-api/releases/tag/2.0'
+    mpRestClientVersion: '2.0'
+    mpRestClientSpecUrl: 'https://github.com/eclipse/microprofile-rest-client/releases/tag/2.0'

docs/modules/ROOT/pages/documentation/microprofile/README.adoc

@@ -11,6 +11,14 @@ Payara has been part of the MicroProfile project from its inception and, therefo
 
 == Payara Support for MicroProfile
 
+Version 4.1::
+Version 4.1 of MicroProfile is a minor release that updates Health Check.
+This is supported by both Payara Server and Payara Micro from release *5.29.0*
+
+Version 4.0::
+Version 4.0 of MicroProfile is a major release that updates Config, Fault Tolerance, Health Check, JWT-Auth, Metrics, OpenAPI, OpenTracing and Rest Client. It is also the first version of MicroProfile to be based on Jakarta EE 8. All of the Java EE dependencies are replaced with Jakarta EE dependencies for all MicroProfile specifications.
+This is supported by both Payara Server and Payara Micro from release *5.29.0*.
+
 Version 3.3::
 Version 3.3 of MicroProfile updates Config, Health Check, Fault Tolerance, Metrics, and Rest Client.
 This is supported by both Payara Server and Payara Micro from release *5.20.0*.
@@ -64,11 +72,67 @@ supported by Payara Server and Payara Micro, an application targeting version
 |Specifications
 |Maven
 
+| 4.1
+|
+* https://jakarta.ee/specifications/restful-ws/2.1/restful-ws-spec-2.1.html[Jakarta JAX-RS 2.1]
+* https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html[Jakarta CDI 2.0]
+* https://jakarta.ee/specifications/annotations/1.3/annotations-spec-1.3.html[Jakarta Annotations 1.3]
+* https://jakarta.ee/specifications/jsonb/1.0/jsonb-spec-1.0.html[Jakarta JSON-B 1.0]
+* https://jakarta.ee/specifications/jsonp/1.1/jsonp-spec-1.1.html[Jakarta JSON-P 1.1]
+* https://github.com/eclipse/microprofile-config/releases/tag/2.0[Config 2.0]
+* https://github.com/eclipse/microprofile-metrics/releases/tag/3.0[Metrics 3.0]
+* https://github.com/eclipse/microprofile-health/releases/tag/3.1[Health Check 3.1]
+* https://github.com/eclipse/microprofile-fault-tolerance/releases/tag/3.0[Fault Tolerance 3.0]
+* https://github.com/eclipse/microprofile-jwt-auth/releases/tag/1.2.1[JWT Authentication 1.2.1]
+* https://github.com/eclipse/microprofile-opentracing/releases/tag/2.0[OpenTracing 2.0]
+* https://github.com/eclipse/microprofile-open-api/releases/tag/2.0[OpenAPI 2.0]
+* https://github.com/eclipse/microprofile-rest-client/releases/tag/2.0[Rest Client 2.0]
+
+| [source, xml]
+----
+<dependency>
+    <groupId>org.eclipse.microprofile</groupId>
+    <artifactId>microprofile</artifactId>
+    <version>4.1</version>
+    <type>pom</type>
+    <scope>provided</scope>
+</dependency>
+----
+
+| 4.0
+|
+* https://jakarta.ee/specifications/restful-ws/2.1/restful-ws-spec-2.1.html[Jakarta JAX-RS 2.1]
+* https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html[Jakarta CDI 2.0]
+* https://jakarta.ee/specifications/annotations/1.3/annotations-spec-1.3.html[Jakarta Annotations 1.3]
+* https://jakarta.ee/specifications/jsonb/1.0/jsonb-spec-1.0.html[Jakarta JSON-B 1.0]
+* https://jakarta.ee/specifications/jsonp/1.1/jsonp-spec-1.1.html[Jakarta JSON-P 1.1] 
+* https://github.com/eclipse/microprofile-config/releases/tag/2.0[Config 2.0]
+* https://github.com/eclipse/microprofile-metrics/releases/tag/3.0[Metrics 3.0]
+* https://github.com/eclipse/microprofile-health/releases/tag/3.0[Health Check 3.0]
+* https://github.com/eclipse/microprofile-fault-tolerance/releases/tag/3.0[Fault Tolerance 3.0]
+* https://github.com/eclipse/microprofile-jwt-auth/releases/tag/1.2[JWT Authentication 1.2]
+* https://github.com/eclipse/microprofile-opentracing/releases/tag/2.0[OpenTracing 2.0]
+* https://github.com/eclipse/microprofile-open-api/releases/tag/2.0[OpenAPI 2.0]
+* https://github.com/eclipse/microprofile-rest-client/releases/tag/2.0[Rest Client 2.0]
+
+| [source, xml]
+----
+<dependency>
+    <groupId>org.eclipse.microprofile</groupId>
+    <artifactId>microprofile</artifactId>
+    <version>4.0.1</version>
+    <type>pom</type>
+    <scope>provided</scope>
+</dependency>
+----
+
+*Due to a known issue with Microprofile 4.0 release, 4.0.1 release should be used instead.*
+
+
 | 3.3
 |
 * JAX-RS 2.1
 * CDI 2.0
-* JSON-P 1.1
 * Common Annotations 1.3
 * JSON-B 1.0
 * JSON-P 1.1
@@ -96,7 +160,6 @@ supported by Payara Server and Payara Micro, an application targeting version
 |
 * JAX-RS 2.1
 * CDI 2.0
-* JSON-P 1.1
 * Common Annotations 1.3
 * JSON-B 1.0
 * JSON-P 1.1
@@ -124,7 +187,6 @@ supported by Payara Server and Payara Micro, an application targeting version
 |
 * JAX-RS 2.1
 * CDI 2.0
-* JSON-P 1.1
 * Common Annotations 1.3
 * JSON-B 1.0
 * JSON-P 1.1
@@ -152,7 +214,6 @@ supported by Payara Server and Payara Micro, an application targeting version
 |
 * JAX-RS 2.1
 * CDI 2.0
-* JSON-P 1.1
 * Common Annotations 1.3
 * JSON-B 1.0
 * JSON-P 1.1
@@ -180,9 +241,9 @@ supported by Payara Server and Payara Micro, an application targeting version
 |
 * JAX-RS 2.1
 * CDI 2.0
-* JSON-P 1.1
 * Common Annotations 1.3
 * JSON-B 1.0
+* JSON-P 1.1
 * https://github.com/eclipse/microprofile-config/releases/tag/1.3[Config 1.3]
 * https://github.com/eclipse/microprofile-metrics/releases/tag/1.1[Metrics 1.1]
 * https://github.com/eclipse/microprofile-health/releases/tag/1.0[Health Check 1.0]
@@ -207,9 +268,9 @@ supported by Payara Server and Payara Micro, an application targeting version
 |
 * JAX-RS 2.1
 * CDI 2.0
-* JSON-P 1.1
 * Common Annotations 1.3
 * JSON-B 1.0
+* JSON-P 1.1
 * https://github.com/eclipse/microprofile-config/releases/tag/1.3[Config 1.3]
 * https://github.com/eclipse/microprofile-metrics/releases/tag/1.1[Metrics 1.1]
 * https://github.com/eclipse/microprofile-health/releases/tag/1.0[Health Check 1.0]
@@ -234,9 +295,9 @@ supported by Payara Server and Payara Micro, an application targeting version
 |
 * JAX-RS 2.1
 * CDI 2.0
-* JSON-P 1.1
 * Common Annotations 1.3
 * JSON-B 1.0
+* JSON-P 1.1
 * https://github.com/eclipse/microprofile-config/releases/tag/1.3[Config 1.3]
 * https://github.com/eclipse/microprofile-metrics/releases/tag/1.1[Metrics 1.1]
 * https://github.com/eclipse/microprofile-health/releases/tag/1.0[Health Check 1.0]

docs/modules/ROOT/pages/documentation/microprofile/config/README.adoc

@@ -647,3 +647,78 @@ asadmin> set-config-cache
     --duration=30
     --target=myAppCluster
 ----
+
+[[microprofile-4-upgrade]]
+== Upgrading from MicroProfile 3.x to 4.x
+
+MicroProfile 4.0 brings with it a number of changes to MicroProfile Config. There are three incompatible changes
+with the previous version of MicroProfile Config, though one is only important when writing your own _ConfigSources_.
+
+=== ConfigSource#getPropertyNames No Longer Default
+The `ConfigSource#getPropertyNames` method is no longer a default method. If you've written your own _ConfigSources_,
+you will need to implement this method yourself. While dependant on the nature of your ConfigSource, this can
+frequently be achieved by simply returning the `keySet` of the collection returned by the `getProperties` method
+of the _ConfigSource_ implementation.
+
+==== Example
+
+[source,Java]
+----
+@Override
+public Set<String> getPropertyNames() {
+    return getProperties().keySet();
+}
+----
+
+=== Evaluation of Property Expressions
+Previous versions of the specification would not evaluate _Property Expressions_ (a config property referencing
+another config property). As such, previous working configuration may behave differently if any MicroProfile Config
+properties contain values with
+https://download.eclipse.org/microprofile/microprofile-config-2.0/microprofile-config-spec-2.0.html#property-expressions[_Property Expressions_]
+syntax.
+
+==== Example
+
+The following microprofile-config.properties file will now evaluate the `server.url` property to
+`http://example.org:8080/foo`, whereas before it would just evaluate to
+`http://${server.host:example.org}:${server.port}/${server.endpoint}`.
+
+```
+server.url=http://${server.host:example.org}:${server.port}/${server.endpoint}
+server.port=8080
+server.endpoint=${server.endpoint.path.${server.endpoint.path.bar}}
+server.endpoint.path.foo=foo
+server.endpoint.path.bar=foo
+```
+
+NOTE: This can also affect the behaviour of MicroProfile Config variable references within a
+`payara-expression-config.properties` file.
+
+==== Disabling MicroProfile Config Property Expansion
+
+The following system property can be defined to make the Payara Platform revert to the previous behaviour of not
+evaluating the embedded expressions: `mp.config.property.expressions.enabled`
+
+This can be set in the same manner as other system properties on a config, with the potential for instance-by-instance
+overrides.
+
+===== Using Asadmin Commands
+
+Disable on a specific config.
+[source,Shell]
+----
+asadmin> create-system-properties --target=my-config "mp.config.property.expressions.enabled=false"
+----
+
+Disable on a specific instance.
+[source,Shell]
+----
+asadmin> create-system-properties --target=my-instance "mp.config.property.expressions.enabled=false"
+----
+
+=== Empty Values and Special Characters No Longer Valid
+Empty value or other special characters (e.g. a standalone ",") are no longer a valid config value return type. Empty
+values will now cause a `NoSuchElementException` to be thrown.
+
+There unfortunately isn't a workaround to this: you must simply ensure that your config properties do not return an
+empty value or a special character.