Skip to main content

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 the path configured in your hypermass-config.yaml subscription-targets
    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 LastWriteTime (oldest first)
            List<Path> files = stream
                .filter(p -> !p.getFileName().toString().startsWith("."))
                .sorted(Comparator.comparingLong(p -> p.toFile().lastModified()))
                .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.
  • Modified Time Sorting: Sorting by lastModified ensures the temporal integrity of your data stream.
  • 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:

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();
    }
}