IC4J API Docs
  • Overview
    • Introduction
  • Quick Start
  • License
  • Reference
    • API Reference
      • Install IC4J Libraries
      • Supported Types
      • ReplicaTransport
      • Identity
      • Principal
      • AgentBuilder
      • ProxyBuilder
      • Using IDLArgs
      • QueryBuilder and UpdateBuilder
      • Using Raw Agent Methods
      • Handle Binary Payloads
      • Object Serializers and Deserializers
        • Pojo Serializer and Deserializer
        • JSON Jackson Serializer and Deserializer
        • JSON Gson Serializer and Deserializer
        • XML DOM Serializer and Deserializer
        • XML JAXB Serializer and Deserializer
        • JDBC Serializer
      • Android Development
Powered by GitBook
On this page
  1. Reference
  2. API Reference

ProxyBuilder

PreviousAgentBuilderNextUsing IDLArgs

Last updated 1 year ago

Using ProxyBuilder is the easiest way to make calls to the Internet Computer using the IC4J Agent. ProxyBuilder will use the Java interface with IC4J annotations which represent the Internet Computer Canister.

The Internet Computer Canister and its Methods will create a proxy object which implements the defined interface.

ProxyBuilder will then provide all Candid type serialization and deserialization steps and the execution of specified canister methods.

Here is an example using Motoko with one QUERY and one UPDATE method.

main.mo
actor {
    stable var name = "Me";

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

    public shared query func peek() : async Text {
        return name;
    };    
};

The Java Proxy interface for this canister looks like .

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

The annotation @Name is optional, but if not specified, the ProxyBuilder will implicitly use the name of the Java method.

The developer can also define the timeout property, to specify when the Waiter should keep checking the state.

The default value for the timeout property is set to 60 seconds. If the annotation is not specified, the ProxyBuilder will automatically set default values.

Main.java
Agent agent = new AgentBuilder().transport(transport).identity(identity).build();			
			
HelloWorldProxy helloWorldProxy = ProxyBuilder.create(agent, Principal.fromString(icCanister))
					.getProxy(HelloWorldProxy.class);rr

The ProxyBuilder Create Method will accept 2 arguments, Agent and Principal.

The getProxy Method will use the proxy interface class as an argument.

The call to the canister can now be completed by calling any other Java function.

String output = helloWorldProxy.peek();

String value = "world";			
CompletableFuture<String> proxyResponse = helloWorldProxy.greet(value);
output = proxyResponse.get();
LoanBroker.java
@Agent(identity = @Identity(type = IdentityType.BASIC, pem_file = "/cert/Ed25519_identity.pem"), transport = @Transport(url = "http://localhost:4943/"))
@Canister("rrkah-fqaaa-aaaaa-aaaaq-cai")
@EffectiveCanister("rrkah-fqaaa-aaaaa-aaaaq-cai")
public interface LoanBroker {
	@UPDATE
	@Name("apply")
	@Waiter(timeout = 30)
	@ResponseClass(LoanOffer.class)
	public CompletableFuture<LoanOffer> apply(@Argument(Type.RECORD)LoanApplication application);
}

Developers can optionally use the following additional annotations.

If the Complex Type Response is being used with Java class needing to be defined, and deserializing is necessary, use the @ResponseClass annotation.

To define if the method is QUERY or UPDATE use or annotations.

For the UPDATE method the developer can explicitly define the Waiter object with annotation, which will check the state of the UPDATE operation in certain intervals, defined by the sleep property. The default value for the sleep property is set to 5 seconds.

For Method parameters the developer can also set a Candid type of the argument with the annotation. If this annotation is not defined, the ProxyBuilder will use the default Java to Candid .

Here is an example of how to create a proxy object in Java .

The UPDATE function call is executed asynchronously, returning the Java result.

The full source code of this sample can be found .

Use the annotation to define Identity and Transport properties directly in the proxy interface.

Use the annotation to define canister id.

Use the annotation to define effective canister id.

canister
this
@QUERY
@UPDATE
@Waiter
@Argument
mapping
code
CompletableFuture
here
@Agent
@Canister
@EffectiveCanister