A production-ready reference template covering best practices, architecture patterns, and working examples for enterprise Java development (Java 17+).
- Quick Start
- Project Structure
- Example Modules
- RESTful API — Spring Boot REST server, WebClient, JAX-RS clients
- Database — JPA/Hibernate, JDBC, transactions, connection pooling
- High Performance Computing — Parallel streams, CompletableFuture, virtual threads
- ETL & Batch Processing — Apache Spark, Spring Batch, data pipelines
- Systems Programming — JNI, off-heap memory, JMH benchmarks, profiling
- Design Patterns — 15 GoF patterns with modern Java idioms
- Simulation — Monte Carlo, discrete event simulation
- Testing — JUnit 5, Mockito, TestContainers, REST Assured, ArchUnit
- Documentation Guides
- Tutorial — New developer walkthrough
- Toolchain — Required tools and IDE setup
- Extending the Template — Adding modules, endpoints, dependencies
- Best Practices
- Architecture Patterns
- Third-Party Libraries
- Documentation Standards
- Development Workflow & CI/CD
- Security Scanning — SpotBugs, OWASP, PMD, Checkstyle
- Requirements
- License
# Build all modules
./mvnw clean verify
# Run the REST API example
./mvnw -pl examples/restful-api spring-boot:run
# Run unit tests only
./mvnw test# Run integration tests (requires Docker)
./mvnw verify -P integration-tests
# Format code
./mvnw spotless:apply -P format├── pom.xml # Parent POM — dependency management & plugin config
├── .github/workflows/ci.yml # GitHub Actions CI/CD pipeline
├── docs/
│ ├── TUTORIAL.md # New developer walkthrough (start here!)
│ ├── TOOLCHAIN.md # Required tools, install guides, IDE setup
│ ├── EXTENDING.md # Adding modules, endpoints, dependencies
│ ├── SECURITY_SCANNING.md # SpotBugs, OWASP, PMD, Checkstyle config
│ ├── best-practices.md # Code style, error handling, logging (Java 17+)
│ ├── architecture-patterns.md # Microservices, hexagonal, CQRS, event sourcing
│ ├── third-party-libraries.md # Library catalog with usage examples
│ ├── documentation-standards.md # JavaDoc, OpenAPI/Swagger, README conventions
│ └── development-workflow.md # CI/CD, adding features, Docker, quality gates
├── examples/
│ ├── restful-api/ # REST server + 3 client implementations
│ ├── database/ # JPA entities, repositories, JDBC, Flyway
│ ├── hpc/ # Parallel streams, virtual threads, concurrency
│ ├── etl/ # Spark, Spring Batch, pipeline abstraction
│ ├── systems/ # JNI, off-heap memory, JMH, profiling
│ ├── patterns/ # Creational, structural, behavioral patterns
│ ├── simulation/ # Monte Carlo & discrete event simulation
│ └── testing/ # JUnit 5, Mockito, TestContainers, REST Assured
Path:examples/restful-api/ · README
Spring Boot 3 REST server with full CRUD, plus three client implementations.
| Component | Description |
|---|---|
ProductController | REST endpoints with validation, OpenAPI annotations |
ProductService | Service interface + in-memory implementation |
GlobalExceptionHandler | Centralized error handling with ErrorResponse DTOs |
ProductRestTemplateClient | Synchronous client (RestTemplate + RestClient) |
ProductWebClientExample | Reactive client (WebFlux WebClient) |
ProductJaxRsClient | JAX-RS/Jersey client |
OpenApiConfig | Swagger UI via springdoc-openapi |
Related docs: Best Practices (error handling), Documentation Standards (OpenAPI), Architecture Patterns (microservices)
Path:examples/database/ · README
JPA/Hibernate entities with Spring Data repositories and raw JDBC access.
| Component | Description |
|---|---|
Order / OrderItem | JPA entities with @OneToMany, optimistic locking, lifecycle callbacks |
OrderRepository | Spring Data JPA — derived queries, JPQL, native SQL, bulk updates |
OrderService | Transactional service — propagation, isolation, read-only, rollback rules |
JdbcOrderDao | JdbcTemplate + NamedParameterJdbcTemplate, batch operations |
DataSourceConfig | HikariCP connection pool configuration |
V1__create_orders.sql | Flyway migration |
application.yml | Dual-profile config (H2 dev / PostgreSQL prod) |
Related docs: Best Practices (resource management), Third-Party Libraries (HikariCP, Flyway)
Path:examples/hpc/ · README
Concurrency patterns using modern Java APIs.
| Component | Description |
|---|---|
ParallelStreamExamples | Custom ForkJoinPool, groupingByConcurrent, parallel reduction |
CompletableFutureExamples | Chaining, fan-out/fan-in, error handling, timeouts |
ConcurrentCollectionsExamples | ConcurrentHashMap, BlockingQueue, LongAdder, Semaphore, StampedLock |
VirtualThreadExamples | Java 21+ virtual threads (Maven profile exclusion on Java 17) |
Related docs: Best Practices (concurrency), Architecture Patterns (async patterns)
Path:examples/etl/ · README
Three approaches to data processing: Spark, Spring Batch, and pure Java.
| Component | Description |
|---|---|
SparkEtlExample | RDD word count, DataFrame CSV→Parquet, Spark SQL, typed Datasets |
CsvToJsonBatchConfig | Spring Batch 5 chunk-oriented job with fault tolerance |
DataPipeline | Pure-Java extract/filter/transform/load abstraction |
DataPipelineTest | Unit tests for the pipeline abstraction |
Related docs: Architecture Patterns (CQRS, event sourcing), Third-Party Libraries (Spring Batch)
Path:examples/systems/ · README
Low-level Java: native interop, memory management, and performance measurement.
| Component | Description |
|---|---|
JniExample | JNI native methods with Java fallback pattern |
OffHeapMemoryExample | Direct ByteBuffer, Cleaner-based arrays, memory-mapped files |
PerformanceBenchmarks | JMH benchmarks (string concat, boxing, collections, streams) |
ProfilingUtils | JVM snapshots via MXBeans, execution timing |
Related docs: Best Practices (performance), Development Workflow (profiling)
Path:examples/patterns/ · README
15 GoF patterns implemented with modern Java 17+ idioms (records, sealed interfaces, pattern matching).
| File | Patterns |
|---|---|
CreationalPatterns | Builder, Factory Method, Singleton, Prototype, Abstract Factory |
StructuralPatterns | Adapter, Decorator, Proxy, Composite, Facade |
BehavioralPatterns | Strategy, Observer, Command, Template Method, Chain of Responsibility |
Related docs: Architecture Patterns (hexagonal, CQRS), Best Practices (code style)
Path:examples/simulation/ · README
Statistical and event-driven simulation frameworks.
| Component | Description |
|---|---|
MonteCarloSimulation | Generic engine with Welford's online variance, Pi estimation, option pricing |
DiscreteEventSimulation | Priority-queue DES engine with M/M/1 queue example |
Related docs: HPC module (parallel execution), Best Practices (functional style)
Path:examples/testing/ · README
Comprehensive testing strategy with examples for every layer.
| Component | Description |
|---|---|
JUnit5FeaturesTest | Parameterized, nested, conditional tests, tags |
MockitoFeaturesTest | Mocking, stubbing, captors, BDD style, spies |
PostgresContainerIT | TestContainers PostgreSQL integration test |
RestAssuredIT | REST Assured API testing with httpbin container |
ArchitectureRulesTest | ArchUnit architecture enforcement |
| Domain classes | User, UserRepository, UserService as test targets |
Related docs: Development Workflow (CI/CD, quality gates), Documentation Standards (test documentation)
docs/TUTORIAL.md — New developer walkthrough: clone, build, run the REST API, explore with curl, run other examples, add a feature, run quality/security scans, Docker build. Start here if you're new to the project.
docs/TOOLCHAIN.md — Required tools (JDK 21, Maven wrapper, Docker), platform-specific install instructions (macOS, Linux, Windows), IDE setup (IntelliJ IDEA, VS Code), and quality tool reference.
docs/EXTENDING.md — Step-by-step guides for adding a new Maven module, REST endpoint, service, third-party dependency, and quality rule/suppression.
docs/best-practices.md — 10 sections covering code style, naming conventions, error handling, logging, null safety, records & sealed classes, collections, concurrency, resource management, and general principles. All examples use Java 17+.
docs/architecture-patterns.md — Microservices (Spring Boot, WebClient, Kafka, API Gateway, Resilience4j), hexagonal architecture (ports & adapters), CQRS (command/query separation), event sourcing (aggregate replay, event store, snapshots). Includes decision flowchart and anti-patterns.
docs/third-party-libraries.md — Catalog of recommended libraries: Spring ecosystem (6 starters), Apache Commons, Guava, Jackson, Lombok, MapStruct, Resilience4j, logging (SLF4J + Logback), database libs (HikariCP, Flyway, H2), and build plugins. Includes version reference table and selection decision guide.
docs/documentation-standards.md — JavaDoc conventions (tag ordering, class/method/record examples), README templates, OpenAPI/Swagger integration (springdoc-openapi, code-first vs contract-first, OpenAPI Generator), and changelog format.
docs/development-workflow.md — GitHub Actions 4-stage pipeline, Dockerfile (Temurin 21 JRE Alpine), adding modules/features guide, quality gates (SpotBugs, Checkstyle, JaCoCo, OWASP), Docker Compose, git branching, conventional commits, and release process.
docs/SECURITY_SCANNING.md — Detailed configuration and usage for SpotBugs, Checkstyle, PMD, and OWASP Dependency-Check. Includes suppression guides, CI integration, and a maturity roadmap.
| Requirement | Version |
|---|---|
| Java | 17+ (21 recommended for virtual threads) |
| Maven | 3.9+ (wrapper included) |
| Docker | Required for TestContainers and containerized deployment |
- Records and sealed classes (Java 17)
- Pattern matching for
instanceofandswitch(Java 17+) - Text blocks (Java 17)
- Virtual threads (Java 21+, guarded by Maven profile)
- Sequenced collections (Java 21+, where noted)
| Requirement | Module / Doc | Status |
|---|---|---|
| RESTful APIs (client + server) | examples/restful-api/ | ✅ |
| Database (JPA, JDBC, pooling, transactions) | examples/database/ | ✅ |
| High Performance Computing | examples/hpc/ | ✅ |
| ETL / MapReduce | examples/etl/ | ✅ |
| Systems Programming | examples/systems/ | ✅ |
| Design Patterns (GoF) | examples/patterns/ | ✅ |
| Simulation (Monte Carlo, DES) | examples/simulation/ | ✅ |
| Testing (JUnit 5, TestContainers, REST Assured) | examples/testing/ | ✅ |
| Best Practices Guide | docs/best-practices.md | ✅ |
| Architecture Patterns | docs/architecture-patterns.md | ✅ |
| Third-Party Libraries | docs/third-party-libraries.md | ✅ |
| Documentation Standards | docs/documentation-standards.md | ✅ |
| Development Workflow & CI/CD | docs/development-workflow.md | ✅ |
| Toolchain & IDE Setup | docs/TOOLCHAIN.md | ✅ |
| Extending the Template | docs/EXTENDING.md | ✅ |
| New Developer Tutorial | docs/TUTORIAL.md | ✅ |
| Security Scanning | docs/SECURITY_SCANNING.md | ✅ |
| Project Setup (Maven multi-module) | pom.xml | ✅ |
| CI/CD Pipeline | .github/workflows/ci.yml | ✅ |
| Docker | examples/restful-api/Dockerfile | ✅ |
Apache License 2.0