Strolch

Strolch is an enterprise-grade, high-performance Java runtime and application framework based on a Resource-Order-Activity (ROA) domain model. It features an in-memory transactional object store, fine-grained Role-Based Access Control (RBAC), multi-tenant realm isolation, flexible persistence providers, and comprehensive REST and WebSocket interfaces.

Learn more at our website: https://strolch.li

---

Table of Contents

• Core Highlights
• Architecture & Domain Model
  • Resource-Order-Activity (ROA) Paradigm
  • Parameter Bags & Dynamic Schema
  • Timed States & Historical Values
  • Policy-Driven Extensibility
• Module Overview
• Quick Start
  • Prerequisites
  • Maven Dependency Management (BOM)
  • Building from Source
• Key Features & Code Examples
  • Fluent Model Construction
  • Transactional Data Access
  • Services & Atomic Commands
  • Fluent Searches & SOQL
  • Security & Personal Access Tokens (PATs)
  • RESTful & WebSocket APIs
  • Runtime Configuration & Maintenance
• Documentation Index
• Community & License

---

Core Highlights

• ⚡ In-Memory Speed & Safety: Instantaneous lookups and queries with robust concurrency locking (readLock, writeLock) and ACID transaction semantics.
• 🧩 Flexible Schema Evolution: Model complex domain objects dynamically using typed ParameterBag and Parameter containers without schema migrations.
• 🔒 Fine-Grained RBAC & PATs: Deep authorization down to individual operations and element locators, with session management and Personal Access Tokens.
• 🏢 Multi-Tenancy & Realms: Built-in support for multiple isolated data realms (transient, cached, or persistent).
• 🔄 Executable Workflows: Hierarchical activities and actions with resource allocation, state transitions, and time ordering.
• 🔍 SOQL & Fluent Querying: Powerful, type-safe search builders and Strolch Object Query Language (SOQL).
• 🌐 Modern APIs: Out-of-the-box Jakarta REST (Jersey with OpenAPI/Swagger) and WebSockets for real-time streaming updates.

---

Architecture & Domain Model

Strolch's core architecture revolves around the Resource-Order-Activity (ROA) model:

graph TD
    UI["Web UI / Clients"] -->|REST / WebSockets| API["strolch-web-rest / strolch-websocket"]
    API -->|Services & Commands| SVC["strolch-service"]
    SVC -->|StrolchTransaction| AGENT["strolch-agent / Runtime Container"]
    AGENT -->|In-Memory Model| MODEL["strolch-model: Resource | Order | Activity"]
    AGENT -->|Persistence Providers| DB[("PostgreSQL / XML Filesystem")]
    AGENT -->|Security & RBAC| PRIV["strolch-privilege"]

Resource-Order-Activity (ROA) Paradigm

1. Resources (Resource): Represent master data, static entities, physical assets, or domain actors (e.g., Product, Machine, Location, User).
2. Orders (Order): Represent transactional records, work orders, tasks, or business events moving through a defined lifecycle state (Created, Planning, Planned, Executing, Executed, Closed).
3. Activities (Activity): Represent executable, hierarchical workflows and multi-step plans containing child activities and Actions with time-ordering constraints (Series or Parallel).

Parameter Bags & Dynamic Schema

All root elements (Resource, Order, Activity) and Action elements implement ParameterBagContainer. Parameters are grouped inside named ParameterBag collections:

• Supported Types: String, Integer, Double, Float, Long, Boolean, Date, Duration, Text, StringList, IntegerList, FloatList, LongList.
• Relationships: Defined in a special relations bag with metadata (Interpretation="Resource-Ref", Uom="TargetType"), supporting 1-to-1 (String) and 1-to-N (StringList) relations.

Timed States & Historical Values

Resource elements can manage timed state variables (StrolchTimedState) that capture value changes, schedules, or measurements over time (e.g., stock levels, availability, temperature curves).

Policy-Driven Extensibility

Algorithms, business rules, and integration handlers can be implemented as StrolchPolicy classes and dynamically resolved at runtime via configuration.

---

Module Overview

Module	Description	Documentation
strolch-bom	Bill of Materials (BOM) for managing dependencies across Strolch projects.	README
strolch-model	Core domain model (ROA, Parameters, Bags, TimedStates, Visitors, Builders, XML/JSON).	README | Spec
strolch-agent	Core runtime container, component lifecycle, multi-tenant realms, transactions, and jobs.	README | Runtime
strolch-privilege	Fine-grained Role-Based Access Control (RBAC), authentication, and token management.	README | Spec
strolch-service	Service orchestration layer (AbstractService, Command, activity execution, migrations).	README | Services
strolch-soql	Strolch Object Query Language parser and AST execution engine using ANTLR4.	README
strolch-utils	Project-independent Java utilities (Design-by-Contract, I18n, collections, date-time).	README | Spec
strolch-persistence-postgresql	High-performance PostgreSQL persistence backend (XML/JSON storage, HikariCP pooling).	README | Spec
strolch-persistence-xml	Filesystem XML persistence provider for development and file-backed models.	README | Spec
strolch-xmlpers	Low-level filesystem XML object persistence engine.	README
strolch-web-rest	Jakarta REST (Jersey) API module with OpenAPI/Swagger support and auth filters.	README | Endpoints
strolch-websocket	Real-time WebSocket event broadcaster and subscriptions for model mutations.	README | Spec
strolch-test-base	Test harness, RuntimeMock, test fixtures, and abstract test bases for JUnit.	README
strolch-jmh-benchmark	JMH micro-benchmark suite for performance testing.	README

---

Quick Start

Prerequisites

