The Java bindings is a client implementation of the Ledger API based on RxJava, a library for composing asynchronous and event-based programs using observable sequences for the Java VM. It provides an idiomatic way to write Daml Ledger applications.
This documentation for the Java bindings API includes the JavaDoc reference documentation.
The Java bindings library is composed of:
- The Data Layer
A Java-idiomatic layer based on the Ledger API generated classes. This layer simplifies the code required to work with the Ledger API.
Can be found in the java package
- The Reactive Layer
A thin layer built on top of the Ledger API services generated classes.
For each Ledger API service, there is a reactive counterpart with a matching name. For instance, the reactive counterpart of
The Reactive Layer also exposes the main interface representing a client connecting via the Ledger API. This interface is called
LedgerClientand the main implementation working against a Daml Ledger is the
Can be found in the java package
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.
For more information on Java code generation, see Generate Java Code from Daml.
Connect to the Ledger:
Connections to the ledger are made by creating instance of classes that implement the interface
LedgerClient. The class
DamlLedgerClient implements this interface, and is used to connect to a Daml ledger.
This class provides access to the ledgerId, and all clients that give access to the various ledger services, such as the active contract set, the transaction service, the time service, etc. This is described below. Consult the JavaDoc for DamlLedgerClient for full details.
The Java bindings library can be added to a Maven project.
Set Up a Maven Project¶
To use the Java bindings library, add the following dependencies to your project’s
<dependencies> <dependency> <groupId>com.daml</groupId> <artifactId>bindings-rxjava</artifactId> <version>x.y.z</version> </dependency> </dependencies>
x.y.z for both dependencies with the version that you want to use. You can find the available versions by checking
the Maven Central Repository.
You can also take a look at the
pom.xml file from the quickstart project.
Connect to the Ledger¶
Before any ledger services can be accessed, you must establish a connection to the ledger by creating an instance of a
DamlLedgerClient. To create an instance of a ledger client, use the static
newBuilder(..) method to create a
DamlLedgerClient.Builder. Then use the builder instance to create the
DamlLedgerClient. Finally, call the
connect() method on the client.
// Create a client object to access services on the ledger. DamlLedgerClient client = DamlLedgerClient.newBuilder(ledgerhost, ledgerport).build(); // Connects to the ledger and runs initial validation. client.connect();
The Java bindings library lets you connect to a Daml Ledger via a secure connection. The builders created by
DamlLedgerClient.newBuilder default to a plaintext connection, but you can invoke
withSslContext to pass an
Using the default plaintext connection is useful only when connecting to a locally running Sandbox for development purposes.
Secure connections to a Daml Ledger must be configured to use client authentication certificates, which can be provided by a Ledger Operator.
For information on how to set up an
SslContext with the provided certificates for client authentication, please consult the gRPC documentation on
TLS with OpenSSL as well as the
HelloWorldClientTls example of the
Advanced Connection Settings¶
Sometimes the default settings for gRPC connections/channels are not suitable for a given situation. These use cases are supported by creating a custom NettyChannelBuilder object and passing the it to the
newBuilder static method defined over DamlLedgerClient.
Example projects using the Java bindings are available on GitHub. Read more about them here.