Allow package-private planning domain classes and methods

[theoema]

Problem

Timefold requires all planning domain classes, getters, and setters to be public. This is enforced by MemberAccessorValidator, but the underlying accessor layer already handles non-public access — making this restriction unnecessary.

The contradiction

The reflection-based accessor already calls setAccessible(true) and creates a MethodHandle that works fine with non-public methods:

// ReflectionBeanPropertyMemberAccessor.java
public ReflectionBeanPropertyMemberAccessor(Method getterMethod, AnnotatedElement annotatedElement, boolean getterOnly) {
    this.getterMethod = getterMethod;
    MethodHandles.Lookup lookup = MethodHandles.lookup();
    this.getterMethod.setAccessible(true);                          // ← handles non-public
    this.getherMethodHandle = lookup.unreflect(getterMethod)        // ← creates fast MethodHandle
            .asFixedArity();
    // ...
}

At runtime, it invokes via MethodHandle, not raw Method.invoke():

public Object executeGetter(Object bean) {
    return getherMethodHandle.invoke(bean);  // MethodHandle — JIT-optimized to direct call
}

But MemberAccessorValidator rejects non-public members before the accessor ever gets a chance:

// MemberAccessorValidator.java — declaring class gate
private static void verifyDeclaringClassIsAccessible(Member member, String messagePrefix) {
    var declaringClass = member.getDeclaringClass();
    if (!Modifier.isPublic(declaringClass.getModifiers())) {
        throw new IllegalArgumentException(
                "%s is not accessible because its declaring class (%s) is not public."
                    .formatted(messagePrefix, declaringClass.getCanonicalName()));
    }
}

// MemberAccessorValidator.java — repeated across verifyFieldOrGetter, verifyIsVoidMethod,
// verifyIsPublicFieldOrHasReadMethod, verifyGetterSetterProperties
if (!Modifier.isPublic(method.getModifiers())) {
    throw new IllegalArgumentException(
            "%s is a getter method, but it is not public."
                .formatted(messagePrefix));
}

There's also a discovery-layer issue — ReflectionHelper uses Class.getMethod() which only returns public methods, so package-private getters are invisible before validation even runs.

What about Gizmo performance?

The Gizmo path generates bytecode with direct invokeVirtual instructions, which requires public access. However, the reflection path already uses MethodHandle — which the JVM JIT-compiles to the same direct call after warmup:

Path	Runtime execution	After JIT
Gizmo	invokeVirtual bytecode	direct call
Reflection (MethodHandle)	MethodHandle.invoke()	direct call (inlined)

For non-public members, falling back to the MethodHandle-based reflection path carries no meaningful performance penalty. The Gizmo implementor itself documents this constraint:

// GizmoMemberAccessorImplementor.java (line 353)
// The member MUST be public if not called in Quarkus
// (i.e. we don't delegate to the field getter/setter).

Why this matters

Package-private domain models are a standard Java encapsulation pattern. In modular codebases, it's common to keep domain classes package-private and expose only the API boundary publicly. Today you're forced to write:

// Everything must be public even though nothing outside this package needs access
public class Lesson {
    public Timeslot getTimeslot() { ... }
    public void setTimeslot(Timeslot timeslot) { ... }
}

This would enable:

class Lesson {
    Timeslot getTimeslot() { ... }
    void setTimeslot(Timeslot timeslot) { ... }
}

Scope

This is a small change — no behavior change for existing public classes, no performance impact, and the accessor infrastructure already supports it.

[triceo]

@theoema Thank you for reporting this! Unfortunately, I do not agree with your assessment, and this change was made intentionally. setAccessible is wrong precisely because it breaks encapsulation.

The JDK is moving on a path towards making setAccessible problematic, to a point that users would have to run their JVMs with specific arguments only to make this possible. We are preparing users for a future where setAccessible is no longer a thing.

If you want us to access your fields through reflection, you need to make a decision to open those fields to us. This is your choice, as a user and an owner of your codebase - we have no right to break into your encapsulation. We have been doing that until recently, and we no longer want to. It has to be your choice to allow us to access your methods and fields.

[theoema]

@triceo That's a fair point. I agree that setAccessible is the wrong direction, and I appreciate that Timefold is being intentional about not breaking user encapsulation.

