Quick Start

Make your first Java call to the IC canister

To create your first IC canister, follow instructions from the Dfinity Quick Start location.

Internet Computer | DocumentationDFINITYDev

Dfinity Quick Start

You can either use local installation of the Canister SDK or use Motoko Playground.

Motoko Playground - DFINITY

Motoko Playground

If you create local project, it will implicitly create the first Motoko file main.mo. The code is a very simple HelloWorld application with one method named greet.

main.mo

actor {
  public func greet(name : Text) : async Text {
    return "Hello, " # name # "!";
  };
};

To run this canister code in Motoko Playground just copy and paste this source to the Playground editor and click the Deploy button.

We can start building the first Java application, that will invoke greet method. The source of IC4JHelloWorld project can be found here.

For your Java project you can use either Gradle or Maven build. To include IC4J support in your project include Gradle or Maven dependencies.

Gradle

implementation 'org.ic4j:ic4j-agent:0.7.0'
implementation 'org.ic4j:ic4j-candid:0.7.0'

Maven

<dependency>
  <groupId>org.ic4j</groupId>
  <artifactId>ic4j-agent</artifactId>
  <version>0.7.0</version>
</dependency>
<dependency>
  <groupId>org.ic4j</groupId>
  <artifactId>ic4j-candid</artifactId>
  <version>0.7.0</version>
</dependency>

Now we can start writing Java code. The easiest way to communicate with the Internet Computer Canister is to use ProxyBuilder.

The ProxyBuilder module creates the Java proxy object Canister based on Java interface with Canister annotations. You can find full source of this interface here.

HelloWorldProxy.java

public interface HelloWorldProxy {	
	@UPDATE
	@Name("greet")
	@Waiter(timeout = 30)
	public CompletableFuture<String> greet(@Argument(Type.TEXT)String name);
}

Next, define the Type of Method for the Canister (UPDATE or QUERY), the Name of the method and define Waiter properties for UPDATE method.

For method arguments we can also define Candid type.

First we have to create the ReplicaTransport object using the URL to your Canister (either local or remote). The we use AgentBuilder to create the Agent Object.

To create the Canister Proxy object use ProxyBuilder create the method with the agent and the Canister Principal arguments and then getProxy method passing Java proxy class.

The full source can be found here.

Main.java

ReplicaTransport transport = ReplicaApacheHttpTransport.create(icLocation);
Agent agent = new AgentBuilder().transport(transport).build();			
HelloWorldProxy helloWorldProxy = ProxyBuilder.create(agent, Principal.fromString(icCanister))
					.getProxy(HelloWorldProxy.class);
String value = "world";		
CompletableFuture<String> proxyResponse = helloWorldProxy.greet(value);			
String output = proxyResponse.get();

Next, to call the Internet Computer Canister you will need 2 properties, location URL and Canister ID.

This is an example to read those properties from the application.properties file.

application.properties

ic.location=https://icp-api.io/
ic.canister=yaku6-4iaaa-aaaab-qacfa-cai

Replace those properties with ones from your deployed canister, either local or remote.

The UPDATE call will run asynchronously and return the Java CompletableFuture object.

Next, the Java project can be built and run using Gradle Script build.gradle. (This build requires Java 1.8; if you are using a different version, make the necessary modifications in the script).

This build script creates Fat Jar with all the required dependencies.

gradle build

Next run with Java.

java -jar build/libs/ic4j-sample-helloworld-0.6.19.jar

The output should look like this.

[main] INFO org.ic4j.samples.helloworld.Main - Hello, world!