Skip to main content

Spring Boot plugin

See also Plugins for the existing Genesis Gradle plugins, and Getting Started with Spring for the server-side modules this build tooling supports. Everything in that section depends on a module having applied the plugin described here.

Starter artifactAddsDocumented on
genesis-spring-boot-starterGuice bridge, system-definition config, HTTP session-token authenticationApplication core
genesis-eventhandler-spring-boot-starterAnnotation-driven event handlersCore business logic (Spring)
genesis-data-spring-boot-starterSpring Data JPA over the existing DbLayerData access APIs (JPA)
genesis-data-cube-spring-boot-starterPivot, grouped and flat cube queries over JPA entitiesCube Query Engine
genesis-spring-testsupportJUnit 6 (JUnit Jupiter) support for Spring-based Genesis applicationsTesting API (Spring)

Genesis Spring Boot plugin​

note

Spring integration ships with Genesis Application Platform v10. Make sure your project is on that version (or later) before applying the plugin. Check server/gradle.properties and make sure genesisVersion and authVersion are set to 10.0.0 (or later) — bump them if the generated project seeded an older version.

The Genesis Spring Boot plugin (global.genesis.spring) is the build-time entry point for Genesis's Spring Boot/JPA application style. Applying it to a module provides:

  • Legacy process and service manifest generation for classes annotated @GenesisApplication, so a Spring Boot process shows up in Genesis tooling (process manager, launcher) exactly like a .kts-defined one.
  • JPA entity, repository and enum code generation from your project's existing Genesis dictionary and view definitions, so a Spring Data JPA layer can be built directly on top of tables and views you've already defined.
  • Automatic KSP wiring to scan your compiled classes for the @GenesisApplication annotation — no separate KSP setup is required in the consuming module.

Unlike the core Genesis Build plugin, which the Genesis Gradle Settings plugin applies to every module automatically, the Spring Boot plugin is opt-in: a module must add id("global.genesis.spring") itself to use it. Modules that don't write Spring/JPA code don't need it and won't have it applied for them.

How to enable?​

Applying the plugin requires the settings.gradle.kts of the Gradle build that contains the module (in a genx layout, server/settings.gradle.kts) to already have Genesis's global.genesis.settings plugin applied — the same one that manages global.genesis.build. That's because global.genesis.spring is a version-managed plugin id, and it only resolves without an explicit version string through that mechanism. A genx-generated project already has global.genesis.settings applied, so this is only a concern for a manually-created or restructured build. With that in place, add the plugin to the module's own build.gradle.kts:

// build.gradle.kts
plugins {
id("global.genesis.spring")
}

The generated JPA entities and repositories are always Kotlin, regardless of what language the rest of the module is written in. The Genesis Settings plugin applies the Kotlin JVM plugin (kotlin("jvm")) to every module, so a consuming module's own plugin block doesn't need to declare it. global.genesis.spring applies Kotlin's Spring compiler plugin (kotlin("plugin.spring")), which makes Kotlin classes annotated @Component, @Service, @Configuration, @Transactional and similar open automatically, so they don't need to be marked open for Spring's proxies. JPA entities are not covered by it; they still rely on kotlin("plugin.jpa"). The process/service manifest generation works the same whether your @GenesisApplication classes are written in Kotlin or Java.

For example, this class needs no open modifiers:

import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
class OrderService {
@Transactional
fun placeOrder() { /* ... */ }
}
tip

To confirm Spring created a proxy for a class like this, inject the bean in a @GenesisSpringTest (not a bare @SpringBootTest) that contributes it with @Import(OrderService::class), and inspect orderService.javaClass.name. A CGLIB proxy class name, containing $$SpringCGLIB$$, confirms the plugin applied. See Testing API (Spring).

Applying the plugin doesn't pull Spring Boot in for you: no Spring Boot dependency needs to be present to apply global.genesis.spring itself, and the Spring Boot starter modules a module needs are added by the consuming module independently, for runtime concerns the plugin doesn't touch.

Applying the plugin creates a genesisSpring { ... } extension with two nested extensions, processes {} and entities {}:

genesisSpring {
processes {
defaultOptions = "-Xmx1024m -DXSD_VALIDATE=false"
portOffset = 11050
}
entities {
packageName = "com.example.myapp.jpa"
sourceSetName = "main"
dictionaryModuleSuffix = "-dictionary-cache"
}
}

Neither nested extension needs to be configured to get useful defaults — see below.

Dependency versions​

You don't set a version on any global.genesis:* Spring artifact yourself. A Genesis project applies the Genesis Gradle Settings plugin, which contributes the Genesis BOM as a platform dependency — see Plugins for that mechanism — and the BOM is what pins the version every global.genesis:* Spring dependency resolves to. For example:

dependencies {
implementation("global.genesis:genesis-spring-boot-starter")
}

To see which version the BOM actually pins for a given dependency, run ./gradlew <module>:dependencies (or ./gradlew <module>:dependencyInsight --dependency <artifact>) and inspect the resolved version.

Processes and service manifest generation​

If a module declares any @GenesisApplication-annotated classes, the plugin's KSP processor scans for them during compilation and the generateGenesisSpringProcessesXml task writes <product>-<module>-processes.xml and <product>-<module>-service-definitions.xml, where <module> is the module name without its <product>- prefix (for a module named myapp-spring, myapp-spring-processes.xml) — the same legacy configuration format the GPAL/dictionary world uses. No extra DSL configuration is required: it runs automatically whenever matching classes are found, and writes nothing if none are.

