Open source Beta version of Java Dfinity Agent

Released beta version of open source Java Dfinity Agent. This library enables remotely connect Java application (or any JVM based solution) to Dfinity canister, invoke query or call methods and also asynchronously read state of call operation.
This agent is inspired by existing Rust Dfinity agent, using similar package structure and naming conventions.
To invoke query or call methods, developers can use either raw method or Builder classes, similar to Rust API. Additionally we also added support for Java Dynamic Proxy, which uses annotated Java interface to read canister and methods signatures.
Currently we support only methods with primitive types, complex types and objects support is in development, hopefully will be added soon.
The source of this library is published on Github https://github.com/rdobrik/dfinity-agent and library is also published on Maven Central.
We also published a sample, demonstrating how to build Java Web Service application (HTTP REST GET and POST, Websockets) to call Dfinity query and call methods. You can find is sample here https://github.com/rdobrik/dfinityWSSample.

Appreciate any feedback and suggestions.

Roman

16 Likes

Thank you for this contribution, we appreciate it very much and hope to see a lot of Java developers build on the IC. This contribution definitely makes it easier!

1 Like

Version 0.5.2 is out. Supports opt (Optional), vec (array) and principal Candid types. We added support for TypeMap, so I am going to work on remaining Candid types (record, variant). Currently I do not see too many use cases for service and function Candid types between Java and Motoko (or Rust) so this is something we ca implement later.

Roman

2 Likes

Incredible effort! :100:

Did you see the Candid test data in https://github.com/dfinity/candid/tree/master/test? It would be great if all candid implementations would be tested agains that data, so make sure that interop works really well

Hi Joachim, yes that is a great suggestion. Currently is Candid type testing quite limited, I am using either internal serialize/deserialize and validating input against output and also using full loopback roundtrip against canister methods https://github.com/rdobrik/dfinity-agent/blob/master/src/test/main.mo deployed on my local Dfinity instance. To isolate outputs for mock testing I captured real CBOR binary payloads from Dfinity HTTP response and stored them in the files https://github.com/rdobrik/dfinity-agent/tree/master/src/test/resources.
But like I said, the number of use cases is for now quite limited, definitely more work needs to be done there. Let me see how I can convert RUST Candid unit test procedure to JUnit. It might be interesting to have some generic procedure which can read test data for different use Candid types in some language neutral format (JSON?) so then it can be used for acceptance tests for different Candid language packages (Rust, Java, C, Go…) . Also maybe have one canister with Motoko or Rust test operations, which different language Agent versions use for acceptance as well.

1 Like

The test suite I linked is not tied to rust, and is used by the Haskell library and the Motoko implementation as well. Sorry for the confusion that arises from having the Candid specification and test data in the same repo as one particular implementation.

Currently, you’d have to extend your candid parser with the few extra features needed to express the test files, and write your own test runner here. I am not sure how avoidable that is, given that languages differ quite a lot in how they integrate with Candid. But it shouldn’t be too much extra work, assuming you already have a Candid textual value parser.

Hi Joachim, yes, my mistake, I looked at Rust code before. You are right, test you shared are definitely much easier to convert to JUnit. Thanks for suggestions, I will start working on JUnit procedure using existing test data very soon.

2 Likes

Version 0.5.3 is out. Added support for nat, nat8, nat16, nat32 and nat64. int and nat types are now deserialized to BigInteger. Rewrote type management to better support inner types. Fixed several exception handling and null support in Candid. Added 100+ Candid type test. Joachim, your test suite is extremely helpful, I was able to identify and fix several issues, especially related to exception handling and null values. I will keep adding additional test cases with future releases.

Here is also a short documentation, just some basic use cases. As we progress with our project we will add more detailed, professional documentations as well.

1 Like

It wasn’t just me, but thanks a lot for the praise :slight_smile:

Released a new version of Java IC Agent. Added early access to complex Candid types (record, variant). I am using Java Map based proto objects to serialize/deserialize complex candid types. Something we are planning to do next is to write custom serializers/deserializers to the most common Java types (POJO, JSON, XML/DOM, JDBC/Row). This will be an open interface, so anybody will be able to write their own Java type serializers/deserializers.

We also support unicode String characters in this release.

4 Likes

Version 0.5.5 out. Added support for Android apps (Java/Kotlin). Now we can query or update canisters from Android!

