Skip to content

codegen.adoc

Latest commit

 

History

History
245 lines (192 loc) · 6.52 KB

codegen.adoc

File metadata and controls

245 lines (192 loc) · 6.52 KB

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(), or can optionally be produced as Java Records, in case of generateRecords=true, delivering the same benefits.

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 {uri-maven-docsite}/artifact/org.pkl-lang/pkl-codegen-java[from Maven Central]. It requires Java 17 or higher.

Note
 Snapshots are published to repository {uri-snapshot-repo}.

Gradle

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

Kotlin
build.gradle.kts
dependencies {
  implementation("org.pkl-lang:pkl-codegen-java:{pkl-artifact-version}")
}

repositories {
  maven(url = "{uri-sonatype}")
}
Groovy
build.gradle
dependencies {
  implementation "org.pkl-lang:pkl-codegen-java:{pkl-artifact-version}"
}

repositories {
  maven { url "{uri-sonatype}" }
}

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>{pkl-artifact-version}</version>
  </dependency>
  <repositories>
    <repository>
      <id>sonatype-s01</id>
      <name>Sonatype S01</name>
      <url>{uri-sonatype}</url>
    </repository>
  </repositories>
</project>

CLI

The CLI is available as a Java executable.

It works on multiple platforms, and requires a Java 17 (or higher) runtime on the system path.

To download:

macOS/Linux
curl -L -o pkl-codegen-java '{uri-sonatype-snapshot-download}&a=pkl-cli-codegen-java&e=jar'
chmod +x pkl-codegen-java
./pkl-codegen-java --version
Windows
Invoke-WebRequest '{uri-sonatype-snapshot-download}&a=pkl-cli-codegen-java&e=jar' -OutFile pkl-codegen-java.bat
.\pkl-codegen-java --version

This should print something similar to:

pkl-codegen-java {pkl-version} (macOS 14.2, Java 17.0.10)

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 or org.pkl.codegen.java.JavaRecordCodeGenerator, respectively. For more information, refer to the Javadoc documentation.

CLI

Synopsis: pkl-codegen-java [<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-records

Default: (flag not set)
Flag that indicates to generate Java records and the related interfaces.
Overrides Java class generation option --generate-getters.

--use-withers

Default: (flag not set)
Flag that indicates whether to generate JEP 468 like withers for Java records.
Works in conjunction with Java records class generation option -generate-records.

--use-lombok-builders

Default: (flag not set)
Flag that indicates whether to generate Lombok Builders for Java records.
Works in conjunction with Java records class generation option -generate-records.

--generate-javadoc

Default: (flag not set)
Flag that indicates to preserve Pkl doc comments by generating corresponding Javadoc comments.

--params-annotation

Default: none if --generate-spring-boot is set, org.pkl.config.java.mapper.Named otherwise
Fully qualified name of the annotation type to use for annotating constructor parameters with their name.
The specified annotation type must have a value parameter of type String or the generated code may not compile. If set to none, constructor parameters are not annotated. Whether and how constructor parameters should be annotated depends on the library that instantiates the generated classes. For Spring Boot applications, and for users of pkl-config-java compiling the generated classes with -parameters, no annotation is required.

--non-null-annotation

Default: org.pkl.config.java.mapper.NonNull
Fully qualified name of the annotation type to use for annotating non-null types.
The specified annotation type must be annotated with @java.lang.annotation.Target(ElementType.TYPE_USE) or the generated code may not compile.

Common code generator options:

Common CLI options:

Full Example

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