Usage

Let’s walk through an example for configuring a Spring Boot application with Pkl.

The source code for this example is available on GitHub. The equivalent Kotlin example is here.

For background information, see Externalized Configuration, in particular Type-safe Configuration Properties, in the Spring Boot documentation.

  1. Define a configuration schema in src/main/resources:

    AppConfig.pkl
    // this module name determines the package and
    // class name of the generated Java config class
    module samples.boot.AppConfig
    
    server: Server
    
    class Server {
      endpoints: Listing<Endpoint>
    }
    
    class Endpoint {
      name: String
      port: UInt16
    }
  2. Define an Application Property File next to the schema:

    application.pkl
    amends "modulepath:/appConfig.pkl"
    
    server {
      endpoints {
        new {
          name = "endpoint1"
          port = 1234
        }
        new {
          name = "endpoint2"
          port = 5678
        }
      }
    }
  3. Use Pkl’s Gradle plugin to generate Java config classes from the schema. Generated classes are placed in generated/configClasses/ and compiled together with your production code. To run the generator directly (which isn’t typically necessary), type ./gradlew configClasses.

    • Groovy

    • Kotlin

    build.gradle
    plugins {
      id "org.pkl-lang" version "$pklVersion"
    }
    
    pkl {
      javaCodeGenerators {
        configClasses {
          generateGetters.set(true)
          generateSpringBootConfig.set(true)
          sourceModules.set(files("src/main/resources/AppConfig.pkl"))
        }
      }
    }
    settings.gradle
    pluginManagement {
      repositories {
        mavenCentral()
      }
    }
    build.gradle.kts
    plugins {
      id("org.pkl-lang") version "$pklVersion"
    }
    
    pkl {
      javaCodeGenerators {
        register("configClasses") {
          generateGetters.set(true)
          generateSpringBootConfig.set(true)
          sourceModules.set(files("src/main/resources/AppConfig.pkl"))
        }
      }
    }
    settings.gradle.kts
    pluginManagement {
      repositories {
        mavenCentral()
      }
    }
  4. Annotate your Boot application class with @ConfigurationPropertiesScan. (Alternatively, explicitly list configuration classes with @EnableConfigurationProperties(…​).)

    @SpringBootApplication
    @ConfigurationPropertiesScan
    public class Application { ... }
  5. Inject the generated config classes into your application’s components as appropriate.

    @Service
    public class Server {
      public Server(AppConfig.Server config) { ... }
    }
  6. To get access to the entire configuration, inject the AppConfig class itself:

    @Service
    public class Server {
      public Server(AppConfig config) { ... }
    }

This example demonstrates one way of configuring Spring Boot applications with Pkl. Some possible deviations are:

  • Use multiple config files, for example one per environment.

  • Read config files from the file system instead of the class path.

  • Write config classes by hand instead of generating them.

  • Do not define a config schema. (Config classes cannot be generated in this case.)

  • Use a build tool other than Gradle.

    • Declare a build dependency on pkl-codegen-java.

    • Invoke the code generator’s main method during the build, passing the required arguments.

    • Configure the build to compile generated config classes together with your production code.

    • For more information, see the Java code generator docs.