Apache Maka Built-in Tools: Read, Write, Edit, Bash, Glob, and Grep Explained

Apache Maka ships with six core built-in utilities—Read, Write, Edit, Bash, Glob, and Grep—implemented as stateless Java classes in the org.apache.maka.tools package for safe, concurrent file operations and shell execution.

Apache Maka provides a lightweight scripting layer specifically designed for mail-processing pipelines and automation tasks. These built-in tools allow developers to perform common file I/O operations, pattern matching, and shell command execution without external dependencies, all while maintaining thread safety and configurable security boundaries.

Overview of the Six Core Tools

The maka-tools module exposes six primary utility classes that follow a consistent API design. Each tool operates independently, accepts explicit inputs, and returns concrete results without retaining mutable state.

• Read: Loads file contents into memory as String or List<String> objects.
• Write: Persists data to disk with automatic parent directory creation.
• Edit: Applies functional transformations to files in-place.
• Bash: Executes shell commands with timeout controls and output capture.
• Glob: Performs Unix-style filename pattern matching across directory hierarchies.
• Grep: Searches file contents using compiled regular expressions.

All tools are located in the org.apache.maka.tools package within the maka-tools source module.

ReadTool: File Content Access

The ReadTool class provides safe, atomic file reading capabilities for configuration files, templates, and log processing.

Source Location: maka-tools/src/main/java/org/apache/maka/tools/ReadTool.java

Key Methods:

• read(Path path) – Returns entire file content as a single String.
• readLines(Path path) – Returns file content as List<String> with line endings removed.

import org.apache.maka.tools.ReadTool;
import java.nio.file.Paths;

// Read entire config file
String config = ReadTool.read(Paths.get("/opt/maka/config.yaml"));

// Read log lines for processing
List<String> lines = ReadTool.readLines(Paths.get("/var/log/mail.log"));

WriteTool: Persistent Storage

The WriteTool handles byte and character stream output, automatically creating missing parent directories to prevent IOException failures during pipeline execution.

Source Location: maka-tools/src/main/java/org/apache/maka/tools/WriteTool.java

Key Methods:

• write(Path path, String content) – Writes UTF-8 text.
• write(Path path, byte[] content) – Writes raw binary data.

import org.apache.maka.tools.WriteTool;
import java.nio.file.Paths;

// Persist generated output
WriteTool.write(Paths.get("/tmp/maka-output.txt"), "Processing complete");

// Write binary attachment data
byte[] pdfData = generatePdf();
WriteTool.write(Paths.get("/archive/document.pdf"), pdfData);

EditTool: In-Place File Modification

Unlike simple read-write cycles, the EditTool provides atomic in-place editing through functional transformation interfaces, eliminating race conditions during concurrent file updates.

Source Location: maka-tools/src/main/java/org/apache/maka/tools/EditTool.java

Key Method:

• edit(Path path, Function<String, String> transformer) – Applies transformation function and atomically replaces file content.

import org.apache.maka.tools.EditTool;
import java.nio.file.Paths;

// Replace sensitive tokens in configuration
EditTool.edit(Paths.get("/etc/maka/config.properties"), content ->
    content.replaceAll("\\bpassword=\\S+", "password=REDACTED")
);

BashTool: Shell Command Execution

The BashTool wraps ProcessBuilder with sandboxing features, providing controlled access to external utilities like sed, awk, or openssl from within Maka scripts.

Source Location: maka-tools/src/main/java/org/apache/maka/tools/BashTool.java

Key Method:

• exec(String command) – Executes shell command with configurable timeout, returning stdout as String.

import org.apache.maka.tools.BashTool;

// Calculate file checksum
String output = BashTool.exec("sha256sum /etc/hosts").trim();
String checksum = output.split("\\s+")[0];

GlobTool: Pattern-Based File Discovery

The GlobTool leverages Java NIO's FileSystem.getPathMatcher to evaluate Unix-style glob patterns recursively, returning concrete Path objects for batch processing workflows.

