Tinystruct Patterns

tinystruct Development Patterns

Architecture and implementation patterns for building modules with the tinystruct Java framework – a lightweight, high-performance framework that treats CLI and HTTP as equal citizens, requiring no main() method and minimal configuration.

Core Principle

CLI and HTTP are equal citizens. Every method annotated with @Action should ideally be runnable from both a terminal and a web browser without modification. This "dual-mode" capability is the core design philosophy of tinystruct.

When to Activate

When to Use

• Creating new Application modules by extending AbstractApplication.
• Defining routes and command-line actions using @Action.
• Handling per-request state via Context.
• Performing JSON serialization using the native Builder and Builders components.
• Working with database persistence via AbstractData POJOs.
• Generating POJOs from database tables using the generate command.
• Implementing Server-Sent Events (SSE) for real-time push.
• Handling file uploads via multipart data.
• Making outbound HTTP requests with URLRequest and HTTPHandler.
• Configuring database connections or system settings in application.properties.
• Debugging routing conflicts (Actions) or CLI argument parsing.

How It Works

The tinystruct framework treats any method annotated with @Action as a routable endpoint for both terminal and web environments. Applications are created by extending AbstractApplication, which provides core lifecycle hooks like init() and access to the request Context.

Routing is handled by the ActionRegistry, which automatically maps path segments to method arguments and injects dependencies. For data-only services, the native Builder and Builders components should be used for JSON serialization to maintain a zero-dependency footprint. The database layer uses AbstractData POJOs paired with XML mapping files for CRUD operations without external ORM libraries.

Examples

Basic Application (MyService)

public class MyService extends AbstractApplication {
    @Override
    public void init() {
        this.setTemplateRequired(false); // Disable .view lookup for data/API apps
    }

    @Override public String version() { return "1.0.0"; }

    @Action("greet")
    public String greet() {
        return "Hello from tinystruct!";
    }

    // Path parameter: GET /?q=greet/James  OR  bin/dispatcher greet/James
    @Action("greet")
    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

HTTP Mode Disambiguation (login)

@Action(value = "login", mode = Mode.HTTP_POST)
public String doLogin(Request<?, ?> request) throws ApplicationException {
    request.getSession().setAttribute("userId", "42");
    return "Logged in";
}

Native JSON Data Handling (Builder + Builders)

import org.tinystruct.data.component.Builder;
import org.tinystruct.data.component.Builders;

@Action("api/data")
public String getData() throws ApplicationException {
    Builders dataList = new Builders();
    Builder item = new Builder();
    item.put("id", 1);
    item.put("name", "James");
    dataList.add(item);

    Builder response = new Builder();
    response.put("status", "success");
    response.put("data", dataList);
    return response.toString(); // {"status":"success","data":[{"id":1,"name":"James"}]}
}

SSE (Server-Sent Events)

import org.tinystruct.http.SSEPushManager;

@Action("sse/connect")
public String connect() {
    return "{\"type\":\"connect\",\"message\":\"Connected to SSE\"}";
}

// Push to a specific client
String sessionId = getContext().getId();
Builder msg = new Builder();
msg.put("text", "Hello, user!");
SSEPushManager.getInstance().push(sessionId, msg);

// Broadcast to all
// Broadcast to all
SSEPushManager.getInstance().broadcast(msg);

File Upload

import org.tinystruct.data.FileEntity;

@Action(value = "upload", mode = Mode.HTTP_POST)
public String upload(Request<?, ?> request) throws ApplicationException {
    List<FileEntity> files = request.getAttachments();
    if (files != null) {
        for (FileEntity file : files) {
            System.out.println("Uploaded: " + file.getFilename());
        }
    }
    return "Upload OK";
}

Database Metadata Operations

DatabaseOperator provides direct access to connection-level catalog, schema, and metadata:

import org.tinystruct.data.DatabaseOperator;

DatabaseOperator operator = new DatabaseOperator();
try {
    String catalog = operator.getCatalog();
    String schema = operator.getSchema();
    java.sql.DatabaseMetaData metaData = operator.getMetaData();
    System.out.println("Using catalog: " + catalog + ", schema: " + schema);
} finally {
    operator.close();
}

MCP Server and Tools Integration

tinystruct provides native support for the Model Context Protocol (MCP) starting with SDK version 1.7.31. The MCP APIs (e.g., org.tinystruct.mcp.MCPTool, org.tinystruct.mcp.MCPServer, org.tinystruct.mcp.MCPException) are included directly in the core dependency:

<dependency>
    <groupId>org.tinystruct</groupId>
    <artifactId>tinystruct</artifactId>
    <version>1.7.31</version>
</dependency>

SECURITY WARNING (Prompt Injection): Tool return values are fed directly back into the AI model's context window. You MUST validate and sanitize all caller-supplied arguments before including them in the tool's return string. Failure to sanitize inputs can allow an attacker to inject adversarial instructions (Prompt Injection) that override the model's behavior. Always validate length, character sets, and nullity.

To create an MCP Tool:

1. Extend org.tinystruct.mcp.MCPTool.
2. Annotate operations with @Action and declare parameters using @Argument within the arguments array.
3. Accept parameters as explicit method arguments matching the keys in @Argument. (Do not use getContext().getAttribute(...) for tool arguments).

import org.tinystruct.mcp.MCPTool;
import org.tinystruct.mcp.MCPException;
import org.tinystruct.system.annotation.Action;
import org.tinystruct.system.annotation.Argument;

public class MyCustomTool extends MCPTool {
    public MyCustomTool() {
        super("custom", "A custom tool for demonstrating MCP");
    }

