Compiling a Spring Boot service that uses Timefold to Native Image

[thimmwork]

Hi everyone,

I took a look at Spring Boot 3 native images and managed to migrate an existing service that uses Timefold.
Probably there are others out there who could benefit from this, so let me list the steps I had to do:

Build using GraalVM

I'm on a Mac, so I used sdkman and sdk use java 21.0.1-graalce.
The build process runs docker images, so I used brew install colima and colima start to set up colima as docker drop-in replacement.
In addition, I had to create symbolic links like this to make colima available to the build plugin:
sudo ln -s ~/.colima/docker.sock /var/run/docker.sock && ln -s ~/.colima/docker.sock ~/.docker/docker.sock

My project is a maven project, so I used maven 3.9.5 and mvn -Pnative clean package to build.

Also, I used graalvm's native-maven-plugin instead of the spring-boot-plugin's build-image goal. The spring-boot-plugin was hard to satisfy due to limitation to a small set of exact supported JDK minor versions.

I've set an environement variable, though I'm not sure whether it has an effect:

export GRAALVM_QUICK_BUILD=true

Maven profile

Spring Boot comes with a preconfigured profile native, but I had to add this snippet to get useful error messages in case native compilation fails:

        <profile>
            <id>native</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.graalvm.buildtools</groupId>
                        <artifactId>native-maven-plugin</artifactId>
                        <configuration>
                            <buildArgs>-H:+ReportExceptionStackTraces -H:BuildOutputJSONFile=target/buildoutput.json</buildArgs>
                        </configuration>
                        <executions>
                            <execution>
                                <id>build-native</id>
                                <goals>
                                    <goal>compile-no-fork</goal>
                                </goals>
                                <phase>package</phase>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>

I don't want to build the native image every time I compile locally, so the profile is not active by default, but specifically activated by the CI/CD pipeline.
The first buildArg will provide you with more detailed information in case errors occur. The second buildArg creates a short json that summarizes build time and used resources. This may come handy when provisioning CI/CD runners etc.

Configure Gizmo

Fortunately, I already switched to Gizmo some months ago.
Gizmo needs planning variables to be public fields.

It doesn't interact well with Kotlin due to Kotlin's property convention, so I ended up rewriting the Solution, PlanningEntities and PlanningFacts in Java. After all, Java is an island within my codebase, surrounded by a sea of Kotlin ;)

As described in Timefold's documentation, add this line to your solverConfig.xml:

    <domainAccessType>GIZMO</domainAccessType>

and make sure you have

        <dependency>
            <groupId>io.quarkus.gizmo</groupId>
            <artifactId>gizmo</artifactId>
        </dependency>

on your classpath.

Create solverFactory ahead of time

Creating the SolverFactory triggers Gizmo which needs to run ahead of time because it uses the Java ByteCode compiler to generate code.
I used this class:

@Configuration
public class AotSolverFactoryConfig {
    //has to run Ahead of Time: uses Gizmo which uses Java ByteCode compiler
    private static final SolverFactory<MySolutionClass> solverFactory =
            SolverFactory.createFromXmlResource("MySolverConfig.xml");

    @Bean
    public static BeanFactoryInitializationAotProcessor aotSolverFactoryProcessor() {
        return beanFactory -> (ctx, code) -> {};
    }

    @Bean
    public Supplier<Solver<MySolutionClass>> aotSolverFactory() {
        return solverFactory::buildSolver;
    }
}

In my @Service class, I'm using constructor injection to get a supplier

       Supplier<Solver<MySolutionClass>> aotSolverFactory

and get the actual solver instance with

        var solver = aotSolverFactory.get();

Unit Tests

In unit tests, I initialize my @Service class by calling the constructor with a self-instantiated instance:

   var myService = new MyService(new AotSolverFactoryConfig().aotSolverFactory());

JaCoCo code coverage

My service uses JaCoCo for test coverage checks. The classes generated by Spring generate false-positives. Though this is not Timefold-related, the generated classes may very carry your Timefold-related bean factory names.
Add this to your jacoco plugin/configuration/exclusions to ignore coverage for the generated classes:

                        <exclude>**/*__BeanDefinitions*</exclude>
                        <exclude>**/*__BeanFactoryRegistrations*</exclude>
                        <exclude>**/*__Autowiring*</exclude>
                        <exclude>**/*__ApplicationContextInitializer*</exclude>
                        <exclude>**/*SpringCGLIB*</exclude>

Additional metadata

When running the native binary, there was still some reflection that failed. When I ran

java -Dspring.aot.enabled=true -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image/ -jar target/my-service-1.0-SNAPSHOT.jar

the java agent generated additional metadata into my project's src/main/resources/META-INF/ folder.
This folder is then automatically used in the next compile run to add reflection information for the respective classes to the native image.
I had to run this a couple of times to get it to completion, which is why I added the files to git. They will rarely change in the future for my service. Make sure you trigger all relevant code paths, especially a Timefold solver run (and other paths using dependencies beyond the spring boot ecosystem).

Statistics

The folder META-INF takes up 324 kB.
My project takes 0m56s to compile a jar of 96 MB
and 6m01s with native profile to compile a binary of 212 MB.

Credit

Quite some credit goes to https://www.baeldung.com/spring-native-intro

Have you used native images yet?
I would like to hear your thoughts and experience.

[triceo]

@thimmwork Interesting! We definitely intend to support Spring in Native mode. Your write-up will come in handy.

[ge0ffrey]

@thimmwork Great writeup!

Sounds like we want that AotSolverFactoryConfig logic in the spring autoconfigure plugin?
https://github.com/TimefoldAI/timefold-solver/tree/main/spring-integration/spring-boot-autoconfigure
Do you want to contribute a Pull Request for it?

[thimmwork]

I'll see what I can do. I just found out that my writeup wasn't as complete as I hoped it to be.
I'm having trouble applying it to the java-spring-boot quickstart, and I'm still trying to figure out why it behaves totally different than my project. It might take me some days.

[ge0ffrey]

No worries, we'll figure this out. This a great start!

[ge0ffrey]

Issue: #547

[ge0ffrey]

"Gizmo does not work well with Kotlin due to Kotlin's property convention"
Can you talk a bit more about that? That sounds like an issue we want to fix.

[thimmwork]

I didn't dive into it deeply, but with

@PlanningSolution
class MySolution {
    @get:PlanningEntityCollectionProperty
    var itemList: List<Item> = listOf()
    ...

I get the error
Caused by: java.lang.ExceptionInInitializerError: Exception java.lang.IllegalStateException: Member (itemList) of class (com.acme.model.MySolution) is not public and domainAccessType is GIZMO. Maybe put the annotations onto the public getter of the field. Maybe use domainAccessType REFLECTION instead of GIZMO. [in thread "main"]
which is irritating, because the annotation is on the getter, as it explicitly has the Kotlin prefix get:.

But you're right: This isn't an issue with Gizmo itself, it originates in Timefold.
I didn't put much thought to it at the time, but instead went for the public fields approach, as it only affected a few properties in my model.
It seems that GizmoSolutionOrEntityDescriptor creates a GizmoMemberDescriptor for both the getters and the fields, and when iterating over them, it fails at the first field because Modifier.isPublic() returns false.

[ge0ffrey]

Thank you, we're tracking it here:
#583
Could be a bug in GizmoMemberDescriptor indeed. Normally that should be field xor getter-setter. Never both.