judo-runtimedispatcher-architecture

name: judo-runtime:dispatcher-architecture description: Understanding JUDO Dispatcher internals for advanced customization. Use when learning about operation routing, behaviour handlers, context management, variable providers, or transaction boundaries. metadata: author: BlackBelt Technology version: "${project.version}"

Dispatcher Architecture

Understanding the JUDO Dispatcher internals for advanced customization and debugging.

Overview

The Dispatcher is the central routing component that handles all operation calls in a JUDO application. It routes requests to the appropriate handler (behaviour, script, or SDK implementation) and manages interceptors, transactions, and context.

Architecture Diagram

flowchart TB
    subgraph "JUDO Application"
        REST["JAX-RS/CXF<br/>REST Endpoint"]
        
        subgraph "Dispatcher Module"
            DISP["DefaultDispatcher"]
            RC["RequestConverter"]
            RESP["ResponseConverter"]
            
            subgraph "Handlers"
                BH["Behaviour Handlers<br/>(CRUD)"]
                SH["Script Handlers<br/>(Model Scripts)"]
                SDK["SDK Handlers<br/>(Java Impl)"]
            end
            
            subgraph "Interceptors"
                INT["OperationCallInterceptor"]
                INTP["InterceptorProvider"]
            end
            
            subgraph "Context"
                TC["ThreadContext"]
                VR["VariableResolverManager"]
                AR["ActorResolver"]
            end
        end
        
        DAO["DAO Layer"]
    end
    
    REST --> RC
    RC --> DISP
    DISP --> BH
    DISP --> SH
    DISP --> SDK
    DISP --> INT
    BH --> DAO
    SH --> DAO
    SDK --> DAO
    DISP --> RESP
    RESP --> REST
    
    TC --> DISP
    VR --> DISP
    AR --> DISP

Request Flow

sequenceDiagram
    participant Client
    participant REST as JAX-RS Endpoint
    participant RC as RequestConverter
    participant Disp as Dispatcher
    participant Int as Interceptors
    participant Handler as Operation Handler
    participant DAO
    participant Resp as ResponseConverter
    
    Client->>REST: HTTP Request
    REST->>RC: Convert to Payload
    RC->>Disp: dispatch(operation, payload)
    
    Disp->>Disp: Resolve actor/context
    Disp->>Int: preCall() for all interceptors
    
    alt Behaviour (CRUD)
        Disp->>Handler: BehaviourCall.execute()
    else Script
        Disp->>Handler: ScriptCall.execute()
    else SDK
        Disp->>Handler: SDKCall.execute()
    end
    
    Handler->>DAO: Data access
    DAO-->>Handler: Result
    Handler-->>Disp: Operation result
    
    Disp->>Int: postCall() for all interceptors
    Disp->>Resp: Convert result
    Resp-->>REST: Response payload
    REST-->>Client: HTTP Response

Key Components

DefaultDispatcher

The main dispatcher implementation that:

Routes operations to appropriate handlers
Manages transaction boundaries
Invokes interceptors in order
Handles error translation

Location: hu.blackbelt.judo.runtime.core.dispatcher.DefaultDispatcher

Behaviour Handlers

Built-in CRUD operation handlers:

Handler	Operation Type
`CreateInstanceCall`	Create new entity
`UpdateInstanceCall`	Update existing entity
`DeleteInstanceCall`	Delete entity
`ListCall`	Query/list entities
`RefreshCall`	Reload entity from DB
`GetTemplateCall`	Get default values
`ValidateCreateCall`	Validate before create
`ValidateUpdateCall`	Validate before update

Location: hu.blackbelt.judo.runtime.core.dispatcher.behaviours.*

Context Management

graph LR
    subgraph "Thread Context"
        TC["ThreadContext"]
        TC --> ACTOR["Current Actor"]
        TC --> PARAMS["Request Parameters"]
        TC --> TX["Transaction"]
    end
    
    subgraph "Variable Resolution"
        VRM["VariableResolverManager"]
        VRM --> DATE["CurrentDateProvider"]
        VRM --> TIME["CurrentTimeProvider"]
        VRM --> TS["CurrentTimestampProvider"]
        VRM --> PRINC["PrincipalVariableProvider"]
        VRM --> ENV["EnvironmentVariableProvider"]
    end

Variable Providers

Built-in providers for expression context:

Provider	Variable	Description
`CurrentDateProvider`	`CURRENT_DATE`	Today's date
`CurrentTimeProvider`	`CURRENT_TIME`	Current time
`CurrentTimestampProvider`	`CURRENT_TIMESTAMP`	Current date+time
`PrincipalVariableProvider`	`PRINCIPAL`	Authenticated user
`ActorVariableProvider`	`ACTOR`	Current actor context
`EnvironmentVariableProvider`	`ENV`	Environment variables

Extension Points

Adding Custom Variable Providers

public class MyVariableProvider implements EnvironmentVariableProvider {
    @Override
    public Optional<Object> get(String name) {
        if ("MY_VAR".equals(name)) {
            return Optional.of(computeValue());
        }
        return Optional.empty();
    }
}

Custom Dispatcher Functions

Implement DispatcherFunctionProvider to add custom functions:

public class MyFunctionProvider implements DispatcherFunctionProvider {
    @Override
    public Map<String, Function<Object[], Object>> getFunctions() {
        return Map.of(
            "myFunction", args -> processArgs(args)
        );
    }
}

Transaction Management

stateDiagram-v2
    [*] --> Begin: Start operation
    Begin --> Execute: Transaction opened
    Execute --> PreCommit: Success
    Execute --> Rollback: Exception
    PreCommit --> Commit: Interceptors OK
    PreCommit --> Rollback: Interceptor fails
    Commit --> [*]: Success
    Rollback --> [*]: Error response

The dispatcher manages transactions via Spring's PlatformTransactionManager:

Transaction opened before operation
Committed after successful execution + interceptors
Rolled back on any exception

Debugging Tips

Enable dispatcher logging:

<logger name="hu.blackbelt.judo.runtime.core.dispatcher" level="DEBUG"/>

Check interceptor order: Interceptors run in registration order
Thread context issues: Use ThreadContext to access current context
Variable resolution failures: Check if provider is registered