But this creates an interesting tension: when a user annotates a class with @PlanningSolution or @PlanningEntity, they are explicitly choosing to give Timefold access. The annotation is the consent. Requiring public on top of that means the user has to break their own encapsulation (exposing internals to their entire module) just so the framework can read the consent they already gave.

What if there was a programmatic configuration API that sidesteps reflection entirely? Something like:

SolverFactory<Timetable> factory = SolverFactory.create(
    SolverConfig.builder()
        .withSolutionModel(SolutionModel.of(Timetable.class)
            .score(Timetable::getScore, Timetable::setScore)
            .problemFacts("rooms", Timetable::getRooms)
            .problemFacts("timeslots", Timetable::getTimeslots)
            .entityCollection("lessons", Timetable::getLessons,
                EntityModel.of(Lesson.class)
                    .genuineVariable("timeslot",
                        Lesson::getTimeslot, Lesson::setTimeslot,
                        ValueRange.from(Timetable::getTimeslots))
                    .genuineVariable("room",
                        Lesson::getRoom, Lesson::setRoom,
                        ValueRange.from(Timetable::getRooms))
            )
        )
        .withConstraintProvider(TimetableConstraintProvider::new)
        .build()
);

This would:

• Use zero reflection. Method references compile to invokedynamic, so the compiler resolves access at the call site. No setAccessible, no JDK compatibility concerns.
• Be the most explicit consent possible. The user directly hands the framework the accessors. Timefold never reaches into anything.
• Allow package-private naturally. If the code compiles, the user has access rights. The JVM enforces the rules, not the framework.
• Simplify GraalVM native support. Lambdas are regular bytecode, so no reflection metadata registration or Gizmo bytecode generation is needed.

The annotation-based API would keep working exactly as-is for users who prefer it. This would just be an alternative path that aligns with the direction you're already heading, away from reflection and toward explicit user control.

Would this be something the team would consider?

[triceo]

But this creates an interesting tension: when a user annotates a class with @PlanningSolution or @PlanningEntity, they are explicitly choosing to give Timefold access. The annotation is the consent. Requiring public on top of that means the user has to break their own encapsulation (exposing internals to their entire module) just so the framework can read the consent they already gave.

I see your point. Unfortunately, in a world without setAccessible, there really is no other option but for you to open up your domain. With JPMS at least, you don't need to open it to everyone - you can make a choice to open it to Timefold Solver only.

This is a problem which is not unique to Timefold Solver. For example, we use JAXB heavily for serializing solver configs, and we are likewise forced to open our entire config hierarchy to JAXB for reflection. Reflection is magic, it has a cost, and that cost was being hidden from users. It is being hidden no more.

Would this be something the team would consider?

We are thinking of something like this - albeit for different reasons, but we are. I can't promise if and when it'll happen though.

[theoema]

@triceo Alright, Im thinking of implementing a programmatic API like the one I suggested for personal use. Is it something you guys would be interested in getting a PR for? It would include decoupling your discovery mechanisms from the domain model layer.

[triceo]

The difficulty here comes from the fact that solutions and entities can have a lot of bells and whistles. Shadow variables, methods which compute values for those shadow variables, all sorts of comparators for construction heuristics, value ranges on solutions and entities, ... Not to mention that these types would have to have some support for cloning, which also happens through reflection. (And does currently use setAccessible; we have yet to solve the problem of cloning.)

My estimation was that, when someone on my team starts working on this, it would take many months to deliver. Because it touches literally every piece of the solver, it is a can of worms. And in the end, the resulting builder may just become a monster which is not worth its weight.

We have not yet done something on this scale as a community contribution. I find it tempting though. It would for sure require immense patience on both sides, much iteration and back-and-forth, and very long timelines.

If you're up for that, then let's see the first design which takes into account the things I outlined above, and see where it takes us; let's see a design for a builder that produces an instance of some internal @PlanningSolution instance. If we know what the type is, we can internally generate everything and not rely on reflection.

(Our ultimate goal was going to be to entirely remove the need for a planning solution, but that is currently a bridge too far.)

[Christopher-Chianelli]

FYI, MethodHandle is not inlined unless it is static final, and the MethodHandle we use are instance fields. When I tested, there is a 12% drop in solving speed when MethodHandle are used.