Serverful Architecture Style

Serverful Architecture

Microservices on a Long-Lived, Multi-Threaded Java Runtime

Overview

Serverful architecture deploys BCE-structured microservices as (uber) jars or regular applications on longer-lived (> 15min), multi-threaded Java runtimes, running on bare metal servers, VMs, or containers with more control over infrastructure and resources.

A well-crafted Serverful application consists solely of pure business logic and the platform (MicroProfile, Jakarta EE or Java SE), with no dependencies on external frameworks or libraries. All top-level packages, also known as business components, are named after business concepts and are consistently structured using the 'boundary control entity' pattern.

Business Components

A Business Component (BC) is a Java package whose name can be understood by product managers and users. BCs provide significant value, which is exposed to external users or systems via the boundary package, and to other BCs via the control and entity packages. A well-sized BC typically hosts a few entities (approximately 1-10) and usually just one Business Facade, keeping components focused and maintainable.

Create classes in the control package when your boundaries become complex or when you need to extract reusable business logic. Control classes should contain methods that focus on a single business task and have transient state. They should also be accessed by boundaries or other controls. Apply the divide-and-conquer principle: if a boundary class is handling multiple concerns or is becoming difficult to understand, refactor the business logic into focused control classes.

Boundary

Create a boundary package as the primary entry point for external clients. Keep boundaries thin and simple by limiting them to input validation, output formatting, and delegation to control or entity layers. Create additional boundaries when you need different external interfaces (REST vs WebSocket) or when cyclomatic complexity exceeds manageable thresholds. Each boundary should expose high-level, transaction-oriented operations that map to specific business capabilities.

Purpose: Act as the entry point between external clients and business logic
Package: Located in the boundary package within a Business Component
Implementation: JAX-RS resources for REST APIs, WebSockets for real-time communication, other protocols are possible.
Naming: Named after domain aspects
Responsibility: Expose high-level, transaction-oriented business operations
Architecture Role: Part of the Entity Control Boundary (ECB) pattern - handles external interfaces
Quantity: Usually just one Business Facade per Business Component
Thin Design: Should contain minimal logic - only input validation, output formatting, delegation
Access Pattern: Called by external users/systems, calls control and entity layers
Complexity Rule: When methods become too complex, extract business logic to control classes
External Exposure: Makes significant business value accessible via HTTP/JSON or other protocols
Transaction Scope: Defines transaction boundaries for business operations. "RequiresNew" is the default
Error Handling: Manages external error responses and status codes
Data Flow: Receives external requests → validates input → delegates to control/entity → formats response

Implementation Guide

Start with REST: Create a JAX-RS resource class with @Path annotation and @Boundary stereotype
Define Operations: Map business operations to HTTP methods (@GET, @POST, @PUT, @DELETE)
Validate Input: Validate input as early as possible and map errors to HTTP status codes
Keep It Thin: If a method exceeds 10-15 lines, extract logic to control layer
Error Responses: Return proper HTTP status codes using Response.status() builders
Content Negotiation: Use @Produces and @Consumes for non-JSON content types
Transaction Boundary: Apply @Transactional annotation or use @Boundary stereotype
Delegation Pattern: Inject control classes with @Inject and delegate business logic
Divide and Conquer: Consider splitting JAX-RS resources into a thin JAX-RS dependent layer (annotations only) and a clean coordination class containing the actual logic
DTO Conversion: Convert between external JSON and internal entities at this layer
Security: Apply @RolesAllowed or custom security annotations here

Control

Create control classes when you need to extract business logic from boundary classes or implement reusable business operations. Control classes should contain methods with transient state that focus on specific business tasks and coordinate entities and external services. Apply the divide-and-conquer principle: when boundary classes become complex or handle multiple concerns, refactor the business logic into focused control classes that can be accessed by boundaries or other control components.

