From 51369e2745b72aa0ab39d8dd88e914fbeb8b3da8 Mon Sep 17 00:00:00 2001 From: Clement Escoffier Date: Mon, 3 May 2021 08:06:16 +0200 Subject: [PATCH] Extend the @RegisterForReflection documentation - add an example with multiple classes registered - add a canonical example - link the section in the various guides mentioning the @RegisterForReflection annotation Fix https://github.com/quarkusio/quarkus/issues/16555. --- docs/src/main/asciidoc/amazon-dynamodb.adoc | 3 +++ docs/src/main/asciidoc/amazon-sns.adoc | 3 +++ docs/src/main/asciidoc/amazon-sqs.adoc | 3 +++ docs/src/main/asciidoc/hibernate-orm-panache.adoc | 3 ++- docs/src/main/asciidoc/kafka-streams.adoc | 2 +- docs/src/main/asciidoc/mongodb.adoc | 1 + docs/src/main/asciidoc/rest-json.adoc | 2 ++ .../writing-native-applications-tips.adoc | 15 +++++++++++++-- 8 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/src/main/asciidoc/amazon-dynamodb.adoc b/docs/src/main/asciidoc/amazon-dynamodb.adoc index 1cd9388069a16..6f3b04ccdf99c 100644 --- a/docs/src/main/asciidoc/amazon-dynamodb.adoc +++ b/docs/src/main/asciidoc/amazon-dynamodb.adoc @@ -180,6 +180,9 @@ public class Fruit { } ---- +TIP: The `@RegisterForReflection` annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. + + Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static `from` method creates a bean based on the `Map` object provided by the DynamoDB client response. diff --git a/docs/src/main/asciidoc/amazon-sns.adoc b/docs/src/main/asciidoc/amazon-sns.adoc index 5530ad4957736..62f028c7bddd1 100644 --- a/docs/src/main/asciidoc/amazon-sns.adoc +++ b/docs/src/main/asciidoc/amazon-sns.adoc @@ -158,6 +158,9 @@ public class Quark { ---- Then, create a `org.acme.sns.QuarksCannonSyncResource` that will provide an API to shoot quarks into the SNS topic via the SNS synchronous client. +TIP: The `@RegisterForReflection` annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. + + [source,java] ---- package org.acme.sns; diff --git a/docs/src/main/asciidoc/amazon-sqs.adoc b/docs/src/main/asciidoc/amazon-sqs.adoc index c3638db17f8a8..551e3cf9be9b4 100644 --- a/docs/src/main/asciidoc/amazon-sqs.adoc +++ b/docs/src/main/asciidoc/amazon-sqs.adoc @@ -159,6 +159,9 @@ public class Quark { ---- Then, create a `org.acme.sqs.QuarksCannonSyncResource` that will provide an API to shoot quarks into the SQS queue using the synchronous client. +TIP: The `@RegisterForReflection` annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. + + [source,java] ---- package org.acme.sqs; diff --git a/docs/src/main/asciidoc/hibernate-orm-panache.adoc b/docs/src/main/asciidoc/hibernate-orm-panache.adoc index 36c2c919541f9..df2673a40114b 100644 --- a/docs/src/main/asciidoc/hibernate-orm-panache.adoc +++ b/docs/src/main/asciidoc/hibernate-orm-panache.adoc @@ -607,10 +607,11 @@ public class PersonName { PanacheQuery query = Person.find("status", Status.Alive).project(PersonName.class); ---- -1. If you plan to deploy your application as a native executable, you must register manually the projection class for reflection. +1. The `@RegisterForReflection` annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. 2. We use public fields here, but you can use private fields and getters/setters if you prefer. 3. This constructor will be used by Hibernate, it must be the only constructor in your class and have all the class attributes as parameters. + [WARNING] ==== The implementation of the `project(Class)` method uses the constructor's parameter names to build the select clause of the query, diff --git a/docs/src/main/asciidoc/kafka-streams.adoc b/docs/src/main/asciidoc/kafka-streams.adoc index 941ec5855e35f..4ecf5e290a079 100644 --- a/docs/src/main/asciidoc/kafka-streams.adoc +++ b/docs/src/main/asciidoc/kafka-streams.adoc @@ -287,7 +287,7 @@ public class WeatherStation { public String name; } ---- -<1> By adding the `@RegisterForReflection` annotation, it is ensured that this type can be instantiated reflectively when running the application in native mode. +<1> The `@RegisterForReflection` annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. Then the file `aggregator/src/main/java/org/acme/kafka/streams/aggregator/model/TemperatureMeasurement.java`, representing temperature measurements for a given station: diff --git a/docs/src/main/asciidoc/mongodb.adoc b/docs/src/main/asciidoc/mongodb.adoc index 99ec7968ccce1..8c2cb3af8cbad 100644 --- a/docs/src/main/asciidoc/mongodb.adoc +++ b/docs/src/main/asciidoc/mongodb.adoc @@ -659,6 +659,7 @@ link:https://docs.mongodb.com/manual/core/security-client-side-encryption/[Clien 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`. +More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. ==== == Conclusion diff --git a/docs/src/main/asciidoc/rest-json.adoc b/docs/src/main/asciidoc/rest-json.adoc index 2a11680a7c5a7..a7d5a5a6aba78 100644 --- a/docs/src/main/asciidoc/rest-json.adoc +++ b/docs/src/main/asciidoc/rest-json.adoc @@ -463,6 +463,8 @@ public class Legume { } ---- +TIP: The `@RegisterForReflection` annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the `@RegisterForReflection` annotation can be found on the xref:writing-native-applications-tips.adoc#registerForReflection[native application tips] page. + Let's do that and follow the same steps as before: * hit `Ctrl+C` to stop the application diff --git a/docs/src/main/asciidoc/writing-native-applications-tips.adoc b/docs/src/main/asciidoc/writing-native-applications-tips.adoc index 44f0f7bd4a8d8..359247cdfd46d 100644 --- a/docs/src/main/asciidoc/writing-native-applications-tips.adoc +++ b/docs/src/main/asciidoc/writing-native-applications-tips.adoc @@ -161,6 +161,7 @@ An even nastier possible outcome could be for no exception to be thrown, but ins There are two different ways to fix this type of issues. +[#registerForReflection] ==== Using the @RegisterForReflection annotation The easiest way to register a class for reflection is to use the `@RegisterForReflection` annotation: @@ -176,12 +177,22 @@ If your class is in a third-party jar, you can do it by using an empty class tha [source,java] ---- -@RegisterForReflection(targets=MyClass.class) +@RegisterForReflection(targets={ MyClassRequiringReflection.class, MySecondClassRequiringReflection.class}) public class MyReflectionConfiguration { } ---- -Note that `MyClass` will be registered for reflection but not `MyReflectionConfiguration`. +Note that `MyClassRequiringReflection` and `MySecondClassRequiringReflection` will be registered for reflection but not `MyReflectionConfiguration`. + +This feature is handy when using third-party libraries using object mapping features (such as Jackson or GSON): + +[source, java] +---- +@RegisterForReflection(targets = {User.class, UserImpl.class}) +public class MyReflectionConfiguration { + +} +---- ==== Using a configuration file