This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new bf19f140c7 Implement TODO-145 builder-deferred REST class-family
architecture
bf19f140c7 is described below
commit bf19f140c7476529a310fe69cce97470d340af43
Author: James Bognar <[email protected]>
AuthorDate: Mon Jun 1 09:20:37 2026 -0400
Implement TODO-145 builder-deferred REST class-family architecture
- Rename RestObject -> RestResource (+ BasicRestObject[Group] ->
BasicRestResource[Group]) and introduce the opt-in RestMixin base.
- Add per-capability flavor classes (Servlet/Resource/Mixin) for
StaticFiles, Version, Admin, Health, the 4 view engines, and Favicon
(annotation-configured; builder surface deferred to TODO-143).
- Split BasicRestOperations into single-responsibility op-mixins
(error/favicon/htdoc/stats).
- Drop the "Basic" prefix from capability classes (kept for convenience
bundles); BasicViewServlet -> ViewServlet.
- Remove RestRequest.getStaticFiles() (repoint
FileVar/Widget/StaticFilesMixin; keep RestContext.getStaticFiles()).
- Planning docs: TODO-145 refinements, new TODO-146 (mixin host-RestContext
access), TODO.md/TODO-143 updates.
---
pages/release-notes/9.5.0.md | 65 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 65 insertions(+)
diff --git a/pages/release-notes/9.5.0.md b/pages/release-notes/9.5.0.md
index 2794385059..1c46e3c3d2 100644
--- a/pages/release-notes/9.5.0.md
+++ b/pages/release-notes/9.5.0.md
@@ -2278,6 +2278,71 @@ String name
### juneau-rest-server
+#### REST class family architecture — naming triad, `RestMixin`, op-mixins,
flavor fill-in (TODO-145)
+
+A coordinated, breaking restructuring of the `@Rest` resource family
establishes one consistent
+architecture across servlets, child resources, and mixins. All changes below
are hard breaks with no
+deprecation bridges (acceptable for the unreleased 9.5.0 line); they supersede
the pre-rename class
+names used elsewhere in these notes.
+
+**Naming triad — `*Servlet` / `*Resource` / `*Mixin`.** Every reusable
capability now follows a
+self-describing `<Capability><Flavor>` naming scheme, and the vestigial
`Basic` prefix is dropped from
+capability classes (it is retained only on the convenience-bundle bases that
have a barer sibling, e.g.
+`BasicRestServlet`):
+
+- `RestObject` → **`RestResource`** (the non-`HttpServlet` child-resource
base), cascading to
+ `BasicRestObject` → **`BasicRestResource`** and `BasicRestObjectGroup` →
**`BasicRestResourceGroup`**.
+- The mixin pack drops `Basic` and standardizes on the `Mixin` suffix:
+ `BasicStaticFilesResource` → `StaticFilesMixin`, `BasicSwaggerResource` →
`SwaggerMixin`,
+ `BasicSwaggerUiResource` → `SwaggerUiMixin`, `BasicOpenApiResource` →
`OpenApiMixin`,
+ `BasicRedocResource` → `RedocMixin`, `BasicRouteIndexResource` →
`RouteIndexMixin`,
+ `BasicEchoResource` → `EchoMixin`, `BasicAdminResource` → `AdminMixin`,
+ `BasicVersionResource` → `VersionMixin`, `BasicWellKnownResource` →
`WellKnownMixin`,
+ `BasicSeoResource` → `SeoMixin`, `BasicFaviconResource` → `FaviconMixin`,
and the four view mixins
+
`BasicJspResource`/`BasicMustacheResource`/`BasicThymeleafResource`/`BasicFreemarkerResource`
→
+ `JspMixin`/`MustacheMixin`/`ThymeleafMixin`/`FreemarkerMixin`.
+- The servlet companions drop `Basic` too: `BasicStaticFilesServlet` →
`StaticFilesServlet`,
+ `BasicAdminServlet` → `AdminServlet`, `BasicVersionServlet` →
`VersionServlet`, and the abstract
+ `BasicViewServlet` → `ViewServlet` (with `Basic*Servlet` view companions →
`<Engine>Servlet`).
+
+**New `RestMixin` base (opt-in).** A third base class
`org.apache.juneau.rest.servlet.RestMixin` joins
+`RestServlet` and `RestResource` to complete the triad. It is **opt-in** — a
plain `@Rest` POJO remains
+fully valid as a mixin or child via annotation-only configuration; extending
`RestMixin` is a
+convenience and does not change composition semantics. (The fluent
`RestBuilder` programmatic-config
+surface from TODO-143 is **not** part of this release and remains deferred.)
+
+**Op-interfaces deleted; replaced by single-responsibility op-mixins.**
`BasicRestOperations` and
+`BasicGroupOperations` are **removed**. Their endpoints are now true
`@Rest(mixins=...)` mixins —
+`ErrorMixin` (`/error`), `HtdocMixin` (`/htdoc`), `StatsMixin` (`/stats`), and
`FaviconMixin`
+(`/favicon.ico`) — added to the `@Rest(mixins=...)` lists of
`BasicRestServlet` / `BasicRestResource`
+and the Spring `BasicSpringRestServlet`. The host-wide nav-links / JSON-schema
configuration that lived
+on `BasicRestOperations` is re-homed as class-level `@HtmlDocConfig` /
`@JsonSchemaConfig` on
+`BasicRestServlet`; the per-method `@HtmlDocConfig` page decoration moves onto
`StatsMixin.getStats`
+(OQ-8). `getChildren` stays a concrete method on the group bases
+(`BasicRestServletGroup` / `BasicRestResourceGroup` /
`BasicSpringRestServletGroup`) so the host's main
+navigation page retains its `@HtmlDocConfig` chrome (a mixin op runs in its
own sub-context and would
+lose the host's page decoration).
+
+**Favicon reconciliation.** The legacy `getFavIcon` op (which served
`REST/favicon` → `images/juneau.png`
+through static files) is dropped in favor of the single convention
`FaviconMixin`, which serves a
+classpath ICO (`/juneau-favicon.ico`) with a 30-day `Cache-Control`. This is a
behavior change for the
+default favicon bytes and the configuration key.
+
+**Per-capability flavor fill-in (delegate-bean model).** Capabilities where
standalone or routed-child
+deployment is a real use case gain their missing flavors as **independent
classes** that delegate to a
+shared worker bean / mixin instance (so the forms cannot drift). New
child-resource flavors:
+`StaticFilesResource`, `VersionResource`, `AdminResource`, `HealthResource`,
plus a `ViewResource`
+abstract base and per-engine `JspResource` / `MustacheResource` /
`ThymeleafResource` /
+`FreemarkerResource`; new favicon flavors `FaviconServlet` and
`FaviconResource`. `HealthServlet` /
+`HealthMixin` / `HealthResource` all delegate to a shared `HealthAggregator`
worker bean (OQ-5 split of
+the former `BasicHealthResource`). All other capabilities (Swagger, SwaggerUi,
OpenApi, Redoc,
+RouteIndex, Error, Stats, Htdoc, WellKnown, Seo) remain mixin-only.
+
+**`RestRequest.getStaticFiles()` removed.** The request-level forwarder is
deleted; obtain the active
+`StaticFiles` bean via `RestContext.getStaticFiles()` (e.g.
`req.getContext().getStaticFiles()`) or
+bean-store injection. `FileVar`, `Widget`, and the static-files flavors are
repointed accordingly.
+`RestContext.getStaticFiles()` is unchanged.
+
#### Opt-in lazy `@Rest(children=...)` materialization (TODO-121)
Parent resources annotated with `@Rest(lazyChildren=true)` now defer the
construction of each child
