Java API Reference¶

Java library for ISCC (ISO 24138:2024) code generation via JNI. All 30 Tier 1 symbols are exposed as static methods on the IsccLib class. The native library is loaded automatically from the JAR's META-INF/native/ directory, with fallback to System.loadLibrary for development environments.

Installation¶

<dependency>
  <groupId>io.iscc</groupId>
  <artifactId>iscc-lib</artifactId>
  <version>0.4.0</version>
</dependency>

implementation 'io.iscc:iscc-lib:0.4.0'

Quick Example¶

import io.iscc.iscc_lib.IsccLib;

String iscc = IsccLib.genMetaCodeV0("Die Unendliche Geschichte", null, null, 64);
System.out.println(iscc); // e.g. "ISCC:AAA..."

Constants¶

Algorithm constants exposed as public static final int fields on IsccLib.

Classes¶

IsccDecodeResult¶

Result of decoding an ISCC unit string via IsccLib.isccDecode(). All fields are public final.

package io.iscc.iscc_lib;

public class IsccDecodeResult {
    public final int maintype;
    public final int subtype;
    public final int version;
    public final int length;
    public final byte[] digest;
}

Conformance¶

conformanceSelftest¶

Run all ISCC conformance tests against vendored test vectors.

public static native boolean conformanceSelftest();

Returns true if all tests pass, false otherwise.

Code Generation¶

All 10 gen*V0 methods return an ISCC string (prefixed with ISCC:) on success. All throw IllegalArgumentException on invalid input.

genMetaCodeV0¶

Generate a Meta-Code from name and optional metadata.

public static native String genMetaCodeV0(
    String name,
    String description,
    String meta,
    int bits
);

String iscc = IsccLib.genMetaCodeV0(
    "Die Unendliche Geschichte", "Von Michael Ende", null, 64
);

genTextCodeV0¶

Generate a Text-Code from plain text content.

public static native String genTextCodeV0(String text, int bits);

String iscc = IsccLib.genTextCodeV0("Hello World", 64);

genImageCodeV0¶

Generate an Image-Code from 1024 grayscale pixel bytes.

public static native String genImageCodeV0(byte[] pixels, int bits);

byte[] pixels = new byte[1024]; // 32×32 grayscale thumbnail
String iscc = IsccLib.genImageCodeV0(pixels, 64);

genAudioCodeV0¶

Generate an Audio-Code from a Chromaprint feature vector.

public static native String genAudioCodeV0(int[] cv, int bits);

int[] fingerprint = {123456, -789012, 345678};
String iscc = IsccLib.genAudioCodeV0(fingerprint, 64);

genVideoCodeV0¶

Generate a Video-Code from frame signature data.

public static native String genVideoCodeV0(int[][] frameSigs, int bits);

Each frame signature is a 380-element int[] array.

int[][] frameSigs = {new int[380], new int[380]};
String iscc = IsccLib.genVideoCodeV0(frameSigs, 64);

genMixedCodeV0¶

Generate a Mixed-Code from multiple Content-Code strings.

public static native String genMixedCodeV0(String[] codes, int bits);

String[] codes = {"ISCC:EAA...", "ISCC:EEA..."};
String iscc = IsccLib.genMixedCodeV0(codes, 64);

genDataCodeV0¶

Generate a Data-Code from raw byte data.

public static native String genDataCodeV0(byte[] data, int bits);

byte[] data = "Hello World".getBytes();
String iscc = IsccLib.genDataCodeV0(data, 64);

genInstanceCodeV0¶

Generate an Instance-Code from raw byte data.

public static native String genInstanceCodeV0(byte[] data, int bits);

byte[] data = "Hello World".getBytes();
String iscc = IsccLib.genInstanceCodeV0(data, 64);

genIsccCodeV0¶

Generate a composite ISCC-CODE from individual unit codes.

public static native String genIsccCodeV0(String[] codes, boolean wide);