Source Location: maka-tools/src/main/java/org/apache/maka/tools/GlobTool.java

Key Method:

• glob(String pattern) – Returns List<Path> of all files matching the pattern (e.g., **/*.txt, data/2024/*/logs/*.log).

import org.apache.maka.tools.GlobTool;
import java.nio.file.Path;
import java.util.List;

// Find all JSON files in data hierarchy
List<Path> configFiles = GlobTool.glob("/data/**/*.json");
configFiles.forEach(p -> System.out.println("Found: " + p));

GrepTool: Content Searching

The GrepTool implements line-by-line regular expression matching using compiled Pattern objects, supporting multiline and case-insensitive flags for log analysis and content filtering.

Source Location: maka-tools/src/main/java/org/apache/maka/tools/GrepTool.java

Key Method:

• grep(Path path, String regex) – Returns List<String> of lines matching the pattern.

import org.apache.maka.tools.GrepTool;
import java.nio.file.Paths;

// Search for error entries (case-insensitive)
List<String> errors = GrepTool.grep(
    Paths.get("/var/log/app.log"),
    "(?i)error|exception|fatal"
);
errors.forEach(System.out::println);

Design Principles and Security Architecture

All six built-in tools share three fundamental architectural constraints designed for production mail-processing environments:

Stateless Operations: Each method receives complete input parameters and returns new objects without modifying internal state, ensuring thread safety across concurrent pipeline stages.

Exception Safety: I/O failures throw MakaToolException with descriptive context rather than checked exceptions, allowing pipeline handlers to implement centralized error recovery strategies.

Configurable Security: Operations respect sandbox boundaries defined in security settings—ReadTool and WriteTool validate paths against allowed directories, while BashTool enforces command whitelists and execution timeouts to prevent unauthorized system access in multi-tenant deployments.

Summary

• Apache Maka provides six built-in tools (ReadTool, WriteTool, EditTool, BashTool, GlobTool, GrepTool) in the org.apache.maka.tools package for common file and shell operations.
• All tools implement stateless APIs suitable for concurrent mail-processing pipelines without synchronization concerns.
• ReadTool and WriteTool handle basic I/O with automatic directory creation and full content handling.
• EditTool offers atomic in-place file modification via functional interfaces.
• BashTool provides sandboxed shell execution with timeout controls using ProcessBuilder internals.
• GlobTool uses FileSystem.getPathMatcher for efficient recursive pattern matching.
• GrepTool applies compiled regular expressions line-by-line for content extraction.
• All operations throw MakaToolException for error handling and respect configurable security boundaries for safe multi-tenant operation.

Frequently Asked Questions

How do I handle large files with ReadTool without running out of memory?

For large files, avoid ReadTool.read() which loads the entire file into a String. Instead, use ReadTool.readLines() to process files as List<String> streams, or combine GlobTool with GrepTool to filter content before loading specific matching lines into memory rather than the entire file.

Can BashTool execute any shell command, or are there restrictions?

BashTool execution is constrained by configurable security settings that typically whitelist allowed commands and set maximum execution timeouts. According to the implementation in BashTool.java, commands run through ProcessBuilder with sandboxed permissions; attempting to execute non-whitelisted commands or exceed timeout limits throws MakaToolException.

What is the difference between GlobTool and standard Java directory listing?

GlobTool supports Unix-style recursive patterns (e.g., **/*.txt) using FileSystem.getPathMatcher, whereas standard Java directory listing requires manual recursion and filename filtering. GlobTool returns concrete Path objects ready for immediate use with other Maka tools like ReadTool or GrepTool.

Are these tools thread-safe for concurrent pipeline processing?

Yes, all six tools implement stateless designs where methods do not modify internal static state. Each operation accepts explicit inputs and returns new result objects, making them safe to invoke from multiple concurrent threads in high-throughput mail-processing pipelines without external synchronization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}