We added support for OkHttp client to be more compatible with Android Java stack. Also had to fix a bunch of incompatibilities between standard Java and Android.

I have a sample (nothing fancy, just a simple Android app written in Kotlin) calling both query and update operations. Works on Android version 8.1 (API 27). I will publish it to Github soon with instructions on how to use it and organize Gradle build.

Also added additional functionality to Apache HTTP 5 Client implementation to support connection pools. Something that can be very useful in highly scalable server applications and data streams like Spark apps.

3 Likes

Beta version 0.5.6 is out. Significantly improved support for complex Candid types (RECORD). Introduced ObjectSerializer and ObjectDeserializer interfaces, which will enable to write custom serializers/deserializers from various Java objects to Candid.
We used those interfaces to impement PojoSerializer and PojoDeserializer. These are converting annotated Java POJO objects to Candid.
Those annotations are similar to something what are Java developers already familiar, for example in Spring or JAXB.
In the next version we are planing to add support for additional Java types (XML/DOM, JSON/Jackson/Gson and JDBC). This will significantly reduce development complexity.

4 Likes

Beta version 0.5.7 is out. This should be the last Beta version for this release, we finalized all major features. Now just testing, testing, testing. We expect to have the first release candidate out in 2 weeks.
For the release candidate we are planning to refactor and change package name to org.ic4j , rebrand the project to IC4J. (I am taking some inspiration from web3j Ethereum project).

This Beta release brings some major improvements. We support some additional complex Java types mapping to/from Candid.

  • JSON (Jackson) Java objects

  • XML (DOM) Java objects

  • JDBC ResultSet Java object

Also release external package to JSON (Gson) Java objects (keeping this as an external project so we do not need to include Gson java libraries in our core package)

10 Likes

Awesome work, didn’t see the post earlier. I will have a look ! Thanks !

1 Like

We refactored our Java Agent libraries under new brand IC4J. It’s now packaged under org.ic4j.

We separated Candid package from Agent package. This will allow us in the future start working on Candid IDL related tools, like POJOs generated from Candid IDL, XML or JSON schema mappings to Candid. Eventually also plugins for Code, Eclipse, Android Studio.

2 Likes

Several Release Candidates are already out. Just pushed out Release Candidate 6. We are continuing with a 1 week release cadence.
We made major improvements in support of complex Candid data structures. All those records, variants, vectors, optionals and their combination. It can be quite hairy, so if you face any problem with some specific Candid type, let me know.
We also significantly improved our POJO, JSON and XML serializers and deserializers to support complex data structures.
We also developed our flagship demo application, LoanFlow, simplified simulation of loan broker process, orchestrating several parties (loan client, credit agency, multiple loan providers). In the centre we have Motoko dapp with 4 canisters, providing an interface to multiple parties. Then we are demonstrating how different Java clients (Android, Java JDBC, Spring with Angular) can communicate with the IC canisters. All on chain :slight_smile:
Here is the link to the source with a simple readme file. I am going to write a much longer Medium article, explaining all the details.

3 Likes

Release Candidate 7 is out. We significantly improved handling of binary payloads using both byte primitives array or Byte object array. Also improved Java POJO serializer/deserializer and ProxyBuilder to better deal with binaries.
I wrote a sample demonstrating how to upload PNG image from Java app to the IC canister, store it and then retrieve back using QUERY call.
You can find this sample and many more in our samples GitHub repository.

3 Likes

Release Candidate 8 is out. GitHub - ic4j/ic4j-agent: IC4J Agent for the Internet Computer Minor fixes, we are almost there. Working on documentation now, the first public draft should be out hopefully next week. We cleaned up our samples, we will use them in our documentation. I always prefer to have functional sample explaining documented functionality. GitHub - ic4j/samples: Samples demonstrating different usage of IC4J Agent libraries

3 Likes

We have a first public draft of IC4J documentation Quick Start - IC4J API Docs . The documentation explains in detail how to use Java and Kotlin API with the Internet Computer canisters. It has links to fully functional samples covering different development scenarios (Identity, JSON payload, XML payload, Pojo Java types, Android…) We also released a minor Release Candidate 9. This is the last Release Candidate version, unless we discover something very critical. Any feedback is welcomed!

1 Like