anchor.diff:  }
   ----
   
  -Using such a construct means that a `--delay-class-initialization-to-runtime` option will automatically be added to the `native-image` command line
  -
  -For more information about `--delay-class-initialization-to-runtime`, please read https://medium.com/graalvm/understanding-class-initialization-in-graalvm-native-image-generation-d765b7e4d6ed[this blog post].
  -
  -== Proxy Classes management
  -
  -While writing native application you'll need to define proxy classes at image build time by specifying the list of interfaces that they implement.
  -
  -In such a situation the error you might encounter is:
  -
  -[source]
  -----
  -com.oracle.svm.core.jdk.UnsupportedFeatureError: Proxy class defined by interfaces [interface org.apache.http.conn.HttpClientConnectionManager, interface org.apache.http.pool.ConnPoolControl, interface com.amazonaws.http.conn.Wrapped] not found. Generating proxy classes at runtime is not supported. Proxy classes need to be defined at image build time by specifying the list of interfaces that they implement. To define proxy classes use -H:DynamicProxyConfigurationFiles=<comma-separated-config-files> and -H:DynamicProxyConfigurationResources=<comma-separated-config-resources> options.
  -----
  -
  -Quarkus allows extensions authors to register a `SubstrateProxyDefinitionBuildItem`. An example of doing so is:
  +Using such a construct means that a `--initialize-at-run-time` option will automatically be added to the `native-image` command line.
  +
  +[NOTE]
  +====
  +For more information about `--initialize-at-run-time`, please read https://github.com/oracle/graal/blob/master/substratevm/CLASS-INITIALIZATION.md[the GraalVM documentation].
  +====
  +
  +=== Managing Proxy Classes
  +
  +Very similarly, Quarkus allows extensions authors to register a `SubstrateProxyDefinitionBuildItem`. An example of doing so is:
   
   [source,java]
   ----
  
positive.code: }
  ----
  
  More information about reflection in GraalVM can be found https://github.com/oracle/graal/blob/master/substratevm/REFLECTION.md[here].
  
  === Alternative with @RegisterForReflection
  
  In application code it is often needed to pass classes to libraries that use reflection to figure out the methods/fields of those classes.
  One such example is using http://json-b.net/[JSON-B] like so:
  
  [source,java]
  ----
      public class Person {
          private String first;
          private String last;
  
          public String getFirst() {
              return first;
          }
  
          public void setFirst(String first) {
              this.first = first;
          }
  
          public String getLast() {
              return last;
          }
  
          public void setValue(String last) {
              this.last = last;
          }
      }
  
      @Path("/person")
      @Produces(MediaType.APPLICATION_JSON)
      @Consumes(MediaType.APPLICATION_JSON)
      public class PersonResource {
  
          private final Jsonb jsonb;
  
          public PersonResource() {
              jsonb = JsonbBuilder.create(new JsonbConfig());
          }
  
          @GET
          public Response list() {
              return Response.ok(jsonb.fromJson("{\"first\":  \"foo\", \"last\":  \"bar\"}", Person.class)).build();
          }
      }
  ----
  
  If we were to use the code above, we would get an exception like the following when using the native executable:
  
  [source]
  ----
   Exception handling request to /person: org.jboss.resteasy.spi.UnhandledException: javax.json.bind.JsonbException: Can't create instance of a class: class org.acme.jsonb.Person, No default constructor found
  ----
  
  An even nastier possible outcome could be for no exception to be thrown, but instead the JSON result would be completely empty.
  
  To get around such problems, simply annotate `Person` with `@RegisterForReflection` so Quarkus will register the class as using reflection.
  
  == Including resources
  
  By default when building a native executable, GraalVM will not include any of the resources which are on the classpath into the native executable it creates. Such resources that are meant to be part of the native executable need to be specified explicitly.
  
  If one were to execute the native executable generation process manually, the `-H:IncludeResources=` flag would be used to point to a JSON configuration file that specifies which resources are to be included.
  
  Quarkus eliminates the need for such a JSON configuration file by allowing extension authors to specify a `SubstrateResourceBuildItem`.
  
  An example use could look like the following:
  
  [source,java]
  ----
  
