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
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:
- JNI Native library linking
Rust
toC
, and thenC
to javanative
methods (.so
,.dll
or.dylib
depending on your system). - 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 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 inRust
Builder builder1 = new Builder();
Builder builder2 = builder1.setValue(true);
// These are different instances, thus builder1 wont have the value set
assertNotEquals(builder1, builder2);