Native mode

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

Character encodings

By default, not all Charsets are available in native mode.

As such, you may face situations where an encoding is missing in native mode, for instance an application throwing UnsupportedCharsetException. In such a case, you may consider using the configuration option below:

quarkus.native.add-all-charsets = true

See also quarkus.native.add-all-charsets in Quarkus documentation.

Locale

By default, only the building JVM default locale is included in the native image. Quarkus provides a way to set the locale via application.properties, so that you do not need to rely on LANG and LC_* environment variables:

quarkus.default-locale=en-US

There is also support for embedding multiple locales into the native image.

quarkus.locales=en-US,es-ES,fr-FR

Using a value of all will include all available locales into the native image.

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 the quarkus.native.resources.includes configuration option in application.properties as demonstrated below:

quarkus.native.resources.includes = docs/*,images/*

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

quarkus.native.resources.includes is a list of comma separated Ant-path style glob patterns. Please refer to Quarkus documentation for more details.

Using the onException clause in native mode

When using Camel onException handling in native mode, it is the application developers responsibility to register the exception classes for reflection.

For instance, with an exception handler like this

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

the class MyException should be registered for reflection, see more in Registering classes for 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 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 @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.

    import io.quarkus.runtime.annotations.RegisterForReflection;

@RegisterForReflection
class MyClassAccessedReflectively {
}

@RegisterForReflection(
    targets = {
        org.third-party.Class1.class,
        org.third-party.Class2.class
    }
)
class ReflectionRegistrations {
}

  2. The quarkus.camel.native.reflection options in application.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 (META-INF/jandex.idx) or they must be registered for indexing using the quarkus.index-dependency.* options in application.properties - e.g.

    quarkus.index-dependency.commons-lang3.group-id = org.apache.commons
quarkus.index-dependency.commons-lang3.artifact-id = commons-lang3

Registering classes for serialization

Some extensions require Java serialization support in order to work. For example, camel-quarkus-netty installs a codec based on Java serialization by default, camel-quarkus-management needs it for JMX, and camel-quarkus-jms needs it to handle ObjectMessage payloads or routes configured with transferExchange=true. Such extensions automatically register the classes listed in CamelSerializationProcessor.BASE_SERIALIZATION_CLASSES for serialization.

The quarkus.camel.native.reflection.serialization-enabled option controls this behavior:

  • When the option is not set, classes are registered for serialization only if an extension on the classpath requires it. This is the default.

  • When set to true, the base set of classes is always registered for serialization. This is needed for functionality that relies on serialization but is not tied to an extension that enables it automatically, such as the Cassandra and Infinispan aggregation repositories.

  • When set to false, nothing is registered for serialization, even if extensions on the classpath require it. This bounds what the native image is able to deserialize, at the cost of breaking any component that depends on Java serialization.

Note that this option governs only the base set of classes and any additional classes that extensions register alongside it. Classes registered individually with @io.quarkus.runtime.annotations.RegisterForReflection(serialization = true) are not affected.

Users can register more classes using @io.quarkus.runtime.annotations.RegisterForReflection(serialization = true).

Back to top