Skip to content

quickstart-java.md

Latest commit

 

History

History
223 lines (172 loc) · 5.21 KB

quickstart-java.md

File metadata and controls

223 lines (172 loc) · 5.21 KB

Java Quickstart

A comprehensive guide to using the Autonomi network with the Java SDK.

Setup

# Prerequisites
# - Java 21+: https://adoptium.net/
# - antd daemon running (ant dev start)

Gradle (build.gradle.kts):

dependencies {
    implementation("com.autonomi:antd-java:0.1.0")
}

Maven (pom.xml):

<dependency>
    <groupId>com.autonomi</groupId>
    <artifactId>antd-java</artifactId>
    <version>0.1.0</version>
</dependency>

Or scaffold a new project:

ant dev init java --name my-project

Connecting

import com.autonomi.antd.AntdClient;

// REST transport (default) — implements AutoCloseable
try (var client = AntdClient.create()) {
    // use client
}

// Custom endpoint
try (var client = AntdClient.builder()
        .transport("rest")
        .baseUrl("http://localhost:8080")
        .timeout(Duration.ofSeconds(30))
        .build()) {
    // use client
}

// gRPC transport
try (var client = AntdClient.builder()
        .transport("grpc")
        .target("localhost:50051")
        .build()) {
    // use client
}

AntdClient implements AutoCloseable. Always use try-with-resources to ensure proper cleanup.

Health Check

var status = client.health();
System.out.println("Healthy: " + status.ok());
System.out.println("Network: " + status.network()); // "local", "default", "alpha"

Response types are Java records with accessor methods.

Public Data

import java.nio.charset.StandardCharsets;

// Store
byte[] payload = "Hello, Autonomi!".getBytes(StandardCharsets.UTF_8);
var result = client.dataPutPublic(payload);
System.out.println("Address: " + result.address());
System.out.println("Cost: " + result.cost() + " atto tokens");

// Retrieve
byte[] data = client.dataGetPublic(result.address());
System.out.println(new String(data, StandardCharsets.UTF_8)); // "Hello, Autonomi!"

// Cost estimation
long cost = client.dataCost(payload);
System.out.println("Would cost: " + cost + " atto tokens");

Private Data

// Store (self-encrypting)
byte[] secret = "secret message".getBytes(StandardCharsets.UTF_8);
var result = client.dataPutPrivate(secret);
String dataMap = result.address(); // Keep this secret!

// Retrieve (decrypt)
byte[] data = client.dataGetPrivate(dataMap);
System.out.println(new String(data, StandardCharsets.UTF_8));

Files

// Upload a file
var result = client.fileUploadPublic("/path/to/file.txt");
System.out.println("File address: " + result.address());

// Download a file
client.fileDownloadPublic(result.address(), "/path/to/output.txt");

// Upload a directory
var dirResult = client.dirUploadPublic("/path/to/directory");

// Download a directory
client.dirDownloadPublic(dirResult.address(), "/path/to/output_dir");

// Cost estimation
long cost = client.fileCost("/path/to/file.txt");

Graph Entries (DAG Nodes)

import com.autonomi.antd.GraphDescendant;
import java.security.SecureRandom;
import java.util.HexFormat;
import java.util.List;

var random = new SecureRandom();
var hex = HexFormat.of();

byte[] keyBytes = new byte[32];
random.nextBytes(keyBytes);
String key = hex.formatHex(keyBytes);

byte[] contentBytes = new byte[32];
random.nextBytes(contentBytes);
String content = hex.formatHex(contentBytes);

// Create root node
var result = client.graphEntryPut(
    key,
    List.of(),   // parents
    content,
    List.of()    // descendants
);
System.out.println("Graph entry: " + result.address());

// Read
var entry = client.graphEntryGet(result.address());
System.out.println("Owner: " + entry.owner());
System.out.println("Content: " + entry.content());
System.out.println("Parents: " + entry.parents());
System.out.println("Descendants: " + entry.descendants());

// Check existence
boolean exists = client.graphEntryExists(result.address());

Error Handling

import com.autonomi.antd.*;

try {
    client.dataGetPublic("nonexistent");
} catch (NotFoundException e) {
    System.out.println("Not found");
} catch (PaymentException e) {
    System.out.println("Payment issue");
} catch (NetworkException e) {
    System.out.println("Network unreachable");
} catch (AntdException e) {
    System.out.println("Error (" + e.statusCode() + "): " + e.getMessage());
}

Exception hierarchy (all extend AntdException, which extends RuntimeException):

Exception HTTP Code When
BadRequestException 400 Invalid parameters
PaymentException 402 Insufficient funds
NotFoundException 404 Resource not found
AlreadyExistsException 409 Duplicate creation
ForkException 409 Version conflict
TooLargeException 413 Payload too large
InternalException 500 Server error
NetworkException 502 Network unreachable

Examples

cd antd-java

# Gradle
./gradlew run --args="1"    # Connect
./gradlew run --args="2"    # Public data
./gradlew run --args="3"    # Chunks
./gradlew run --args="4"    # Files
./gradlew run --args="5"    # Graph entries
./gradlew run --args="6"    # Private data
./gradlew run --args="all"  # Run all examples

# Maven
mvn exec:java -Dexec.args="1"

Or use the dev CLI:

ant dev example data -l java
ant dev example all -l java