Skip to main content
Version: 1.4

Getting Started

Prerequisites​

To use the library, we recommend you update Rust to the latest stable version $ rustup update stable. Nightly should be fine but some changes might not be compatible.

Ensure you have first installed the required dependencies for the library here. Then also install the following programs:

  • Java & JDK (Make sure $JAVA_HOME env variable) is set
  • Gradle v4 or higher or Maven installe
  • Cargo ndk (cargo install cargo-ndk)
  • Cargo fmt (rustup component add rustfmt)

Download or clone the iota.rs repository

git clone https://github.com/iotaledger/iota.rs.git

Security​

Password Storage

It is not recommended to store passwords or seeds on a host's environment variables or in the source code in a production setup. Please follow our backup and security recommendations for production use.

Installation​

To build using the iota.rs Java bindings, you need the following two parts:

  1. JNI Native library linking Rust to C, and then C to java native methods (.so , .dll or .dylib depending on your system).
  2. Java archive(Jar) containing native methods which call C code. (.jar).

Step 1: Creating the Native Library​

Build the iota.rs library (This generates the java source code and JNI library file)

cd iota.rs/bindings/java
cargo build --release

Generated binaries can then be found at iota.rs/bindings/java/target/release

Compiling for Android

Compiling for Android requires additional compilation instructions. Specific instructions can be found in Android development

Step 2: Creating the Java archive​

Generating the source files and classes​

After step 1, Java source files will be generated under iota.rs/bindings/java/native/src/main/java/org/iota/client.

If this step succeeded, we need to generate the jar file containing the newly generated Java source files.

Generating the jar​

Generating the jar can be done with your tool of preference. We provide examples for Gradle and Maven in this guide

Gradle​

Make gradlew executable (chmod +x gradlew) if needed, then run

cd iota.rs/bindings/java
./gradlew jar
Maven​
cd iota.rs/bindings/java
mvn install

After running one of these commands, the jar can then be found at iota.rs/bindings/java/native/build/libs/native.jar

Usage​

You can find more information on using the iota.rs library's java binding in the examples section.

Gradle​

./gradlew examples:java-app:test --info

Maven​

mvn exec:exec

Initialisation​

This example fetches node information

private static void nodeInfo() {
    String nodeUrl = "https://chrysalis-nodes.iota.cafe:443";
    Client iota = Client.Builder()
        // Insert your node URL here
        .withNode(nodeUrl)
        // Choose pow mode
        .withLocalPow(true)
        //Then create the Client instance
        .finish();
    NodeInfoWrapper info = iota.getInfo();
    System.out.println("Node url: " + info.url());
    System.out.println("Node Info: " + info.nodeInfo());
}

API Reference​

Java

Limitations​

Due to the fact that we are linking through C from Rust, there are a couple of limiting factors.

  • Classic builder patterns return a clone after each builder call since we can only pass back to C by reference in Rust
Builder builder1 = new Builder();
Builder builder2 = builder1.setValue(true);

// These are different instances, thus builder1 wont have the value set
assertNotEquals(builder1, builder2);