judo-runtime-core

Imported from BlackBeltTechnology/judo-runtime-core (AGENTS.md). Install upstream with npx skills add BlackBeltTechnology/judo-runtime-core. Copyright stays with the author.

JUDO Runtime Core - Developer Guide

Project Overview

Project: JUDO Runtime Core
GroupId: hu.blackbelt.judo.runtime
ArtifactId: judo-runtime-core-parent
Version: 1.0.6-SNAPSHOT
License: Eclipse Public License 2.0 (EPL-2.0)
Repository: https://github.com/BlackBeltTechnology/judo-runtime-core

JUDO Runtime Core is an enterprise-grade Java runtime framework providing data access, business logic, security, and API services for JUDO-based applications.

Code Instructions

1. First think through the problem, read the codebase for relevant files.
2. Before you make any major changes, check in with me and I will verify the plan.
3. Please every step of the way just give me a high level explanation of what changes you made.
4. Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible. Everything is about simplicity.
5. Maintain a documentation file that describes how the architecture of the app works inside and out.
6. Never speculate about code you have not opened. If the user references a specific file, you MUST read the file before answering. Make sure to investigate and read relevant files BEFORE answering questions about the codebase. Never make any claims about code before investigating unless you are certain of the correct answer - give grounded and hallucination-free answers.
7. For implementation use TDD (Test-Driven Development): write or update tests first to define the expected behaviour, verify they fail, then write the minimal implementation to make them pass.
8. Use DRY (Don't Repeat Yourself): extract reusable logic into separate classes, utilities, or components. If the same pattern appears in multiple places, refactor it into a shared helper.

Technology Stack

Core Technologies

Dependency Injection

Web & API

Database & Persistence

JSON Processing

Security

Expression & Query

Metamodels (JUDO Ecosystem)

Testing

Utility Libraries

Build Commands

Prerequisites

• Java 21+
• Maven 3.8.3+

Basic Build

# Full build with tests
mvn clean install

# Build without tests
mvn clean install -DskipTests

# Build without modules (parent only)
mvn clean install -DskipModules=true

Code Quality

# Run tests with coverage
mvn clean verify

# Generate Javadoc
mvn javadoc:javadoc

# SonarQube analysis
mvn sonar:sonar

Release Profiles

# Sign artifacts (for releases)
mvn clean deploy -Psign-artifacts

# Deploy to Nexus (judong)
mvn clean deploy -Prelease-judong

# Deploy to Maven Central
mvn clean deploy -Prelease-central

# Local file-based deployment
mvn clean deploy -Prelease-dummy

Utility Profiles

# Update license headers
mvn license:format -Pupdate-source-code-license

# Generate documentation diagrams
mvn -Pgenerate-github-asciidoc-diagrams

Project Structure

judo-runtime-core/
├── pom.xml                          # Parent POM (aggregator)
├── README.adoc                      # Project documentation
├── CONTRIBUTING.adoc                # Contribution guidelines
├── LICENSE.txt                      # EPL-2.0 license
├── logback-test.xml                 # Test logging config
├── .mvn/                            # Maven wrapper
├── .github/workflows/               # CI/CD pipelines
└── [31 module directories]

Module Architecture

Module Dependency Flow

                    ┌─────────────────────────────────┐
                    │    judo-runtime-core            │
                    │    (Core Abstractions)          │
                    └───────────────┬─────────────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
        ▼                           ▼                           ▼
┌───────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  dao-core     │         │   expression    │         │    security     │
│ (DAO Layer)   │         │  (Expressions)  │         │  (Auth Base)    │
└───────┬───────┘         └─────────────────┘         └────────┬────────┘
        │                                                       │
        ▼                                                       ▼
┌───────────────┐                                     ┌─────────────────┐
│  dao-rdbms    │                                     │security-keycloak│
│ (RDBMS Impl)  │                                     │(Keycloak Auth)  │
└───────┬───────┘                                     └─────────────────┘
        │
        ├─────────────────┬─────────────────┐
        ▼                 ▼                 ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│dao-rdbms-hsqldb│ │dao-rdbms-    │ │dao-rdbms-     │
│               │ │postgresql    │ │liquibase      │
└───────────────┘ └───────────────┘ └───────────────┘

                    Integration Frameworks
        ┌───────────────────────────────────────────┐
        │                                           │
        ▼                                           ▼
┌───────────────────────────┐         ┌─────────────────────────┐
│      Guice Stack          │         │      Spring Stack       │
│ ┌─────────────────────┐   │         │ ┌───────────────────┐   │
│ │ guice (core DI)     │   │         │ │ spring (autoconf) │   │
│ │ guice-hsqldb        │   │         │ │ spring-hsqldb     │   │
│ │ guice-postgresql    │   │         │ │ spring-postgresql │   │
│ │ guice-jetty         │   │         │ └───────────────────┘   │
│ │ guice-cxf           │   │         └─────────────────────────┘
│ │ guice-keycloak      │   │
│ │ guice-testkit       │   │
│ └─────────────────────┘   │
└───────────────────────────┘

Module Descriptions

Foundation Modules

Data Access Layer (DAO)

Business Logic & Processing

Security & Access Control

Serialization & API

Guice Integration

Spring Integration

Utilities

Key Source Packages

Core Module

hu.blackbelt.judo.runtime.core/
├── DataTypeManager.java           # Type conversion and management
├── UUIDIdentifierProvider.java    # UUID-based ID generation
├── SerializableIdentifierProvider.java
├── MetricsCancelToken.java        # Operation cancellation
├── MetricsCollector.java          # Performance metrics
├── PayloadTraverser.java          # Data traversal utilities
└── exception/                     # Custom exceptions

DAO RDBMS Module

hu.blackbelt.judo.runtime.core.dao.rdbms/
├── AbstractRdbmsDAO.java          # Base DAO implementation
├── RdbmsDAOImpl.java              # Full RDBMS DAO
├── RdbmsInit.java                 # Database initialization
├── RdbmsResolver.java             # Entity resolution
├── Dialect.java                   # Database dialect abstraction
├── executors/                     # Statement executors
└── query/                         # Query translation

Packaging Strategy

OSGi Bundle Modules

Most core modules use <packaging>bundle</packaging> with Apache Felix Bundle Plugin:

• dao-core, dao-rdbms
• expression, query, dispatcher, validator
• security, jaxrs, jackson

Standard JAR Modules

Integration and implementation modules use standard JAR packaging:

• guice-, spring-
• jaxrs-cxf, security-keycloak-*
• export-jxls

CI/CD Pipeline

GitHub Actions Workflows

Build Configuration

• Runner: Self-hosted (judong)
• Timeout: 30 minutes
• JDK: Java 21 (Zulu distribution)

Branching Strategy

Commit Requirement: All commits must include a JIRA ticket number (JNG-xxx)

External Integrations

JUDO Ecosystem Dependencies

• judo-dao-api - DAO interface definitions
• judo-dispatcher-api - Dispatcher interface definitions
• judo-sdk-common - Common SDK utilities
• judo-tatami - Model transformation framework
• judo-meta-* - Various metamodels

External Services

• Keycloak - Identity and access management
• PostgreSQL/HSQLDB - Database backends
• Jetty - HTTP server
• Apache CXF - SOAP/REST services

Testing

Test Stack

• JUnit 5 (Jupiter) for unit tests
• Mockito for mocking
• TestContainers for integration tests
• Hamcrest for assertions

Running Tests

# All tests
mvn test

# Integration tests only
mvn verify

# Skip tests
mvn install -DskipTests

# Run specific test
mvn test -Dtest=ClassName

TestContainers

Used for integration testing with:

• PostgreSQL containers
• Keycloak containers

Configuration

Logging

Test logging configured via logback-test.xml in project root.

Maven Properties

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>

Quick Start

1. Clone the repository

   git clone https://github.com/BlackBeltTechnology/judo-runtime-core.git
   cd judo-runtime-core

2. Build the project

   ./mvnw clean install

3. Choose integration framework

   • For Guice: Use judo-runtime-core-guice-* modules
   • For Spring: Use judo-runtime-core-spring-* modules

4. Choose database

   • Development: HSQLDB (*-hsqldb modules)
   • Production: PostgreSQL (*-postgresql modules)