negative.code: 
  include::./attributes.adoc[]
  
  This guide contains various tips and tricks for getting around problems that might arise when attempting to run Java applications as native executables.
  
  Note that we differentiate two contexts where the solution applied might be different:
  
   * in the context of an application, you will rely on configuring the `native-image` configuration by tweaking your `pom.xml`;
   * in the context of an extension, Quarkus offers a lot of infrastructure to simplify all of this.
  
  Please refer to the appropriate section depending on your context.
  
  == Supporting native in your application
  
  GraalVM imposes a number of constraints and making your application a native executable might require a few tweaks.
  
  === Including resources
  
  By default, when building a native executable, GraalVM will not include any of the resources that are on the classpath into the native executable it creates.
  Such resources that are meant to be part of the native executable need to be specified explicitly.
  
  Quarkus automatically includes the resources present in `META-INF/resources` (the web resources) but, outside of this directory, you are on your own.
  
  To include more resources in the native executable, create a `resources-config.json` JSON file at the root of your project defining which resources should be included:
  
  [source,json]
  ----
  {
    "resources": [
      {
        "pattern": ".*\\.xml$"
      },
      {
        "pattern": ".*\\.json$"
      }
    ]
  }
  ----
  
  The patterns are valid Java regexps.
  Here we include all the XML files and JSON files into the native executable.
  
  Now, let's tell the `native-image` executable about this configuration file by tweaking the `native-image` execution in your `pom.xml`:
  
  [source,xml]
  ----
  <plugin>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-maven-plugin</artifactId>
      <version>${version.quarkus}</version>
      <executions>
          <execution>
              <goals>
                  <goal>native-image</goal>
              </goals>
              <configuration>
                  <enableHttpUrlHandler>true</enableHttpUrlHandler>
                  <additionalBuildArgs>
                      <additionalBuildArg>-H:ResourceConfigurationFiles=${project.basedir}/resources-config.json</additionalBuildArg>
                  </additionalBuildArgs>
              </configuration>
          </execution>
      </executions>
  </plugin>
  ----
  
  Your resources will now be included in your native executable.
  
  [NOTE]
  ====
  You can find more information about this topic in https://github.com/oracle/graal/blob/master/substratevm/RESOURCES.md[the GraalVM documentation].
  ====
  
  === Registering for reflection
  
  When building a native executable, GraalVM operates with a closed world assumption.
  It analyzes the call tree and removes all the classes/methods/fields that are not used directly.
  
  The elements used via reflection are not part of the call tree so they are dead code eliminated (if not called directly in other cases).
  To include these elements in your native executable, you need to register them for reflection explicitly.
  
  This is a very common case as JSON libraries typically use reflection to serialize the objects to JSON:
  
  [source,java]
  ----
      public class Person {
          private String first;
          private String last;
  
          public String getFirst() {
              return first;
          }
  
          public void setFirst(String first) {
              this.first = first;
          }
  
          public String getLast() {
              return last;
          }
  
          public void setValue(String last) {
              this.last = last;
          }
      }
  
      @Path("/person")
      @Produces(MediaType.APPLICATION_JSON)
      @Consumes(MediaType.APPLICATION_JSON)
      public class PersonResource {
  
          private final Jsonb jsonb;
  
          public PersonResource() {
              jsonb = JsonbBuilder.create(new JsonbConfig());
          }
  
          @GET
          public Response list() {
              return Response.ok(jsonb.fromJson("{\"first\":  \"foo\", \"last\":  \"bar\"}", Person.class)).build();
          }
      }
  ----
  
  If we were to use the code above, we would get an exception like the following when using the native executable:
  
  [source]
  ----
   Exception handling request to /person: org.jboss.resteasy.spi.UnhandledException: javax.json.bind.JsonbException: Can't create instance of a class: class org.acme.jsonb.Person, No default constructor found
  ----
  
  An even nastier possible outcome could be for no exception to be thrown, but instead the JSON result would be completely empty.
  
  There are two different ways to fix this type of issues.
  
  ==== Using the @RegisterForReflection annotation
  
  The easiest way to register a class for reflection is to use the `@RegisterForReflection` annotation:
  
  [source,java]
  ----
  @RegisterForReflection
  public class MyClass {
  }
  ----
  
  ==== Using a configuration file
  
  Obviously, adding `@RegisterForReflection` is not possible if the class is in a third-party jar.
  
  In this case, you can use a configuration file to register classes for reflection.
  
  Let's create the `reflection-config.json` file at the root of the project:
  
  [source,json]
  ----
  [
    {
      "name" : "com.acme.MyClass",
      "allDeclaredConstructors" : true,
      "allPublicConstructors" : true,
      "allDeclaredMethods" : true,
      "allPublicMethods" : true,
      "allDeclaredFields" : true,
      "allPublicFields" : true
    }
  ]
  ----
  
  [NOTE]
  ====
  For more details on the format of this file, please refer to https://github.com/oracle/graal/blob/master/substratevm/REFLECTION.md[the GraalVM documentation].
  ====
  
  Now, let's tell the `native-image` executable about this configuration file by tweaking the `native-image` execution in the `pom.xml`:
  
  [source,xml]
  ----
  <plugin>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-maven-plugin</artifactId>
      <version>${version.quarkus}</version>
      <executions>
          <execution>
              <goals>
                  <goal>native-image</goal>
              </goals>
              <configuration>
                  <enableHttpUrlHandler>true</enableHttpUrlHandler>
                  <additionalBuildArgs>
                      <additionalBuildArg>-H:ReflectionConfigurationFiles=${project.basedir}/reflection-config.json</additionalBuildArg>
                  </additionalBuildArgs>
              </configuration>
          </execution>
      </executions>
  </plugin>
  ----
  
  `com.acme.MyClass` will now be registered for reflection and included in the native executable.
  
  === Delaying class initialization
  
  By default, Quarkus initializes all classes at build time.
  
  There are cases where the initialization of certain classes is done in a static block needs to be postponed to runtime.
  Typically omitting such configuration would result in a runtime exception like the following:
  
  [source]
  ----
  Error: No instances are allowed in the image heap for a class that is initialized or reinitialized at image runtime: sun.security.provider.NativePRNG
  Trace: object java.security.SecureRandom
  method com.amazonaws.services.s3.model.CryptoConfiguration.<init>(CryptoMode)
  Call path from entry point to com.amazonaws.services.s3.model.CryptoConfiguration.<init>(CryptoMode):
  ----
  
  If you need to delay the initialization of a class, you can use the `--initialize-at-run-time=<package or class>` configuration knob.
  
  It should be added to the `native-image` configuration using an `<additionalBuildArg>` as shown in the examples above.
  
  [NOTE]
  ====
  You can find more information about all this in https://github.com/oracle/graal/blob/master/substratevm/CLASS-INITIALIZATION.md[the GraalVM documentation].
  ====
  
  === Managing Proxy Classes
  
  While writing native application you'll need to define proxy classes at image build time by specifying the list of interfaces that they implement.
  
  In such a situation, the error you might encounter is:
  
  [source]
  ----
  com.oracle.svm.core.jdk.UnsupportedFeatureError: Proxy class defined by interfaces [interface org.apache.http.conn.HttpClientConnectionManager, interface org.apache.http.pool.ConnPoolControl, interface com.amazonaws.http.conn.Wrapped] not found. Generating proxy classes at runtime is not supported. Proxy classes need to be defined at image build time by specifying the list of interfaces that they implement. To define proxy classes use -H:DynamicProxyConfigurationFiles=<comma-separated-config-files> and -H:DynamicProxyConfigurationResources=<comma-separated-config-resources> options.
  ----
  
  Solving this issue requires adding the `-H:DynamicProxyConfigurationResources=<comma-separated-config-resources>` option and to provide a dynamic proxy configuration file.
  You can find all the information about the format of this file in https://github.com/oracle/graal/blob/master/substratevm/DYNAMIC_PROXY.md#manual-configuration[the GraalVM documentation].
  
  [[native-in-extension]]
  == Supporting native in a Quarkus extension
  
  Supporting native in a Quarkus extension is even easier as Quarkus provides a lot of tools to simplify all this.
  
  [WARNING]
  ====
  Everything described here will only work in the context of Quarkus extensions, it won't work in an application.
  ====
  
  === Register reflection
  
  Quarkus makes registration of reflection in an extension a breeze by using `ReflectiveClassBuildItem`, thus eliminating the need for a JSON configuration file.
  
  To register a class for reflection, one would need to create a Quarkus processor class and add a build step that registers reflection:
  
  [source,java]
  ----
  