= Native mode
:page-aliases: native-mode.adoc

Things to consider before you run your application in native mode.

[[charsets]]
== Character encodings

By default only the following `Charsets` are available in native mode (https://github.com/oracle/graal/blob/vm-19.3.0/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/jdk/LocalizationFeature.java#L149-L163[source]):

[source,text]
----
Charset.defaultCharset(), US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16
----

If you expect your application to need any encoding not included in this set or if you see
an `UnsupportedCharsetException` thrown in the native mode, please add the following entry to your
`application.properties`:

[source,properties]
----
quarkus.native.add-all-charsets = true
----

See also https://quarkus.io/guides/all-config#quarkus-core_quarkus.native.add-all-charsets[quarkus.native.add-all-charsets]
in Quarkus documentation.

[[locale]]
== Locale

Before GraalVM 21.1, only the building JVM's default locale was included in the native image.
Quarkus offered a way to set that locale via `application.properties`, so that you did not need to rely on `LANG` and `LC_*` environement variables:

[source,properties]
----
quarkus.native.user-country=US
quarkus.native.user-language=en
----

Since https://medium.com/graalvm/graalvm-21-1-96e18f6806bf#7ce8[GraalVM 21.1], there is a support for embedding multiple locales into the native image
and for selecting the default locale via GraalVM command line options `-H:IncludeLocales=fr,en`, `H:+IncludeAllLocales` and `-H:DefaultLocale=de`.
You can set those via Quarkus `quarkus.native.additional-build-args` property.

[[embedding-resource-in-native-executable]]
== Embedding resources in the native executable

Resources accessed via `Class.getResource()`, `Class.getResourceAsStream()`, `ClassLoader.getResource()`,
`ClassLoader.getResourceAsStream()`, etc. at runtime need to be explicitly listed for including in the native executable.

This can be done using Quarkus `quarkus.native.resources.includes` and `quarkus.native.resources.excludes` properties
in `application.properties` file as demonstrated below:

[source,properties]
----
quarkus.native.resources.includes = docs/*,images/*
quarkus.native.resources.excludes = docs/ignored.adoc,images/ignored.png
----

In the example above, resources named `docs/included.adoc` and `images/included.png` would be embedded in the native executable
while `docs/ignored.adoc` and `images/ignored.png` would not.

`resources.includes` and `resources.excludes` are both lists of comma separated Ant-path style glob patterns.
Please refer to https://quarkus.io/guides/building-native-image#quarkus-native-pkg-native-config_quarkus.native.resources.includes[Quarkus documentation] for more details.

[[using-onexception-clause-in-native-mode]]
== Using the onException clause in native mode

When using xref:latest@manual::exception-clause.adoc[camel onException handling] in native mode, it is the application developers responsibility to register exception classes for reflection.

For instance, having a camel context with onException handling as below:

[source,java]
----
onException(MyException.class).handled(true);
from("direct:route-that-could-produce-my-exception").throw(MyException.class);
----

The class `mypackage.MyException` should be registered for reflection, see more in xref:user-guide/native-mode.adoc#reflection[Registering classes for reflection].

[[reflection]]
== Registering classes for reflection

By default, dynamic reflection is not available in native mode. Classes for which reflective access is needed, have to be
registered for reflection at compile time.

In many cases, application developers do not need to care because Quarkus extensions are able to detect the classes that
require the reflection and register them automatically.

However, in some situations, Quarkus extensions may miss some classes and it is up to the application developer to
register them. There are two ways to do that:

1. The `https://quarkus.io/guides/writing-native-applications-tips#alternative-with-registerforreflection[@io.quarkus.runtime.annotations.RegisterForReflection]`
annotation can be used to register classes on which it is used, or it can also register third party classes via
its `targets` attribute.

2. The `quarkus.camel.native.reflection` options in `application.properties`:
+
[source,properties]
----
quarkus.camel.native.reflection.include-patterns = org.apache.commons.lang3.tuple.*
quarkus.camel.native.reflection.exclude-patterns = org.apache.commons.lang3.tuple.*Triple
----
+
For these options to work properly, the artifacts containing the selected classes
must either contain a Jandex index ({@code META-INF/jandex.idx}) or they must
be registered for indexing using the {@code quarkus.index-dependency.*} options
in {@code application.properties} - e.g.
+
[source,properties]
----
quarkus.index-dependency.commons-lang3.group-id = org.apache.commons
quarkus.index-dependency.commons-lang3.artifact-id = commons-lang3
----

[[serialization]]
== Registering classes for serialization

If serialization support is requested via `quarkus.camel.native.reflection.serialization-enabled`, the classes listed in https://github.com/apache/camel-quarkus/blob/main/extensions-core/core/deployment/src/main/java/org/apache/camel/quarkus/core/deployment/CamelSerializationProcessor.java[CamelSerializationProcessor.BASE_SERIALIZATION_CLASSES] are automatically registered for serialization.

Users can register more classes using `@RegisterForReflection(serialization = true)`.