String dataCode = IsccLib.genDataCodeV0(data, 64);
String instanceCode = IsccLib.genInstanceCodeV0(data, 64);
String isccCode = IsccLib.genIsccCodeV0(
    new String[]{dataCode, instanceCode}, false
);

Text Utilities¶

Text processing functions for normalization and cleaning.

textClean¶

Clean and normalize text for display. Applies NFKC normalization, removes control characters (except newlines), normalizes CRLF to LF, collapses consecutive empty lines, and strips leading/trailing whitespace.

public static native String textClean(String text);

textRemoveNewlines¶

Remove newlines and collapse whitespace to single spaces.

public static native String textRemoveNewlines(String text);

textTrim¶

Trim text so its UTF-8 encoded size does not exceed nbytes. Multi-byte characters that would be split are dropped entirely. Leading/trailing whitespace is stripped from the result.

public static native String textTrim(String text, int nbytes);

textCollapse¶

Normalize and simplify text for similarity hashing. Applies NFD normalization, lowercasing, removes whitespace and characters in Unicode categories C, M, and P, then recombines with NFKC normalization.

public static native String textCollapse(String text);

Encoding¶

encodeBase64¶

Encode bytes as base64url (RFC 4648 section 5, no padding).

public static native String encodeBase64(byte[] data);

jsonToDataUrl¶

Convert a JSON string to a data URL with base64 encoding. Uses application/ld+json media type when the JSON contains an @context key, otherwise application/json.

public static native String jsonToDataUrl(String json);

Throws IllegalArgumentException on invalid JSON input.

Codec¶

encodeComponent¶

Encode header fields and a raw digest into a base32-encoded ISCC unit string (without ISCC: prefix).

public static native String encodeComponent(
    int mtype,
    int stype,
    int version,
    int bitLength,
    byte[] digest
);

Throws IllegalArgumentException on invalid input.

isccDecode¶

Decode an ISCC unit string into its header components and raw digest. Strips an optional ISCC: prefix before decoding.

public static native IsccDecodeResult isccDecode(String isccUnit);

Returns an IsccDecodeResult with maintype, subtype, version, length, and digest fields. Throws IllegalArgumentException on invalid input.

IsccDecodeResult result = IsccLib.isccDecode("ISCC:EAASKDNZNYGUUF5A");
System.out.println(result.maintype); // 2 (Content)
System.out.println(result.subtype);  // 0 (Text)

isccDecompose¶

Decompose a composite ISCC-CODE into individual ISCC-UNITs.

public static native String[] isccDecompose(String isccCode);

Returns an array of base32-encoded ISCC-UNIT strings (without ISCC: prefix). Throws IllegalArgumentException on invalid input.

Sliding Window¶

slidingWindow¶

Generate sliding window n-grams from a string.

public static native String[] slidingWindow(String seq, int width);

Throws IllegalArgumentException if width is less than 2.

String[] ngrams = IsccLib.slidingWindow("Hello World", 3);
// ["Hel", "ell", "llo", "lo ", "o W", " Wo", "Wor", "orl", "rld"]

Algorithm Primitives¶

Low-level algorithm functions for SimHash, MinHash, content-defined chunking, and video hashing.

algSimhash¶

Compute a SimHash from a sequence of equal-length hash digests. The output length matches the input digest length.

public static native byte[] algSimhash(byte[][] hashDigests);

Throws IllegalArgumentException on invalid input (empty array or unequal digest lengths).

algMinhash256¶

Compute a 256-bit MinHash digest from 32-bit integer features. Uses 64 universal hash functions with bit-interleaved compression.

public static native byte[] algMinhash256(int[] features);

Returns a 32-byte MinHash digest.

algCdcChunks¶

Split data into content-defined chunks using gear rolling hash.

public static native byte[][] algCdcChunks(byte[] data, boolean utf32, int avgChunkSize);