    @Action(
        value = "custom/hello",
        description = "Say hello to someone",
        arguments = {
            @Argument(key = "name", description = "The name to greet", type = "string", optional = false)
        }
    )
    public String hello(String name) throws MCPException {
        // SECURITY: Validate/sanitize tool inputs before returning to the model
        // to prevent prompt injection vulnerabilities.
        if (name == null || name.length() > 50 || !name.matches("^[a-zA-Z0-9 ]+$")) {
            throw new MCPException("Invalid name provided");
        }
        return "Hello, " + name + "!";
    }
}

To deploy an MCP Server:

1. Extend org.tinystruct.mcp.MCPServer.
2. Override init() and register your tools using this.registerTool(). The framework automatically scans and maps the @Action methods.

import org.tinystruct.mcp.MCPServer;

public class MyMCPServer extends MCPServer {
    @Override
    public void init() {
        super.init();
        this.registerTool(new MyCustomTool());
    }

    @Override
    public String version() {
        return "1.0.0";
    }
}

Run the server via the dispatcher:

bin/dispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyMCPServer

Overloaded Tool Methods

tinystruct supports overloaded methods for the same tool name in MCPTool (sharing the same tool name but accepting different parameter signatures).

• Schema Merging: Input schemas of all overloads with the same name are dynamically merged into a unified JSON schema. Properties are unioned, and required properties are intersected (only fields required across all overloads remain marked mandatory).
• Execution Routing: When executing a tool, the server iterates sequentially through the available overloaded methods, attempting execution. Each method's schema validation is performed first, and the first overload that validates against the provided arguments successfully executes. If no signature matches or succeeds, the framework throws an appropriate exception.

Configuration

Settings are managed in src/main/resources/application.properties.

# Database
driver=org.h2.Driver
database.url=jdbc:h2:~/mydb
database.user=sa
database.password=

# Server
default.home.page=hello
server.port=8080
default.server.open_browser=true

# Locale
default.language=en_US

# Session (Redis for clustered environments)
# default.session.repository=org.tinystruct.http.RedisSessionRepository
# redis.host=127.0.0.1
# redis.port=6379

# Programmatic Logging Configuration
logging.enabled=true
logging.level=INFO
org.tinystruct.level=FINE

Access config values in your application:

String port = this.getConfiguration("server.port");

Logging and Diagnostics

The framework includes a programmatic wrapper around java.util.logging (JUL) that provides beautiful console output and advanced caller tracing out of the box.

• ANSI Console Colors: Console output is color-coded based on the log level (red for SEVERE, yellow for WARNING, green for INFO, cyan for CONFIG, and grey for FINE/debug logs).
• Precise Caller Tracing: Uses Java's StackWalker API to trace the call stack at runtime. It identifies and logs the exact class, method, filename, and line number of the caller that initiated the log (bypassing internal utility and logging layers).
• Package/Logger Level Overrides: Set package-specific overrides directly in application.properties (e.g., org.tinystruct.level=FINE).

Red Flags & Anti-patterns

Best Practices

1. Granular Applications: Break logic into smaller, focused applications rather than one monolithic class.
2. Setup in init(): Leverage init() for setup (config, DB) rather than the constructor. Do NOT call setAction() — use @Action annotation.
3. Mode Awareness: Use the Mode parameter in @Action to restrict sensitive operations to CLI only or specific HTTP methods.
4. Context over Params: For optional CLI flags, use getContext().getAttribute("--flag") rather than adding parameters to the method signature.
5. Asynchronous Events: For heavy tasks triggered by events, use CompletableFuture.runAsync() inside the event handler.

Technical Reference

Detailed guides are available in the references/ directory:

• Architecture & Config — Abstractions, Package Map, Properties
• Routing & @Action — Annotation details, Modes, Parameters
• Data Handling — Builder, Builders, JSON serialization & parsing
• Database Persistence — AbstractData POJOs, CRUD, mapping XML, POJO generation
• System & Usage — Context, Sessions, SSE, File Uploads, Events, Networking
• Testing Patterns — JUnit 5 unit and HTTP integration testing

Reference Source Files (Internal)

• src/main/java/org/tinystruct/AbstractApplication.java — Core base class with lifecycle hooks
• src/main/java/org/tinystruct/system/annotation/Action.java — Annotation & Modes
• src/main/java/org/tinystruct/application/ActionRegistry.java — Routing Engine
• src/main/java/org/tinystruct/data/component/Builder.java — JSON object serializer
• src/main/java/org/tinystruct/data/component/Builders.java — JSON array serializer
• src/main/java/org/tinystruct/data/component/AbstractData.java — Base POJO class with CRUD
• src/main/java/org/tinystruct/data/Mapping.java — Mapping XML parser
• src/main/java/org/tinystruct/data/tools/MySQLGenerator.java — POJO generator reference
• src/main/java/org/tinystruct/data/component/FieldType.java — SQL-to-Java type mappings
• src/main/java/org/tinystruct/data/component/Condition.java — Fluent SQL query builder
• src/main/java/org/tinystruct/http/SSEPushManager.java — SSE connection management
• src/main/java/org/tinystruct/system/logging/LogFormatter.java — Custom log formatter with ANSI console colors and StackWalker-based caller tracing
• src/main/java/org/tinystruct/system/logging/LoggerConfigurer.java — Programmatic logging configurator from application properties
• src/test/java/org/tinystruct/application/ActionRegistryTest.java — Registry test examples
• src/test/java/org/tinystruct/system/HttpServerHttpModeTest.java — HTTP integration test patterns