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

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

[[charsets]]
== Character encodings

By default only the following `Charsets` are available in the 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.

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

Resources needed at runtime need to be explicitly embedded in the built native executable. In such situations, the `include-patterns` and `exclude-patterns` configurations could be set in `application.properties` as demonstrated below:

[source,properties]
----
quarkus.camel.native.resources.include-patterns = docs/*,images/*
quarkus.camel.native.resources.exclude-patterns = 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.

`include-patterns` and `exclude-patterns` are list of comma separated link:https://github.com/apache/camel/blob/master/core/camel-util/src/main/java/org/apache/camel/util/AntPathMatcher.java[Ant-path style patterns].
At the end of the day, resources matching `include-patterns` are marked for inclusion at the exception of resources matching `exclude-patterns`.

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

When using xref:latest@manual::exception-clause.adoc[camel onException handling] in native mode, it is the application developer's 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
----
