OfficeFloor Tutorials
OfficeFloor extends dependency injection with two further kinds of injection:
- Function injection composes plain Java methods into a request-handling pipeline declared entirely in a YAML file. The YAML is the specification: readable without opening any Java file, which is especially valuable when working with AI coding tools.
- Thread injection assigns dedicated thread pools to functions based solely on their dependencies. Socket threads never block on database calls.
The first section covers existing Spring MVC functionality delivered through OfficeFloor function injection. The second covers function orchestration. It composes an endpoint from small, single-purpose functions wired together in YAML. The third shows where OfficeFloor goes beyond Spring MVC, adding capabilities such as thread injection and polyglot procedure logic.
All tutorials are part of the OfficeFloor continuous builds and their source can be found here.
Spring Boot
For developers already using Spring Boot, this is the starting point. The OfficeFloor REST Spring Boot Starter adds REST YAML composition to your existing Spring Boot application without requiring any code migration. Your Spring beans, security, persistence, and all other Spring configuration remain unchanged. OfficeFloor simply takes over the declaration of REST endpoints via YAML files.
The starter is published to Maven Central, so no additional repository configuration is needed. Add the single dependency to your pom.xml and Maven downloads it automatically.
| Tutorial | Description | Covered |
|---|---|---|
| Getting Started | Add the single starter dependency, write one YAML file, and serve your first REST endpoint. No controllers, no annotations. | OfficeFloor REST Spring Boot Starter YAML endpoint basics Spring bean injection |
| Spring REST | YAML naming conventions, multi-method service classes, multiple path variables, and custom response headers via ResponseEntity. | YAML naming conventions method: for multi-method classes ResponseEntity |
| Spring Boot 3 | Add OfficeFloor REST to an existing Spring Boot 3 application using the version-specific starter. Explains which starter to choose for SB3 vs SB4 and how to migrate between them. | officefloor-rest-spring-boot-3-starter Starter version selection |
| Exception Handling | Handle exceptions thrown from REST service methods and map them to HTTP responses. | @ExceptionHandler REST error handling |
| Validation | Validate request payloads and path parameters using Bean Validation. | @Valid ConstraintViolationException |
| Spring Security | Secure REST endpoints using Spring Security with OfficeFloor REST composition. | Spring Security HTTP authorisation |
| CORS | Configure Cross-Origin Resource Sharing for REST endpoints. | CORS @CrossOrigin |
| OpenAPI / Swagger | Generate OpenAPI documentation from REST YAML endpoint declarations. | OpenAPI Swagger UI |
| Thymeleaf | Render Thymeleaf server-side templates from OfficeFloor REST YAML composition. | Thymeleaf Server-side rendering |
| Servlet Interop | Inject HttpServletRequest and HttpServletResponse directly into REST service methods. | HttpServletRequest HttpServletResponse |
| Qualifier | Disambiguate multiple Spring beans of the same type using @Qualifier in service methods. | @Qualifier Bean disambiguation |
| Spring Data JPA | Integrate Spring Data JPA repositories with transaction governance in REST YAML composition. | Spring Data JPA @Transactional governance |
| Actuator | Spring Boot Actuator health, info, and metrics endpoints continue to work alongside OfficeFloor REST YAML endpoints with no additional configuration. | spring-boot-starter-actuator /actuator/health |
| Conversion Reference | Side-by-side reference for converting a Spring MVC REST application to OfficeFloor REST YAML configuration. Covers all common substitutions from endpoint declaration to transaction governance. | Spring → OfficeFloor mapping Conversion checklist |
Function Orchestration
These tutorials cover OfficeFloor's function orchestration model: composing an endpoint from small, single-purpose functions wired together in YAML. Each function is a plain Java method handling one concern, and the YAML names the functions, their order, how state flows between them, and the cross-cutting concerns that wrap them. The final two tutorials apply the complete producer to action to responder pattern to a REST resource, with the naming conventions that keep it navigable.
| Tutorial | Description | Covered |
|---|---|---|
| Function Injection | Compose a multi-function request pipeline via YAML. Conditional branching with @Flow, sequential continuation with return values, and typed data passing between functions. | @Flow @Parameter Pipeline composition |
| Variables | Pass state downstream through a procedure flow without coupling callers to callees. | Out<T> @Val |
| Governance | Wrap function execution with framework-managed pre/post lifecycle declared in YAML, with no annotations on the service class required. Governed objects implement a typed extension interface; OfficeFloor enrolls them automatically. | officefloor/govern/ @Govern, @Enforce, @Disregard Auto-wire extensions |
| REST CRUD Orchestration | Build a full CRUD resource from single-purpose functions for GET, POST, PUT and DELETE. Load and Build producers, Apply and Save actions, RespondWith responders. Entities flow between functions as variables; DTOs appear only at the edges. | Load / Build / Save / RespondWith |
| Filtering and Pagination | Collection endpoints with an optional query-parameter filter and pagination, combined. The read side of a resource, where the list stays a single function. | Optional filter and pagination |
| Related Entities | Two related entities. A shared Load reused across endpoints, and an ownership-scoped load that finds a child within its parent. A global load would leak data across parents. | Shared and scoped loads |
| Resolving References | A Resolve function enriches an entity by looking up managed references from a second repository, between Build/Apply and Save. Shared across create and update. | Resolve function |
| Problem Detail Errors | Structured RFC 7807 error responses (application/problem+json) via office-level escalation handlers: a domain 404, a validation 400 with field errors, and a catch-all 500. | RFC 7807 error responses |
| Testing Functions | Unit test each function as a plain object with the shipped MockVar and MockObjectResponse, then one integration test for the wiring. A testing pyramid over composed functions. | Unit and integration testing |
| Orchestration Patterns and Naming | Reference for the function naming conventions and the request-to-response data flow: validate the DTO, publish the entity via a variable, work only with entities, then transform back to a DTO when responding. Covers the one-shot request body, @Valid ordering, and variable reference semantics. | Naming and data-flow reference |
Beyond Spring MVC: Additional OfficeFloor Capabilities
The following tutorials cover capabilities that OfficeFloor provides over and above what Spring MVC offers. Thread injection assigns dedicated thread pools to pipeline functions so that socket threads are never blocked waiting on databases or external services. The remaining tutorials extend that further with reactive interop, implicit state passing via variables, and polyglot procedure logic written in Kotlin, Scala, JavaScript, or other JVM languages.
| Tutorial | Description | Covered |
|---|---|---|
| Thread Injection | Assign dedicated thread pools to functions based on their dependencies. Socket threads are freed immediately; blocking database calls run on a separate team. | Teams Thread injection officefloor/teams/ |
| Managed Objects | Declare managed objects via YAML with PROCESS, THREAD, or FUNCTION scope. Implement ManagedObjectSource for flows and asynchronous completion managed by the OfficeFloor framework. | officefloor/managedobjects/ ManagedObjectSource flows PROCESS / THREAD / FUNCTION scope |
| Supplier | Register a library of related managed objects from a single YAML declaration. A SupplierSource holds shared state (connections, queues, DI containers) and vends it through multiple typed wrappers, ideal for third-party library integration. | officefloor/suppliers/ SupplierSource Library integration |
| Kotlin | Implement REST procedure logic in Kotlin alongside Java procedures. | Polyglot Kotlin |
| Scala | Implement REST procedure logic in Scala alongside Java procedures. | Polyglot Scala |
| JavaScript | Implement REST procedure logic in JavaScript via GraalVM. | Polyglot JavaScript GraalVM |
| Cats Effect | Integrate Cats Effect functional IO into OfficeFloor REST composition. | Cats Effect |
| ZIO | Integrate ZIO functional effects into OfficeFloor REST composition. | ZIO |