Skip to content

codegen.adoc

Latest commit

 

History

History
193 lines (149 loc) · 5.63 KB

codegen.adoc

File metadata and controls

193 lines (149 loc) · 5.63 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-sonatype}.

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 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 or org.pkl.codegen.java.JavaRecordCodeGenerator, 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-records

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

--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/pkl-examples repository.