• Java: JDK 24 or higher recommended
• Maven: Version 3.6+

Maven Dependency Management (BOM)

Import strolch-bom in your project's pom.xml to align all module versions:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>li.strolch</groupId>
            <artifactId>strolch-bom</artifactId>
            <version>2.7.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Add the core dependencies to your application:

<dependencies>
    <dependency>
        <groupId>li.strolch</groupId>
        <artifactId>strolch-agent</artifactId>
    </dependency>
    <dependency>
        <groupId>li.strolch</groupId>
        <artifactId>strolch-service</artifactId>
    </dependency>
    <dependency>
        <groupId>li.strolch</groupId>
        <artifactId>strolch-web-rest</artifactId>
    </dependency>
</dependencies>

Building from Source

Clone the repository and build with Maven:

git clone https://github.com/strolch-li/strolch.git
cd strolch
mvn clean install -DskipTests

To run full tests:

mvn clean install

---

Key Features & Code Examples

Fluent Model Construction

Construct Strolch elements fluently using builders:

Resource product = new ResourceBuilder("prod-001", "Precision Sensor", "Product")
    .bag("parameters", "Parameters")
        .string("sku", "SKU").value("SEN-8821").end()
        .integer("stock", "Stock Level").value(42).end()
        .booleanParam("active", "Is Active").value(true).end()
    .endBag()
    .resourceRelation("manufacturer", "Manufacturer")
    .build();

// Convenient parameter access
String sku = product.getString("sku");
int stock = product.getInteger("stock");

Transactional Data Access

Interact with the data model using safe, auditable transactions:

try (StrolchTransaction tx = agent.openTx(cert, "UpdateProduct", false).rollbackOnFailure()) {
    // Acquire a read-locked modifiable copy
    Resource product = tx.getResourceBy("Product", "prod-001", true);
    Resource lockedProduct = tx.readLock(product);
    
    lockedProduct.setInteger("stock", 50);
    tx.update(lockedProduct);
    
    tx.commitOnClose();
}

Services & Atomic Commands

Encapsulate business logic into reusable AbstractService and Command units:

public class UpdateStockService extends AbstractService<StockArgument, ServiceResult> {
    @Override
    protected ServiceResult internalDoService(StockArgument arg) throws Exception {
        try (StrolchTransaction tx = openArgOrUserTx(arg)) {
            Resource product = tx.getResourceBy("Product", arg.productId, true);
            
            // Execute atomic command within transaction
            UpdateStockCommand command = new UpdateStockCommand(tx, product, arg.newQuantity);
            tx.doCommand(command);
            
            tx.commitOnClose();
        }
        return ServiceResult.success();
    }
}

Fluent Searches & SOQL

Query the in-memory object model with type-safe predicates or SOQL queries:

// Fluent Search API
List<Resource> activeSensors = new ResourceSearch()
    .types("Product")
    .where(param("parameters", "active", isEqualTo(true))
        .and(param("parameters", "stock", isGreaterThan(0))))
    .search(tx)
    .toList();

// Strolch Object Query Language (SOQL)
List<Resource> results = tx.doQuery(
    "SELECT r FROM Resource:Product r WHERE r.parameters.active = true");

Security & Personal Access Tokens (PATs)

Strolch provides role-based authentication and long-lived Personal Access Tokens (PATs) for machine-to-machine integration:

// Authenticate using a Personal Access Token
PrivilegeHandler privilegeHandler = agent.getContainer().getPrivilegeHandler();
Certificate cert = privilegeHandler.authenticatePersonalAccessToken(userPatToken);

// Validate permissions on element locators
tx.assertHasPrivilege(Operation.UPDATE, productResource);

For more details, see Personal Access Tokens Guide.

RESTful & WebSocket APIs

• REST API: Standard endpoints for model CRUD operations, inspections, queries, and service triggers using Jakarta REST and OpenAPI annotations. See REST Documentation.
• WebSocket API: Push live updates to frontend clients when elements change. See WebSocket Documentation.

Runtime Configuration & Maintenance

• Dynamic Configuration: Inspect and update runtime policies on the fly without service restarts. See Runtime Configuration Management.
• Automated Temp File Retention: Built-in scheduled cleanup of temporary files based on configurable ISO-8601 durations. See Temporary File Retention.
• Operations Log: Centralized, queryable system event and alert stream with I18n localization. See Operations Log Guide.

---

Documentation Index

Explore detailed documentation across all Strolch domains:

Architecture & Runtime

• Strolch Agent & Runtime Guide
• Transaction API & Concurrency
• Realms & Multi-Tenancy
• Policy Extensibility Pattern
• Job Handler & Background Tasks
• Runtime Configuration Management
• Temporary File Retention

Domain Model & Utilities

• Strolch Model Technical Specification
• Parameter Memory Footprint Baseline
• Strolch Utils Guide
• Enum Handler

Security & Auditing

• Privilege & RBAC Architecture
• Personal Access Tokens (PATs)
• Sessions & Privilege Handling
• Audit Trail Handler
• Operations Log

Logic, Execution & Querying

• Service & Command Architecture
• Activity Execution Framework
• Reporting Framework
• Migration Framework
• Search API
• SOQL Guide

Persistence & Web APIs

• PostgreSQL Persistence Specification
• XML Persistence Specification
• REST API Endpoints & Authentication
• WebSocket API Specification

---

Community & License

• Website: https://strolch.li
• Source Code: GitHub Repository
• Issues: GitHub Issue Tracker
• Code of Conduct: CODE_OF_CONDUCT.md
• Security Policy: SECURITY.md
• License: Strolch is licensed under the Apache License, Version 2.0.