Generate Java code from Daml¶
Introduction¶
When writing applications for the ledger in Java, you want to work with a representation of Daml templates and data types in Java that closely resemble the original Daml code while still being as true to the native types in Java as possible. To achieve this, you can use Daml to Java code generator (“Java codegen”) to generate Java types based on a Daml model. You can then use these types in your Java code when reading information from and sending data to the ledger.
The Daml assistant documentation describes how to run and configure the code generator for all supported bindings, including Java.
The rest of this page describes Java-specific topics.
Understand the generated Java model¶
The Java codegen generates source files in a directory tree under the output directory specified on the command line.
Map Daml primitives to Java types¶
Daml built-in types are translated to the following equivalent types in Java:
Daml type | Java type | Java Bindings Value Type |
---|---|---|
Int |
java.lang.Long |
Int64 |
Numeric |
java.math.BigDecimal |
Numeric |
Text |
java.lang.String |
Text |
Bool |
java.util.Boolean |
Bool |
Party |
java.lang.String |
Party |
Date |
java.time.LocalDate |
Date |
Time |
java.time.Instant |
Timestamp |
List or [] |
java.util.List |
DamlList |
TextMap |
java.util.Map
Restricted to using String keys. |
DamlTextMap |
Optional |
java.util.Optional |
DamlOptional |
() (Unit) |
None since the Java language doesn’t
have a direct equivalent of Daml’s Unit
type () , the generated code uses the
Java Bindings value type. |
Unit |
ContractId |
Fields of type ContractId X refer to
the generated ContractId class of the
respective template X . |
ContractId |
Understand escaping rules¶
To avoid clashes with Java keywords, the Java codegen applies escaping rules to the following Daml identifiers:
- Type names (except the already mapped built-in types)
- Constructor names
- Type parameters
- Module names
- Field names
If any of these identifiers match one of the Java reserved keywords, the Java codegen appends a dollar sign $
to the name. For example, a field with the name import
will be generated as a Java field with the name import$
.
Understand the generated classes¶
Every user-defined data type in Daml (template, record, and variant) is represented by one or more Java classes as described in this section.
The Java package for the generated classes is the equivalent of the lowercase Daml module name.
module Foo.Bar.Baz where
package foo.bar.baz;
Records (a.k.a product types)¶
A Daml record is represented by a Java class with fields that have the same name as the Daml record fields. A Daml field having the type of another record is represented as a field having the type of the generated class for that record.
module Com.Acme.ProductTypes where
data Person = Person with name : Name; age : Decimal
data Name = Name with firstName : Text; lastName : Text
A Java file is generated that defines the class for the type Person
:
package com.acme.producttypes;
public class Person {
public final Name name;
public final BigDecimal age;
public static Person fromValue(Value value$) { /* ... */ }
public Person(Name name, BigDecimal age) { /* ... */ }
public DamlRecord toValue() { /* ... */ }
}
A Java file is generated that defines the class for the type Name
:
package com.acme.producttypes; public class Name { public final String firstName; public final String lastName; public static Person fromValue(Value value$) { /* ... */ } public Name(String firstName, String lastName) { /* ... */ } public DamlRecord toValue() { /* ... */ } }
Templates¶
The Java codegen generates three classes for a Daml template:
- TemplateName
- Represents the contract data or the template fields.
- TemplateName.ContractId
- Used whenever a contract ID of the corresponding template is used in another template or record, for example:
data Foo = Foo (ContractId Bar)
. This class also provides methods to generate anExerciseCommand
for each choice that can be sent to the ledger with the Java Bindings.- TemplateName.Contract
- Represents an actual contract on the ledger. It contains a field for the contract ID (of type
TemplateName.ContractId
) and a field for the template data (of typeTemplateName
). With the static methodTemplateName.Contract.fromCreatedEvent
, you can deserialize a CreatedEvent to an instance ofTemplateName.Contract
.module Com.Acme.Templates where data BarKey = BarKey with p : Party t : Text template Bar with owner: Party name: Text where signatory owner key BarKey owner name : BarKey maintainer key.p choice Bar_SomeChoice: Bool with aName: Text controller owner do return True
A file is generated that defines three Java classes:
Bar
Bar.ContractId
Bar.Contract
package com.acme.templates;
public class Bar extends Template {
public static final Identifier TEMPLATE_ID = new Identifier("some-package-id", "Com.Acme.Templates", "Bar");
public final String owner;
public final String name;
public static ExerciseByKeyCommand exerciseByKeyBar_SomeChoice(BarKey key, Bar_SomeChoice arg) { /* ... */ }
public static ExerciseByKeyCommand exerciseByKeyBar_SomeChoice(BarKey key, String aName) { /* ... */ }
public CreateAndExerciseCommand createAndExerciseBar_SomeChoice(Bar_SomeChoice arg) { /* ... */ }
public CreateAndExerciseCommand createAndExerciseBar_SomeChoice(String aName) { /* ... */ }
public static class ContractId {
public final String contractId;
public ExerciseCommand exerciseArchive(Unit arg) { /* ... */ }
public ExerciseCommand exerciseBar_SomeChoice(Bar_SomeChoice arg) { /* ... */ }
public ExerciseCommand exerciseBar_SomeChoice(String aName) { /* ... */ }
}
public static class Contract {
public final ContractId id;
public final Bar data;
public static Contract fromCreatedEvent(CreatedEvent event) { /* ... */ }
}
}
Note that the static methods returning an ExerciseByKeyCommand
will only be generated for templates that define a key.
Variants (a.k.a sum types)¶
A variant or sum type is a type with multiple constructors, where each constructor wraps a value of another type. The generated code is comprised of an abstract class for the variant type itself and a subclass thereof for each constructor. Classes for variant constructors are similar to classes for records.
module Com.Acme.Variants where
data BookAttribute = Pages Int
| Authors [Text]
| Title Text
| Published with year: Int; publisher: Text
The Java code generated for this variant is:
package com.acme.variants;
public class BookAttribute {
public static BookAttribute fromValue(Value value) { /* ... */ }
public static BookAttribute fromValue(Value value) { /* ... */ }
public Value toValue() { /* ... */ }
}
package com.acme.variants.bookattribute;
public class Pages extends BookAttribute {
public final Long longValue;
public static Pages fromValue(Value value) { /* ... */ }
public Pages(Long longValue) { /* ... */ }
public Value toValue() { /* ... */ }
}
package com.acme.variants.bookattribute;
public class Authors extends BookAttribute {
public final List<String> listValue;
public static Authors fromValue(Value value) { /* ... */ }
public Author(List<String> listValue) { /* ... */ }
public Value toValue() { /* ... */ }
}
package com.acme.variants.bookattribute;
public class Title extends BookAttribute {
public final String stringValue;
public static Title fromValue(Value value) { /* ... */ }
public Title(String stringValue) { /* ... */ }
public Value toValue() { /* ... */ }
}
package com.acme.variants.bookattribute;
public class Published extends BookAttribute {
public final Long year;
public final String publisher;
public static Published fromValue(Value value) { /* ... */ }
public Published(Long year, String publisher) { /* ... */ }
public DamlRecord toValue() { /* ... */ }
}
Parameterized types¶
Note
This section is only included for completeness: we don’t expect users to make use of the fromValue
and toValue
methods, because they would typically come from a template that doesn’t have any unbound type parameters.
The Java codegen uses Java Generic types to represent Daml parameterized types.
This Daml fragment defines the parameterized type Attribute
, used by the BookAttribute
type for modeling the characteristics of the book:
module Com.Acme.ParameterizedTypes where
data Attribute a = Attribute
with v : a
data BookAttributes = BookAttributes with
pages : (Attribute Int)
authors : (Attribute [Text])
title : (Attribute Text)
The Java codegen generates a Java file with a generic class for the Attribute a
data type:
package com.acme.parametrizedtypes;
public class Attribute<a> {
public final a value;
public Attribute(a value) { /* ... */ }
public DamlRecord toValue(Function<a, Value> toValuea) { /* ... */ }
public static <a> Attribute<a> fromValue(Value value$, Function<Value, a> fromValuea) { /* ... */ }
}
Enums¶
An enum type is a simplified sum type with multiple constructors but without argument nor type parameters. The generated code is standard java Enum whose constants map enum type constructors.
module Com.Acme.Enum where
data Color = Red | Blue | Green
The Java code generated for this variant is:
package com.acme.enum;
public enum Color {
RED,
GREEN,
BLUE;
/* ... */
public static final Color fromValue(Value value$) { /* ... */ }
public final DamlEnum toValue() { /* ... */ }
}
package com.acme.enum.bookattribute;
public class Authors extends BookAttribute {
public final List<String> listValue;
public static Authors fromValue(Value value) { /* ... */ }
public Author(List<String> listValue) { /* ... */ }
public Value toValue() { /* ... */ }
}
Convert a value of a generated type to a Java Bindings value¶
To convert an instance of the generic type Attribute<a>
to a Java Bindings Value, call the toValue
method and pass a function as the toValuea
argument for converting the field of type a
to the respective Java Bindings Value. The name of the parameter consists of toValue
and the name of the type parameter, in this case a
, to form the name toValuea
.
Below is a Java fragment that converts an attribute with a java.lang.Long
value to the Java Bindings representation using the method reference Int64::new
.
Attribute<Long> pagesAttribute = new Attributes<>(42L);
Value serializedPages = pagesAttribute.toValue(Int64::new);
See Daml To Java Type Mapping for an overview of the Java Bindings Value types.
Note: If the Daml type is a record or variant with more than one type parameter, you need to pass a conversion function to the toValue
method for each type parameter.
Create a value of a generated type from a Java Bindings value¶
Analogous to the toValue
method, to create a value of a generated type, call the method fromValue
and pass conversion functions from a Java Bindings Value type to the expected Java type.
Attribute<Long> pagesAttribute = Attribute.<Long>fromValue(serializedPages,
f -> f.asInt64().getOrElseThrow(() -> throw new IllegalArgumentException("Expected Int field").getValue());
See Java Bindings Value class for the methods to transform the Java Bindings types into corresponding Java types.
Non-exposed parameterized types¶
If the parameterized type is contained in a type where the actual type is specified (as in the BookAttributes
type above), then the conversion methods of the enclosing type provides the required conversion function parameters automatically.
Convert Optional values¶
The conversion of the Java Optional
requires two steps. The
Optional
must be mapped in order to convert its contains before
to be passed to DamlOptional::of
function.
Attribute<Optional<Long>> idAttribute = new Attribute<List<Long>>(Optional.of(42));
val serializedId = DamlOptional.of(idAttribute.map(Int64::new));
To convert back DamlOptional to Java Optional
, one must use the
containers method toOptional
. This method expects a function to
convert back the value possibly contains in the container.
Attribute<Optional<Long>> idAttribute2 =
serializedId.toOptional(v -> v.asInt64().orElseThrow(() -> new IllegalArgumentException("Expected Int64 element")));
Convert Collection values¶
DamlCollectors provides collectors to converted Java collection
containers such as List
and Map
to DamlValues in one pass. The
builders for those collectors require functions to convert the element
of the container.
Attribute<List<String>> authorsAttribute =
new Attribute<List<String>>(Arrays.asList("Homer", "Ovid", "Vergil"));
Value serializedAuthors =
authorsAttribute.toValue(f -> f.stream().collect(DamlCollector.toList(Text::new));
To convert back Daml containers to Java ones, one must use the
containers methods toList
or toMap
. Those methods expect
functions to convert back the container’s entries.
Attribute<List<String>> authorsAttribute2 =
Attribute.<List<String>>fromValue(
serializedAuthors,
f0 -> f0.asList().orElseThrow(() -> new IllegalArgumentException("Expected DamlList field"))
.toList(
f1 -> f1.asText().orElseThrow(() -> new IllegalArgumentException("Expected Text element"))
.getValue()
)
);
Daml Interfaces¶
From this daml definition:
module Interfaces where
interface TIf where
getOwner: Party
dup: Update (ContractId TIf)
choice Ham: ContractId TIf with
controller getOwner this
do dup this
choice Useless: ContractId TIf with
interfacely: ContractId TIf
controller getOwner this
do
dup this
template Child
with
party: Party
where
signatory party
choice Bar: () with
controller party
do
return ()
implements TIf where
getOwner = party
dup = toInterfaceContractId <$> create this
The generated file for the interface definition can be seen below. Effectively it is a class that contains only the inner type ContractId because one will always only be able to deal with Interfaces via their ContractId.
package interfaces
/* imports */
public final class TIf {
public static final Identifier TEMPLATE_ID = new Identifier("94fb4fa48cef1ec7d474ff3d6883a00b2f337666c302ec5e2b87e986da5c27a3", "Interfaces", "TIf");
public static final class ContractId extends com.daml.ledger.javaapi.data.codegen.ContractId<TIf> {
public ContractId(String contractId) { /* ... */ }
public ExerciseCommand exerciseUseless(Useless arg) { /* ... */ }
public ExerciseCommand exerciseHam(Ham arg) { /* ... */ }
}
}
For templates the code generation will be slightly different if a template implements interfaces. Main difference here is that the choices from inherited interfaces are included in the class declaration. Moreover to allow converting the ContractId of a template to an interface ContractId, an additional conversion method called toInterfaceName is generated.
package interfaces
/* ... */
public final class Child extends Template {
/* ... */
public CreateAndExerciseCommand createAndExerciseHam(Ham arg) { /* ... */ }
public CreateAndExerciseCommand createAndExerciseHam() { /* ... */ }
public CreateAndExerciseCommand createAndExerciseUseless(Useless arg) { /* ... */ }
public CreateAndExerciseCommand createAndExerciseUseless(TIf.ContractId interfacely) { /* ... */ }
/* ... */
public static final class ContractId extends com.daml.ledger.javaapi.data.codegen.ContractId<Child> {
/* ... */
public ExerciseCommand exerciseHam(Ham arg) { /* ... */ }
public ExerciseCommand exerciseUseless(Useless arg) { /* ... */ }
public ExerciseCommand exerciseHam() { /* ... */ }
public ExerciseCommand exerciseUseless(TIf.ContractId interfacely) { /* ... */ }
public TIf.ContractId toTIf() { /* ... */ }
}
/* ... */
}