The processes {} extension only needs touching when a module wants different defaults from the ones Genesis normally uses:

PropertyDefaultDescription
defaultOptions"-Xmx1024m -DXSD_VALIDATE=false"JVM options written into the generated <process> entry, unless the @GenesisApplication annotation supplies its own.
portOffset11050Base port for generated <service> entries. Each process's port is portOffset plus either the port the annotation specifies, or the process's position in declaration order.

A module that only wants to change these defaults configures processes {} alone. JPA entity generation still runs with its defaults, as described below:

// build.gradle.kts
plugins {
id("global.genesis.spring")
}

genesisSpring {
processes {
defaultOptions = "-Xmx2048m -DXSD_VALIDATE=false"
portOffset = 12000
}
}

JPA entity generation​

The entities {} extension controls the generateJpaEntities task, which reads the merged Genesis dictionary and view definitions out of sibling modules and generates @Entity, repository and enum Kotlin sources from them. A companion generateAutoConfig task emits the Spring Boot AutoConfiguration.imports file that lets a consuming application auto-discover the generated JPA configuration.

A minimal configuration only needs packageName; every other property is derived from it:

// build.gradle.kts
plugins {
id("global.genesis.spring")
}

genesisSpring {
entities {
packageName = "com.example.myapp.jpa"
}
}

Running ./gradlew generateJpaEntities in the module that applies the plugin reads the dictionary from a sibling module (by default, any subproject whose name ends -dictionary-cache) and writes generated sources under build/generated/genesis-jpa/. Both the generated entities and the auto-configuration output are attached to the module's main Kotlin source set, so they compile as part of the module and land on its classpath with no further wiring.

Generation runs as part of an ordinary build; invoking generateJpaEntities directly is only needed to regenerate the sources on demand.

note

Tables with a mutable primary key — one whose value can change after a row is created — aren't eligible for entity generation, since JPA doesn't support that. A table whose primary key includes the TIMESTAMP field is one of these. generateJpaEntities skips these tables with a warning rather than failing the build: a build with skipped tables still reports BUILD SUCCESSFUL. To see whether any tables were skipped, check the generateJpaEntities task's output for warnings such as <TABLE_NAME>: Unable to generate JPA entity for table; JPA does not support mutable primary keys.

Common configuration​

Every property below keys off packageName by default:

PropertyConvention defaultDescription
packageNameglobal.genesis.jpaBase package for all generated code.
entityPackageName$packageName.daoPackage for generated @Entity classes.
repoPackageName$packageName.repoPackage for generated repository interfaces.
enumPackageName$entityPackageName.enumsPackage for generated enums.
configClassPackageName$packageName.configPackage for the generated JpaConfiguration class.
dictionaryModuleSuffix-dictionary-cacheName suffix used to find sibling subprojects to generate entities from. Matching is by suffix against every subproject of the root project — there's no way to point at a dictionary module by path. The default *-dictionary-cache module is generated automatically by the Genesis Settings plugin from the project's merged dictionary, so it never appears as a declared subproject in settings.gradle.kts.
sourceSetNamemainWhich Kotlin source set the generated sources and auto-configuration resources are attached to.
useNullableRepotrueWhether generated repository methods return nullable types.

One of these deserves a closer look:

  • sourceSetName, set to "test", keeps generated entities out of the module's published jar entirely — the intended setting for a module whose dictionary is only a test fixture rather than something it ships. A name that doesn't match any real source set in the module silently generates into nothing, with no build error.

A dictionary that only exists to back a module's own tests sets it:

// build.gradle.kts
plugins {
id("global.genesis.spring")
kotlin("plugin.jpa")
}

genesisSpring {
entities {
dictionaryModuleSuffix = "paltest-dictionary-cache"
// This module has no main sources of its own — without this, its jar would be nothing
// but fixture entities plus an auto-configuration trigger that activates them in any consumer.
sourceSetName = "test"
}
}
tip

The plugin registers generateJpaEntities whether or not entities {} is configured, and the module's sourceSetName source set depends on it. If no subproject matches dictionaryModuleSuffix, generateJpaEntities has no dictionary to read and fails the build with unable to find dictionary in dictionaryFiles — check jpaGenerator configuration. A genx-generated project always has a -dictionary-cache module, so this only affects a restructured build. In a module that only needs the process/service manifest generation, set sourceSetName to a name that matches no source set, so no entities are generated.

H2 version pinning​

com.h2database:h2 is pinned strictly to a single version, to work around a check-constraint regression in H2 2.4.x. A module that needs a different H2 version has to override that pin explicitly — a plain version request won't displace it.

Overriding the pinned H2 version​

Because the pin uses strictly(), a consuming module can't simply declare a different com.h2database:h2 version and expect it to win — a strictly() constraint only loses to another strictly() declared at higher precedence, not to a plain version request or prefer(). To override it, declare your own strictly() constraint directly in the consuming module:

// build.gradle.kts
plugins {
id("global.genesis.spring")
}

genesisSpring {
entities {
packageName = "com.example.myapp.jpa"
}
}

dependencies {
constraints {
// Overrides the strictly() pin on com.h2database:h2 — a plain version
// request or prefer() here would not beat a strictly() constraint.
api("com.h2database:h2") {
version { strictly("2.5.0") }
}
}
}

This is standard Gradle rich-version-constraint behaviour, not something this plugin implements: a strictly() constraint a project declares for itself takes precedence over one it resolves from elsewhere. The same technique applies to any other dependency you need to move off the version it resolves to by default.