From 0f1840ab08b06bf360f57b6796437435de6bf98d Mon Sep 17 00:00:00 2001 From: Foivos Zakkak Date: Fri, 17 May 2024 19:57:19 +0300 Subject: [PATCH] Improve documentation about `@RegisterForReflection` Make clear that it will register nested classes as well. --- docs/src/main/asciidoc/amqp.adoc | 7 ++++--- docs/src/main/asciidoc/cache.adoc | 1 + docs/src/main/asciidoc/mongodb.adoc | 2 +- docs/src/main/asciidoc/qute-reference.adoc | 2 +- docs/src/main/asciidoc/rabbitmq.adoc | 7 ++++--- .../security-authorize-web-endpoints-reference.adoc | 2 +- .../main/asciidoc/writing-native-applications-tips.adoc | 2 ++ 7 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/src/main/asciidoc/amqp.adoc b/docs/src/main/asciidoc/amqp.adoc index d36d6391cb059..b61117c1d8e44 100644 --- a/docs/src/main/asciidoc/amqp.adoc +++ b/docs/src/main/asciidoc/amqp.adoc @@ -151,9 +151,10 @@ Quarkus has built-in capabilities to deal with JSON AMQP messages. [NOTE] .@RegisterForReflection ==== -The `@RegisterForReflection` annotation instructs Quarkus to include the class (including fields and methods) when building the native executable. -This will be useful later when we run the applications as native executables inside containers. -Without, the native compilation would remove the fields and methods during the dead-code elimination phase. +The `@RegisterForReflection` annotation instructs Quarkus to keep the class, its fields, and methods when creating a native executable. +This is crucial when we later run our applications as native executables within containers. +Without this annotation, the native compilation process would discard the fields and methods during the dead-code elimination phase, which would lead to runtime errors. +More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. ==== == Sending quote request diff --git a/docs/src/main/asciidoc/cache.adoc b/docs/src/main/asciidoc/cache.adoc index c927e03a3cd9b..b27b6eba003fc 100644 --- a/docs/src/main/asciidoc/cache.adoc +++ b/docs/src/main/asciidoc/cache.adoc @@ -1075,3 +1075,4 @@ When you encounter this error, you can easily fix it by adding the following ann <1> It is an array, so you can register several cache implementations in one go if your configuration requires several of them. This annotation will register the cache implementation classes for reflection and this will include the classes into the native executable. +More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. \ No newline at end of file diff --git a/docs/src/main/asciidoc/mongodb.adoc b/docs/src/main/asciidoc/mongodb.adoc index 6093e86a9af16..cd069975a5293 100644 --- a/docs/src/main/asciidoc/mongodb.adoc +++ b/docs/src/main/asciidoc/mongodb.adoc @@ -701,7 +701,7 @@ Currently, Quarkus doesn't support link:https://docs.mongodb.com/manual/core/sec ==== If you encounter the following error when running your application in native mode: + `Failed to encode 'MyObject'. Encoding 'myVariable' errored with: Can't find a codec for class org.acme.MyVariable.` + -This means that the `org.acme.MyVariable` class is not known to GraalVM, the remedy is to add the `@RegisterForReflection` annotation to your `MyVariable class`. +This means that the `org.acme.MyVariable` class is not known to GraalVM, the remedy is to add the `@RegisterForReflection` annotation to your `MyVariable` class. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. ==== diff --git a/docs/src/main/asciidoc/qute-reference.adoc b/docs/src/main/asciidoc/qute-reference.adoc index 8b31a7c50f139..dff500a62efb2 100644 --- a/docs/src/main/asciidoc/qute-reference.adoc +++ b/docs/src/main/asciidoc/qute-reference.adoc @@ -2538,7 +2538,7 @@ There are several ways to solve this problem: ** In this case, an optimized value resolver is generated automatically and used at runtime ** This is the preferred solution * Annotate the model class with <> - a specialized value resolver is generated and used at runtime -* Annotate the model class with `@io.quarkus.runtime.annotations.RegisterForReflection` to make the reflection-based value resolver work +* Annotate the model class with `@io.quarkus.runtime.annotations.RegisterForReflection` to make the reflection-based value resolver work. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. [[rest_integration]] diff --git a/docs/src/main/asciidoc/rabbitmq.adoc b/docs/src/main/asciidoc/rabbitmq.adoc index 7e271f83876c1..67c23e1502072 100644 --- a/docs/src/main/asciidoc/rabbitmq.adoc +++ b/docs/src/main/asciidoc/rabbitmq.adoc @@ -173,9 +173,10 @@ Quarkus has built-in capabilities to deal with JSON RabbitMQ messages. [NOTE] .@RegisterForReflection ==== -The `@RegisterForReflection` annotation instructs Quarkus to include the class (including fields and methods) when building the native executable. -This will be useful later when we run the applications as native executables inside containers. -Without, the native compilation would remove the fields and methods during the dead-code elimination phase. +The `@RegisterForReflection` annotation instructs Quarkus to keep the class, its fields, and methods when creating a native executable. +This is crucial when we later run our applications as native executables within containers. +Without this annotation, the native compilation process would discard the fields and methods during the dead-code elimination phase, which would lead to runtime errors. +More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. ==== == Sending quote request diff --git a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc b/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc index 5f3f37c8a39ae..fdae898edb3e0 100644 --- a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc +++ b/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc @@ -882,7 +882,7 @@ public class MediaLibraryPermission extends LibraryPermission { } ---- -<1> When building a native executable, the permission class must be registered for reflection unless it is also used in at least one `io.quarkus.security.PermissionsAllowed#name` parameter. +<1> When building a native executable, the permission class must be registered for reflection unless it is also used in at least one `io.quarkus.security.PermissionsAllowed#name` parameter. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. <2> We want to pass the `MediaLibrary` instance to the `LibraryPermission` constructor. [source,properties] diff --git a/docs/src/main/asciidoc/writing-native-applications-tips.adoc b/docs/src/main/asciidoc/writing-native-applications-tips.adoc index 04afc5df02b1b..c7b6f86c8419a 100644 --- a/docs/src/main/asciidoc/writing-native-applications-tips.adoc +++ b/docs/src/main/asciidoc/writing-native-applications-tips.adoc @@ -197,6 +197,8 @@ public class MyReflectionConfiguration { } ---- +Note: By default the `@RegisterForReflection` annotation will also registered any potential nested classes for reflection. If you want to avoid this behavior, you can set the `ignoreNested` attribute to `true`. + ==== Using a configuration file You can also use a configuration file to register classes for reflection, if you prefer relying on the GraalVM infrastructure.