digital-asset · S11001001 · May 6, 2022 · Apr 27, 2022 · Apr 27, 2022 · Apr 27, 2022
diff --git a/docs/source/app-dev/bindings-java/codegen.rst b/docs/source/app-dev/bindings-java/codegen.rst
@@ -171,14 +171,18 @@ A file is generated that defines three Java classes:
 
 .. code-block:: java
   :caption: com/acme/templates/Bar.java
-  :emphasize-lines: 3,14,24
+  :emphasize-lines: 3,22,33
 
   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 static final ContractCompanion.WithKey<Contract, ContractId, Bar, BarKey> COMPANION = 
+        new ContractCompanion.WithKey<>("com.acme.templates.Bar",
+          TEMPLATE_ID, ContractId::new, Bar::fromValue, Contract::new, e -> BarKey.fromValue(e));
+
     public final String owner;
     public final String name;
 
@@ -190,7 +194,8 @@ A file is generated that defines three Java classes:
 
     public CreateAndExerciseCommand createAndExerciseBar_SomeChoice(String aName) { /* ... */ }
 
-    public static class ContractId {
+    public static class ContractId extends com.daml.ledger.javaapi.data.codegen.ContractId<Bar> {
+      // inherited:
       public final String contractId;
 
       public ExerciseCommand exerciseArchive(Unit arg) { /* ... */ }
@@ -200,7 +205,8 @@ A file is generated that defines three Java classes:
       public ExerciseCommand exerciseBar_SomeChoice(String aName) { /* ... */ }
     }
 
-    public static class Contract {
+    public static class Contract extends ContractWithKey<ContractId, Bar, BarKey> {
+      // inherited:
       public final ContractId id;
       public final Bar data;
 

diff --git a/...ge-support/java/bindings/src/main/java/com/daml/ledger/javaapi/data/codegen/Contract.java b/...ge-support/java/bindings/src/main/java/com/daml/ledger/javaapi/data/codegen/Contract.java
@@ -0,0 +1,80 @@
+// Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package com.daml.ledger.javaapi.data.codegen;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+
+/**
+ * A superclass for all codegen-generated Contracts.
+ *
+ * @param <Id> The generated contract ID class alongside the generated Contract class.
+ * @param <Data> The containing template's associated record type.
+ */
+public abstract class Contract<Id, Data> implements com.daml.ledger.javaapi.data.Contract {
+  public final Id id;
+
+  public final Data data;
+
+  public final Optional<String> agreementText;
+
+  public final Set<String> signatories;
+
+  public final Set<String> observers;
+
+  protected Contract(
+      Id id,
+      Data data,
+      Optional<String> agreementText,
+      Set<String> signatories,
+      Set<String> observers) {
+    this.id = id;
+    this.data = data;
+    this.agreementText = agreementText;
+    this.signatories = signatories;
+    this.observers = observers;
+  }
+
+  // concrete 1st type param would need a self-reference type param in Contract
+  protected abstract ContractCompanion<? extends Contract<Id, Data>, Id, Data> getCompanion();
+
+  @Override
+  public boolean equals(Object object) {
+    if (this == object) {
+      return true;
+    }
+    if (object == null) {
+      return false;
+    }
+    if (!(object instanceof Contract)) {
+      return false;
+    }
+    Contract<?, ?> other = (Contract<?, ?>) object;
+    // a bespoke Contract-specific equals is unneeded, as 'data' here
+    // already compares the associated record types' classes
+    return this.id.equals(other.id)
+        && this.data.equals(other.data)
+        && this.agreementText.equals(other.agreementText)
+        && this.signatories.equals(other.signatories)
+        && this.observers.equals(other.observers);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(this.id, this.data, this.agreementText, this.signatories, this.observers);
+  }
+
+  @Override
+  public String toString() {
+    return String.format(
+        "%s.Contract(%s, %s, %s, %s, %s)",
+        getCompanion().templateClassName,
+        this.id,
+        this.data,
+        this.agreementText,
+        this.signatories,
+        this.observers);
+  }
+}
diff --git a/...t/java/bindings/src/main/java/com/daml/ledger/javaapi/data/codegen/ContractCompanion.java b/...t/java/bindings/src/main/java/com/daml/ledger/javaapi/data/codegen/ContractCompanion.java
@@ -0,0 +1,155 @@
+// Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package com.daml.ledger.javaapi.data.codegen;
+
+import com.daml.ledger.javaapi.data.CreatedEvent;
+import com.daml.ledger.javaapi.data.DamlRecord;
+import com.daml.ledger.javaapi.data.Identifier;
+import com.daml.ledger.javaapi.data.Value;
+import java.util.Collections;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Function;
+
+public abstract class ContractCompanion<Ct, Id, Data> {
+  public final Identifier TEMPLATE_ID;
+  final String templateClassName; // not something we want outside this package
+
+  protected final Function<String, Id> newContractId;
+  protected final Function<DamlRecord, Data> fromValue;
+
+  public abstract Ct fromCreatedEvent(CreatedEvent event);
+
+  protected ContractCompanion(
+      String templateClassName,
+      Identifier templateId,
+      Function<String, Id> newContractId,
+      Function<DamlRecord, Data> fromValue) {
+    this.TEMPLATE_ID = templateId;
+    this.templateClassName = templateClassName;
+    this.newContractId = newContractId;
+    this.fromValue = fromValue;
+  }
+
+  public static final class WithoutKey<Ct, Id, Data> extends ContractCompanion<Ct, Id, Data> {
+    private final NewContract<Ct, Id, Data> newContract;
+
+    public WithoutKey(
+        String templateClassName,
+        Identifier templateId,
+        Function<String, Id> newContractId,
+        Function<DamlRecord, Data> fromValue,
+        NewContract<Ct, Id, Data> newContract) {
+      super(templateClassName, templateId, newContractId, fromValue);
+      this.newContract = newContract;
+    }
+
+    public Ct fromIdAndRecord(
+        String contractId,
+        DamlRecord record$,
+        Optional<String> agreementText,
+        Set<String> signatories,
+        Set<String> observers) {
+      Id id = newContractId.apply(contractId);
+      Data data = fromValue.apply(record$);
+      return newContract.newContract(id, data, agreementText, signatories, observers);
+    }
+
+    /**
+     * @deprecated since introduction; only exists to support generated method that has itself been
+     *     deprecated since v0.12.18
+     */
+    @Deprecated
+    public Ct fromIdAndRecord(String contractId, DamlRecord record$) {
+      return fromIdAndRecord(
+          contractId, record$, Optional.empty(), Collections.emptySet(), Collections.emptySet());
+    }
+
+    @Override
+    public Ct fromCreatedEvent(CreatedEvent event) {
+      return fromIdAndRecord(
+          event.getContractId(),
+          event.getArguments(),
+          event.getAgreementText(),
+          event.getSignatories(),
+          event.getObservers());
+    }
+
+    @FunctionalInterface
+    public interface NewContract<Ct, Id, Data> {
+      Ct newContract(
+          Id id,
+          Data data,
+          Optional<String> agreementText,
+          Set<String> signatories,
+          Set<String> observers);
+    }
+  }
+
+  public static final class WithKey<Ct, Id, Data, Key> extends ContractCompanion<Ct, Id, Data> {
+    private final NewContract<Ct, Id, Data, Key> newContract;
+    private final Function<Value, Key> keyFromValue;
+
+    public WithKey(
+        String templateClassName,
+        Identifier templateId,
+        Function<String, Id> newContractId,
+        Function<DamlRecord, Data> fromValue,
+        NewContract<Ct, Id, Data, Key> newContract,
+        Function<Value, Key> keyFromValue) {
+      super(templateClassName, templateId, newContractId, fromValue);
+      this.newContract = newContract;
+      this.keyFromValue = keyFromValue;
+    }
+
+    public Ct fromIdAndRecord(
+        String contractId,
+        DamlRecord record$,
+        Optional<String> agreementText,
+        Optional<Key> key,
+        Set<String> signatories,
+        Set<String> observers) {
+      Id id = newContractId.apply(contractId);
+      Data data = fromValue.apply(record$);
+      return newContract.newContract(id, data, agreementText, key, signatories, observers);
+    }
+
+    /**
+     * @deprecated since introduction; only exists to support generated method that has itself been
+     *     deprecated since v0.12.18
+     */
+    @Deprecated
+    public Ct fromIdAndRecord(String contractId, DamlRecord record$) {
+      return fromIdAndRecord(
+          contractId,
+          record$,
+          Optional.empty(),
+          Optional.empty(),
+          Collections.emptySet(),
+          Collections.emptySet());
+    }
+
+    @Override
+    public Ct fromCreatedEvent(CreatedEvent event) {
+      return fromIdAndRecord(
+          event.getContractId(),
+          event.getArguments(),
+          event.getAgreementText(),
+          event.getContractKey().map(keyFromValue),
+          event.getSignatories(),
+          event.getObservers());
+    }
+
+    @FunctionalInterface
+    public interface NewContract<Ct, Id, Data, Key> {
+      Ct newContract(
+          Id id,
+          Data data,
+          Optional<String> agreementText,
+          Optional<Key> key,
+          Set<String> signatories,
+          Set<String> observers);
+    }
+  }
+}
diff --git a/...ort/java/bindings/src/main/java/com/daml/ledger/javaapi/data/codegen/ContractWithKey.java b/...ort/java/bindings/src/main/java/com/daml/ledger/javaapi/data/codegen/ContractWithKey.java
@@ -0,0 +1,49 @@
+// Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package com.daml.ledger.javaapi.data.codegen;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+
+public abstract class ContractWithKey<Id, Data, Key> extends Contract<Id, Data> {
+  public final Optional<Key> key;
+
+  protected ContractWithKey(
+      Id id,
+      Data data,
+      Optional<String> agreementText,
+      Optional<Key> key,
+      Set<String> signatories,
+      Set<String> observers) {
+    super(id, data, agreementText, signatories, observers);
+    this.key = key;
+  }
+
+  @Override
+  public final boolean equals(Object object) {
+    return object instanceof ContractWithKey
+        && super.equals(object)
+        && this.key.equals(((ContractWithKey<?, ?, ?>) object).key);
+  }
+
+  @Override
+  public final int hashCode() {
+    return Objects.hash(
+        this.id, this.data, this.agreementText, this.key, this.signatories, this.observers);
+  }
+
+  @Override
+  public final String toString() {
+    return String.format(
+        "%s.Contract(%s, %s, %s, %s, %s, %s)",
+        getCompanion().templateClassName,
+        this.id,
+        this.data,
+        this.agreementText,
+        this.key,
+        this.signatories,
+        this.observers);
+  }
+}
diff --git a/language-support/java/codegen/src/it/java/com/daml/TemplateMethodTest.java b/language-support/java/codegen/src/it/java/com/daml/TemplateMethodTest.java
@@ -90,19 +90,20 @@ void contractHasFromIdAndRecord() {
         nonEmptyAgreement.agreementText, Optional.of("I agree"), "Unexpected agreementText");
   }
 
+  private static final CreatedEvent agreementEvent =
+      new CreatedEvent(
+          Collections.emptyList(),
+          "eventId",
+          SimpleTemplate.TEMPLATE_ID,
+          "cid",
+          simpleTemplateRecord,
+          Optional.of("I agree"),
+          Optional.empty(),
+          Collections.emptySet(),
+          Collections.emptySet());
+
   @Test
   void contractHasFromCreatedEvent() {
-    CreatedEvent agreementEvent =
-        new CreatedEvent(
-            Collections.emptyList(),
-            "eventId",
-            SimpleTemplate.TEMPLATE_ID,
-            "cid",
-            simpleTemplateRecord,
-            Optional.of("I agree"),
-            Optional.empty(),
-            Collections.emptySet(),
-            Collections.emptySet());
     CreatedEvent noAgreementEvent =
         new CreatedEvent(
             Collections.emptyList(),
@@ -123,4 +124,20 @@ void contractHasFromCreatedEvent() {
         SimpleTemplate.Contract.fromCreatedEvent(noAgreementEvent);
     assertFalse(withoutAgreement.agreementText.isPresent(), "AgreementText was present");
   }
+
+  @Test
+  void contractHasCompanion() {
+    var companion = SimpleTemplate.COMPANION;
+    SimpleTemplate.Contract withAgreement = companion.fromCreatedEvent(agreementEvent);
+    SimpleTemplate data = withAgreement.data;
+    assertEquals(new SimpleTemplate("Bob"), data);
+  }
+
+  @Test
+  void contractHasToString() {
+    assertEquals(
+        "tests.template1.SimpleTemplate.Contract(ContractId(cid), "
+            + "tests.template1.SimpleTemplate(Bob), Optional[I agree], [], [])",
+        SimpleTemplate.Contract.fromCreatedEvent(agreementEvent).toString());
+  }
 }