Purpose: Handle business logic and coordinate operations between entities and external services
Package: Located in the control package within a Business Component
Implementation: CDI managed beans (POJOs), or interfaces with static methods
Structure: consists of methods with only transient state - no persistent data
Responsibility: Execute business operations, orchestrate entity interactions, handle business rules
Architecture Role: Part of the Entity Control Boundary (ECB) pattern - contains procedural logic
Access Pattern: Called by boundaries and other control classes, accesses entities and external services
Refactoring Origin: Created through divide-and-conquer principle when boundaries become too complex
Stateless Design: Contains no shared state between method calls, focuses on business operations
Reusability: Can be accessed by multiple boundaries within the same Business Component. Controls can be also accessed by other Business Components without any additional ceremony.
Business Focus: Named and organized around business concepts rather than technical concerns
Testability: Isolated business logic that's easy to unit test independently
Complexity Reduction: Reduces boundary complexity by extracting business logic into focused classes
Coordination Role: Orchestrates calls to entities, external service interfaces, and data transfer objects

Implementation Guide

Extract from Boundary: When boundary methods exceed 20 lines, move logic to control
Create control Classes: Use @ApplicationScoped CDI beans for stateless services
Method Focus: Each method should do one business task (e.g., calculateDiscount, validateAccount)
Inject Dependencies: Use @Inject for EntityManager, external services, other controls
Return Domain Objects: Return entities or DTOs, not technical types like Response
Business Rules: Implement complex business validation and calculations here
External Integration: Call external REST clients, message queues, or databases
Static Methods: For pure functions, use interfaces with static methods
Error Handling: Throw domain-specific runtime exceptions with business meaning
Testability: Design methods to be easily unit testable with mock dependencies

Entity

Create classes in the entity package to represent core business concepts and persistent data structures. Entities should encapsulate both state and business logic related to the domain objects they represent. Use JPA annotations for persistent entities or create regular Java objects for transient domain models. Complex and domain-motivated records, enums, and POJOs should also be modeled as entities when they represent meaningful business concepts rather than simple technical data structures.

Purpose: Represent core business concepts and domain objects with both state and behavior
Package: Located in the entity package within a Business Component
Implementation: JPA entities for persistence or regular Java objects for transient domain models
Structure: Contain both persistent/transient state and business logic related to the domain concept
Responsibility: Encapsulate domain data, business rules, and validation logic for specific business concepts
Architecture Role: Part of the Entity Control Boundary (ECB) pattern - represents the data and domain layer
Business Focus: Represent key domain concepts that are meaningful to business stakeholders
Persistence Options: Can be database-mapped JPA / JDBC entities or non-persistent domain objects
Access Pattern: Used by control classes and accessed through standard JPA or direct object operations
Domain Modeling: Include complex records, domain-motivated enums, and value objects as entities
Self-Contained: Maintain both data state and business methods that operate on that data
Business Logic: Contains domain-specific validation rules and business constraints
Rich Structures: Model sophisticated business records and meaningful enums, not just simple data holders
Optional Nature: Fully optional, but used by the vast majority of real applications
Domain Representation: Each entity represents a key concept from the target business domain, with names ideally taken directly from the domain vocabulary used by business experts and stakeholders to ensure clear communication between technical and business teams

Implementation Characteristics

Scope and Dependency Injection

All CDI beans use @ApplicationScoped except request specific beans like e.g. JWT, user data use @RequestScoped
Field injection is preferred for simplicity
Injected fields are come with package-private visibility
Interfaces are used to hold static methods
All REST resources inherit @ApplicationScoped through @Boundary annotation
control-layer classes (e.g. TransactionProcessor, AccountQuery) explicitly use @ApplicationScoped

Transactions

@Boundary stereotype annotation combines @ApplicationScoped with @Transactional
Transactional boundaries are JAX-RS resources in boundary package
Control-layer classes are not managing transactions

Documentation

Only intentions, motivations and additional context are documented.
Every component ships with package-info.java with javadoc describing the essential responsibility of the component