softHashVideoV0¶

Compute a similarity-preserving hash from video frame signatures.

public static native byte[] softHashVideoV0(int[][] frameSigs, int bits);

Returns a byte array of length bits / 8. Throws IllegalArgumentException if input is empty.

Streaming Hashers¶

Streaming hashers process large data incrementally without loading the entire content into memory. Each hasher follows the lifecycle: *New() → *Update() (repeated) → *Finalize() → *Free().

Streaming hashers use opaque long handles for native memory management. Callers must call the corresponding *Free method to release native memory.

DataHasher¶

Streaming Data-Code hasher using content-defined chunking and MinHash.

// Create a new DataHasher — returns an opaque handle
long hasher = IsccLib.dataHasherNew();

// Push data into the hasher (repeatable)
IsccLib.dataHasherUpdate(hasher, chunk1);
IsccLib.dataHasherUpdate(hasher, chunk2);

// Finalize and get the ISCC string
String iscc = IsccLib.dataHasherFinalize(hasher, 64);

// Free the native memory (required)
IsccLib.dataHasherFree(hasher);

dataHasherNew¶

public static native long dataHasherNew();

Returns an opaque long handle to the hasher.

dataHasherUpdate¶

public static native void dataHasherUpdate(long ptr, byte[] data);

Throws IllegalArgumentException if the hasher has been finalized.

dataHasherFinalize¶

public static native String dataHasherFinalize(long ptr, int bits);

Throws IllegalArgumentException if already finalized or on error.

dataHasherFree¶

public static native void dataHasherFree(long ptr);

Zero/null handle is a no-op. Each handle must be freed exactly once.

InstanceHasher¶

Streaming Instance-Code hasher using BLAKE3.

// Create a new InstanceHasher — returns an opaque handle
long hasher = IsccLib.instanceHasherNew();

// Push data into the hasher (repeatable)
IsccLib.instanceHasherUpdate(hasher, chunk1);
IsccLib.instanceHasherUpdate(hasher, chunk2);

// Finalize and get the ISCC string
String iscc = IsccLib.instanceHasherFinalize(hasher, 64);

// Free the native memory (required)
IsccLib.instanceHasherFree(hasher);

instanceHasherNew¶

public static native long instanceHasherNew();

Returns an opaque long handle to the hasher.

instanceHasherUpdate¶

public static native void instanceHasherUpdate(long ptr, byte[] data);

Throws IllegalArgumentException if the hasher has been finalized.

instanceHasherFinalize¶

public static native String instanceHasherFinalize(long ptr, int bits);

Throws IllegalArgumentException if already finalized or on error.

instanceHasherFree¶

public static native void instanceHasherFree(long ptr);

Zero/null handle is a no-op. Each handle must be freed exactly once.

Error Handling¶

All methods that accept user input throw IllegalArgumentException on invalid arguments:

• Empty or null required parameters (e.g., empty name in genMetaCodeV0)
• Invalid bits values (must be a multiple of 32, range 32–256)
• Malformed ISCC strings passed to isccDecode or isccDecompose
• Streaming hasher operations after finalization

try {
    String iscc = IsccLib.genTextCodeV0("Hello World", 64);
    System.out.println(iscc);
} catch (IllegalArgumentException e) {
    System.err.println("Error: " + e.getMessage());
}

Memory Management¶

Most Java types (String, byte[], int[]) are managed by the JVM garbage collector. The only resources requiring manual cleanup are streaming hasher handles:

• dataHasherFree(long ptr) — release a DataHasher
• instanceHasherFree(long ptr) — release an InstanceHasher

Use try-finally to ensure cleanup:

long hasher = IsccLib.dataHasherNew();
try {
    IsccLib.dataHasherUpdate(hasher, data);
    String iscc = IsccLib.dataHasherFinalize(hasher, 64);
} finally {
    IsccLib.dataHasherFree(hasher);
}