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

> Explore Apache Maka's built-in tools Read, Write, Edit, Bash, Glob, and Grep. Learn how these stateless Java classes enable safe concurrent file operations and shell execution.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-27

---

**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`](https://github.com/apache/maka/blob/main/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.

```java
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`](https://github.com/apache/maka/blob/main/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.

```java
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`](https://github.com/apache/maka/blob/main/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.

```java
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`](https://github.com/apache/maka/blob/main/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`.

```java
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`](https://github.com/apache/maka/blob/main/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`).

```java
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`](https://github.com/apache/maka/blob/main/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.

```java
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`](https://github.com/apache/maka/blob/main/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.