Skip to content

README.md

Latest commit

 

History

History
331 lines (252 loc) · 15.9 KB

README.md

File metadata and controls

331 lines (252 loc) · 15.9 KB
Raw

Strolch

Maven Central License Java Version Contributors Commit Activity Forks Stars Issues

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

  • ⚡ 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"]
Loading

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

Domain Model & Utilities

Security & Auditing

Logic, Execution & Querying

Persistence & Web APIs

Community & License