Dfinity Agent is a set of native java libriaries to connect remotely to Dfinity Internet Computer applications.
https://dfinity.org/The code is implementation of Internet Computer Interface protocol
https://sdk.dfinity.org/docs/interface-spec/index.html and it's using Dfinity Rust agent as an inspiration, using similar package structures and naming conventions.Internally we are using open source libraries:
- Apache HTTP Components v5 for HTTP communication
- Jackson for CBOR serialization and deserialization
- Bouncy Castle for Ed25519 and Secp256k1 identity signing
Currently we support query and update (call) operations with primitive types. Complex types support is in development.
Dfinity Agent is available under Apache License 2.0.
We support 3 different ways how to connect to Dfinity Internet Computer and invoke either Query or Call method type. Raw methods and Builder class are similar to Rust agent implementation. Third method is to use Java dynamic proxy, which uses annotated interface to read signature of Dfinity canister and methods. Method names and types can be either same as Dfinity methods and types or can be overriden using annotations.
Agent agent = new AgentBuilder()
.transport(transport)
.identity(identity)
.build();
List<IDLValue> args = new ArrayList<IDLValue>();
args.add(IDLValue.create("x"));
args.add(IDLValue.create(new Integer(1)));
IDLArgs idlArgs = IDLArgs.create(args);
data = idlArgs.toBytes();
CompletableFuture<byte[]> response = agent.queryRaw(Principal.fromString(CANISTER_ID),
Principal.fromString(CANISTER_ID), "peek", data, ingressExpiryDatetime);
byte[] output = response.get();
IDLArgs outArgs = IDLArgs.fromBytes(output);
CompletableFuture<byte[]> response = QueryBuilder.create(agent, Principal.fromString(CANISTER_ID), "peek").expireAfter(Duration.ofMinutes(3)).arg(data).call();
Annotated Interface
@Agent(identity = @Identity(type = IdentityType.BASIC, pem_file = "Ed25519_identity.pem"), transport = @Transport(url = "http://localhost:8001"))
@Canister("rrkah-fqaaa-aaaaa-aaaaq-cai")
@EffectiveCanister("rrkah-fqaaa-aaaaa-aaaaq-cai")
public interface HelloProxy {
@QUERY
public String peek(@Argument(Type.TEXT)String name, @Argument(Type.INT) Integer value);
@QUERY
@Name("echoInt")
public Integer getInt(Integer value);
@QUERY
public CompletableFuture<Double> getFloat(Double value);
@UPDATE
@Name("greet")
@Waiter(timeout = 30)
public CompletableFuture<String> greet(@Argument(Type.TEXT)String name);
}
Then create Dynamic Proxy and call the method
HelloProxy hello = ProxyBuilder.create().getProxy(HelloProxy.class);
String result = hello.peek(stringValue, intValue);
To include Java Dfinity Agent in your Java project euther use maven or gradle dependency from Maven Central.
implementation 'com.scaleton.dfinity:dfinity-agent:0.5.1'
<dependency>
<groupId>com.scaleton.dfinity</groupId>
<artifactId>dfinity-agent</artifactId>
<version>0.5.1</version>
</dependency>
You need JDK 8+ to build Dfinity Agent.