Skip to content

Compiled APIs ​

Runtime Flexibility, Compiled Speed. SJF4J can turn annotated Java interfaces into specialized implementations during compilation. The result is ordinary, readable Java source code that can be inspected, debugged, and optimized by the JVM.

Compiled APIs complement SJF4J's flexible runtime APIs. They are designed for stable operations where type information and expressions are known ahead of time.

How It Works ​

Define an interface that describes what you want to do. SJF4J's annotation processor analyzes the interface and generates its implementation at build time.

Define InterfaceJava
@CompiledNavigator
interface UserNavigator {
    @GetByPath("$.address.city")
    String getCity(User user);
}
Generated CodeJava
public final class UserNavigator_Impl
        implements UserNavigator {

    @Override
    public String getCity(User user) {
        if (user == null) return null;
        Address a = user.address;
        return a == null ? null : a.city;
    }
}

The generated implementation above is a simplified illustration, not verbatim processor output. In this example, User has an Address address property, and Address has a String city property.

Use the interface as you would any other Java API:

java
UserNavigator navigator = CompiledInstances.create(UserNavigator.class);
String city = navigator.getCity(user);

The generated class is named UserNavigator_Impl. Its compiled methods can replace repeated path interpretation and generic dispatch with direct Java access where the model permits. Some operations still call SJF4J runtime support where necessary.

The process is straightforward: declare an interface → compile the generated Java → call the implementation. There is no separate bytecode interpreter or required intermediate JSON tree.

Available Compiled APIs ​

The same compile-time programming model covers five capabilities:

AnnotationGenerated capabilityGuide
@CompiledBinderSpecialized reads and writes for selected formats and backendsBinding
@CompiledNavigatorJSONPath access, querying, and updatesNavigating
@CompiledValidatorValidation of statically bound JSON SchemasValidating
@CompiledMapperJava object-to-object mapping and updatesObject Mapping
@CompiledJdbcMapperDirect JDBC ResultSet-to-object mappingJDBC Mapping

Each annotation generates a dedicated _Impl class for its interface, but the supported method signatures and compilation rules differ by capability.

In particular, @CompiledJdbcMapper maps database columns directly rather than transforming a Java object graph. It can also prepare reusable, stateless JdbcRowMapper<T> instances from ResultSetMetaData. See the feature guides for the operation-specific APIs and examples.

Getting Started ​

For dependencies and annotation processor setup, see Installation.

Create and reuse instances ​

CompiledInstances.create(...) constructs a new instance of the generated implementation each time; it does not cache one for you. Applications may retain an instance, manage it through dependency injection, or declare a shared field on the interface:

java
@CompiledNavigator
interface UserNavigator {
    UserNavigator INSTANCE = CompiledInstances.create(UserNavigator.class);

    @GetByPath("$.address.city")
    String getCity(User user);
}

String city = UserNavigator.INSTANCE.getCity(user);

The factory also supports supplying a RuntimeContext; compiled binders may accept a preconfigured matching backend binder. See the corresponding feature guide for configuration details.

In Spring Framework 6.2+, sjf4j-spring registers generated interfaces via @EnableSjf4j. Spring Boot 3.x can use the Starter for the same behavior without extra configuration. Both support @Autowired instead of calling CompiledInstances.create(). See Spring Integration.

Inspect generated source ​

Generated Java uses the interface name with an _Impl suffix and appears in the normal annotation-processing output directory:

Build toolTypical generated source directory
Gradlebuild/generated/sources/annotationProcessor/java/main/
Maventarget/generated-sources/annotations/

Open the generated UserNavigator_Impl.java to inspect the actual code. It is regular Java source, so you can debug it with ordinary IDE tooling.

Runtime vs. Compiled ​

Choose the API style based on how much of the operation is known before execution:

Runtime APIsCompiled APIs
DefinitionSelected and configured at runtimeDeclared in annotated interfaces
Expressions and typesCan be dynamicMust satisfy static compilation rules
ExecutionGeneral-purpose structural processingSpecialized generated Java
SetupNo annotation processorAnnotation processing during the build
Best suited forDynamic or ad hoc operationsStable, frequently executed operations

Both operate on SJF4J's OBNT (Object-Based Node Tree), so adopting compiled APIs does not require adopting a separate Java object model.

Compilation limits and fallback ​

Not every runtime feature can be generated as direct Java code. Unsupported operations may produce compiler diagnostics rather than silently changing behavior.

Fallback is capability-specific, not a universal switch. For example:

  • @CompiledNavigator(fallback = true) permits runtime evaluation for certain @FindByPath filters.
  • @CompiledValidator(fallback = true) can delegate unsupported schema checks to the runtime SchemaPlan; its default is false, which rejects unsupported constructs during compilation.

These options do not mean every dynamic expression or conversion can be compiled or automatically delegated. Consult the relevant feature guide when deciding between runtime execution and generated code.

Performance ​

Compiled APIs generate specialized Java code to reduce runtime overhead for supported operations. Results vary by workload; see Benchmarks for measurements and methodology.

API Reference (latest release): CompiledInstances · @CompiledNavigator · @CompiledMapper · @CompiledValidator

Released under the MIT License.