Java Code Generator

The Java source code generator takes Pkl class definitions as an input, and generates corresponding Java classes with equally named properties.

The benefits of code generation are:

  • Configuration can be conveniently consumed as statically typed Java objects.

  • The entire configuration tree can be code-completed in Java IDEs.

  • Any drift between Java code and Pkl configuration structure is caught at compile time.

The generated classes are immutable and have component-wise implementations of equals(), hashCode(), and toString().

Installation

The code generator is offered as Gradle plugin, Java library, and CLI.

Gradle Plugin

See Installation in the Gradle plugin chapter.

Java Library

The pkl-codegen-java library is available from Maven Central. It requires Java 11 or higher.

Gradle

To use the library in a Gradle project, declare the following dependency:

  • Groovy

  • Kotlin

build.gradle
dependencies {
  compile "org.pkl-lang:pkl-codegen-java:0.25.3"
}

repositories {
  mavenCentral()
}
build.gradle.kts
dependencies {
  compile("org.pkl-lang:pkl-codegen-java:0.25.3")
}

repositories {
  mavenCentral()
}

Maven

To use the library in a Maven project, declare the following dependency:

pom.xml
<project>
  <dependency>
    <groupId>org.pkl-lang</groupId>
    <artifactId>pkl-codegen-java</artifactId>
    <version>0.25.3</version>
  </dependency>
</project>

CLI

The CLI is bundled with the Java library. As we do not currently ship the CLI as a self-contained Jar, we recommend to provision it with a Maven compatible build tool as shown in Java Library.

Usage

The code generator is offered as Gradle plugin, Java library, and CLI.

Gradle Plugin

See Java Code Generation in the Gradle plugin chapter.

Java Library

The Java library offers two APIs: a high-level API that corresponds to the CLI, and a lower-level API that provides additional features and control. The entry points for these APIs are org.pkl.codegen.java.CliJavaCodeGenerator and org.pkl.codegen.java.JavaCodeGenerator, respectively. For more information, refer to the Javadoc documentation.

CLI

As explained in Installation, the CLI is bundled with the Java library. To run the CLI, execute the library Jar or its org.pkl.codegen.java.Main main class.

Synopsis: java -cp <classpath> -jar pkl-codegen-java.jar [<options>] <modules>

<modules>

The absolute or relative URIs of the modules to generate classes for. Relative URIs are resolved against the working directory.

Options

--generate-getters

Default: (flag not set)
Flag that indicates to generate private final fields and public getter methods instead of public final fields.

--generate-javadoc

Default: (flag not set)
Flag that indicates to generate Javadoc based on doc comments for Pkl modules, classes, and properties.

--params-annotation

Default: org.pkl.config.java.mapper.Named
Fully qualified name of the annotation to use on constructor parameters.

--non-null-annotation

Default: org.pkl.config.java.mapper.NonNull
Fully qualified named of the annotation class to use for non-null types.
This annotation is required to have java.lang.annotation.ElementType.TYPE_USE as a @Target or it may generate code that does not compile.

--implement-serializable

Default: (flag not set)
Whether to make generated classes implement java.io.Serializable.

Common code generator options:

--indent

Default: " " (two spaces)
Example: "\t" (one tab)
The characters to use for indenting generated source code.

-o, --output-dir

Default: (not set)
Example: generated/
The directory where generated source code is placed. Relative paths are resolved against the working directory.

--generate-spring-boot

Default: (not set)
Flag that indicates to generate config classes for use with Spring Boot.

Common CLI options:

--allowed-modules

Default: pkl:,file:,modulepath:,https:,repl:,package:,projectpackage:
Comma-separated list of URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

--allowed-resources

Default: env:,prop:,package:,projectpackage:
Comma-separated list of URI patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URIs. At least one pattern needs to match for a resource to be readable.

--cache-dir

Default: ~/.pkl/cache
Example: /path/to/module/cache/
The cache directory for storing packages.

--no-cache

Disable cacheing of packages.

-e, --env-var

Default: OS environment variables for the current process
Example: MY_VAR=myValue
Sets an environment variable that can be read by Pkl code with read("env:<envVarName>"). Repeat this option to set multiple environment variables.

-h, --help

Display help information.

--module-path

Default: (empty)
Example: dir1:zip1.zip:jar1.jar
Directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Paths are separated by the platform-specific path separator (: on *nix, ; on Windows). Relative paths are resolved against the working directory.

-p, --property

Default: (none)
Example: myProp=myValue
Sets an external property that can be read by Pkl code with read("prop:<propertyName>"). Repeat this option to set multiple external properties.

--root-dir

Default: (none)
Example: /some/path
Root directory for file: modules and resources. If set, access to file-based modules and resources is restricted to those located under the specified root directory. Any symlinks are resolved before this check is performed.

--settings

Default: (none)
Example: mySettings.pkl
File path of the Pkl settings file to use. If not set, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

-t, --timeout

Default: (none)
Example: 30
Duration, in seconds, after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

-v, --version

Display version information.

-w, --working-dir

Base path that relative module paths passed as command-line arguments are resolved against. Defaults to the current working directory.

--ca-certificates

Default: (none)
Example: /some/path/certificates.pem
Path to a file containing CA certificates to be used for TLS connections.

Setting this option replaces the existing set of CA certificates bundled into the CLI. Certificates need to be X.509 certificates in PEM format.

For other methods of configuring certificates, see CA Certificates.

Full Example

For a ready-to-go example with full source code, see codegen-java in the pkl/pkl-examples repository.