Building a Java Client

Java remains the backbone of many enterprise data processing systems. Integrating Hypermass into a JVM-based environment is highly efficient using the modern NIO.2 file libraries.

A simple file poller

This example uses a standard polling loop. It is designed to be easy to drop into an existing Spring Boot service or a standalone JAR.

import java.io.IOException;
import java.nio.file.*;
import java.util.Comparator;
import java.util.List;
import java.util.stream.Stream;

public class HypermassPoller {

    // 🔥 set this to your subscription folder, e.g. <home folder>/hypermass/subscriptions/<stream id>
    private static final String SUB_DIR = "<<YOUR PATH HERE>>";

    public static void main(String[] args) throws InterruptedException {
        System.out.println("Monitoring Hypermass folder: " + SUB_DIR);

        while (true) {
            scanAndProcess();
            Thread.sleep(5000); // Wait 5 seconds
        }
    }

    private static void scanAndProcess() {
        Path path = Paths.get(SUB_DIR);
        if (!Files.exists(path)) return;

        try (Stream<Path> stream = Files.list(path)) {
            // List files, ignoring hidden files (like .hypermass metadata)
            // Sort by name - payload ids are guaranteed to sort in publication order
            List<Path> files = stream
                .filter(p -> !p.getFileName().toString().startsWith("."))
                .sorted(Comparator.comparing(p -> p.getFileName().toString()))
                .toList();

            for (Path filePath : files) {
                System.out.println("Processing: " + filePath.getFileName());

                try {
                    // ⚠️⚠️⚠️ YOUR LOGIC HERE ⚠️⚠️⚠️
                    // String content = Files.readString(filePath);

                    // Delete once processed
                    Files.delete(filePath);
                } catch (Exception e) {
                    System.err.println("Error processing " + filePath.getFileName() + ": " + e.getMessage());
                    // Break to preserve order - try again on next scan
                    break;
                }
            }
        } catch (IOException e) {
            System.err.println("Failed to list directory: " + e.getMessage());
        }
    }
}

About this code

We suggest starting with this and modifying it to suit your needs. Some notes about the approach;

• Stream API Filtering: We use Java's Stream API to cleanly filter out the .hypermass system directory and any other hidden files.
• Name Sorting: Each file is named with its payload id, and payload ids sort in publication order, so sorting by file name processes files in publication order.
• Atomic Readiness: Because the Hypermass CLI moves files into the directory only once they are fully written, Java's Files.delete() won't catch a file mid-write.

note

The hypermass sync command relies on the hidden .hypermass directory to track what it has already downloaded. The code above is explicitly written to ignore this directory.

How to productionize this code example

Small file subscriptions

For standard JSON or XML, Files.readString(path) (Java 11+) is the easiest way to pull data into memory.

Large file subscriptions

If you are processing larger files, use InputStreams and stream processing libraries to keep your memory footprint low:

• JSON: Use Jackson Streaming API for high-performance, low-memory parsing.
• XML: Use the built-in StAX (Streaming API for XML) parser.

Stop on fail

The break in the catch block is critical. In enterprise messaging, skipping a failed file can lead to "out-of-sync" state. If a file fails, it's often safer to let it sit in the folder and alert an operator.

Structure

If you are using Spring, or some other IOC framework, you'll likely want to register the poller as a bean to make wiring, control and monitoring easier.

Using Spring Boot

If you're in a Spring environment, you can trigger this logic from a @Scheduled task:

@Component
public class HypermassSyncTask {

    @Autowired
    private HypermassPoller hypermassPoller;

    @Scheduled(fixedDelay = 5000)
    public void scheduleFileTask() {
        hypermassPoller.scanAndProcess();
    }
}