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 1a930f80fb Docs: correct stale marshaller instance-API entry in 10.0.0
release notes
1a930f80fb is described below
commit 1a930f80fbf563f43b39ecfef544158f78c451b3
Author: James Bognar <[email protected]>
AuthorDate: Tue Jul 14 12:26:20 2026 -0400
Docs: correct stale marshaller instance-API entry in 10.0.0 release notes
The TODO-188-era entry described the
Marshaller/CharMarshaller/StreamMarshaller
instance methods as renamed to to/of; that interim rename was not carried
through.
Instance methods remain read/write (plus the capability-gated token/record
variants)
and of/to ship as static shortcuts on the concrete marshaller classes (work
item 225).
Corrects the entry and its migration note to match the shipped API.
Co-authored-by: Cursor <[email protected]>
---
pages/release-notes/10.0.0.md | 14 ++++++--------
1 file changed, 6 insertions(+), 8 deletions(-)
diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index 118956da7e..352dcb02f4 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -578,14 +578,12 @@ _TBD — to be filled in as development continues._
- **Unaffected** — `MarshalledMap`/`MarshalledList` (and
`JsonMap`/`JsonList`) `getAt`/`putAt`/`postAt`/`deleteAt` are unchanged (now
backed by `PathTraversal`); the companion exception is now
`PathTraversalException` (public, renamed to match `PathTraversal`); the
`Traversable` REST response converter and Swagger/OpenAPI `$ref` (`#/`)
resolution behavior are unchanged.
- **New replacement APIs** — the new `MarshalledNode` typed tree façade and
`JsonPointer` (see New Features above) provide typed navigation and RFC 6901
JSON-Pointer addressing over the same collections model.
-- **`Marshaller` instance-method API renamed (TODO-188).** The top-level
convenience methods on `Marshaller`, `CharMarshaller`, and `StreamMarshaller`
have been renamed to align with the static shortcut names already used on
concrete marshallers (`Json.of(...)`, `Json.to(...)`):
- - `Marshaller.read(Object, Class<T>)` / `read(Object, Type, Type...)` →
`to(Object, Class<T>)` / `to(Object, Type, Type...)`
- - `Marshaller.write(Object, Object)` → `of(Object, Object)`
- - `CharMarshaller.read(String, ...)` → `to(...)`;
`CharMarshaller.write(Object)` → `of(Object)`
- - `StreamMarshaller.read(byte[], ...)` / `read(InputStream, ...)` →
`to(...)`; `StreamMarshaller.write(Object)` → `of(Object)`
- - Six streaming cursor factory methods: `readTokens` → `fromTokens`,
`writeTokens` → `toTokens`, `readRecords` → `fromRecords`, `writeRecords` →
`toRecords`, `readArrayRecords` → `fromArrayRecords`, `writeArrayRecords` →
`toArrayRecords`
-
- Note: the `RecordReader.read()` and `RecordWriter.write()` **cursor**
methods are **not** renamed; only the top-level factory methods on marshaller
instances changed. Update call sites by replacing `.read(` with `.to(` and
`.write(` with `.of(` on marshaller instances, and rename streaming factory
calls accordingly.
+- **`Marshaller` instance API kept as `read`/`write`; static `of`/`to`
shortcuts reintroduced on concrete classes (TODO-225).** An interim plan to
rename the top-level convenience methods on `Marshaller`, `CharMarshaller`, and
`StreamMarshaller` to `to`/`of` was **not** carried through — the instance
methods remain `read`/`write`, and `to`/`of` ship instead as **static**
shortcuts on the concrete marshaller classes (e.g. `Json`, `Xml`, `Protobuf`),
delegating to each class's `DEFAULT` instance:
+ - **Instance (unchanged names):** `Marshaller.read(Object, Class<T>)` /
`read(Object, Type, Type...)`; `Marshaller.write(Object, Object)`.
`CharMarshaller` adds a `String`-based `read(String, ...)` and a
`String`-returning `write(Object)`; `StreamMarshaller` adds a `byte[]`-based
`read(byte[], ...)` and a `byte[]`-returning `write(Object)`.
+ - **Static shortcuts (new, on each concrete class):** `Xxx.to(input, type,
...)` parses via `Xxx.DEFAULT.read(...)`; `Xxx.of(object)` serializes via
`Xxx.DEFAULT.write(...)` — e.g. `Json.to(json, MyBean.class)` /
`Json.of(myBean)`.
+ - **Streaming/record cursors (capability-gated)** — only available when the
underlying serializer/parser implements the corresponding marker interface
(`TokenReadable`/`TokenWritable`, `RecordReadable`/`RecordWritable`,
`ArrayRecordReadable`/`ArrayRecordWritable`): instance
`readTokens`/`writeTokens`, `readRecords`/`writeRecords`,
`readArrayRecords`/`writeArrayRecords`; and their static counterparts
`toTokens`/`ofTokens`, `toRecords`/`ofRecords`,
`toArrayRecords`/`ofArrayRecords`.
+
+ Note: the `RecordReader.read()` and `RecordWriter.write()` **cursor**
methods are a separate, unrelated low-level cursor contract — they were never
part of this rename discussion. If you adopted the earlier
`to`/`of`-as-instance-methods preview, revert those call sites back to
`.read(`/`.write(` on the marshaller instance, or switch to the static shortcut
on the concrete class (`Json.to(...)`/`Json.of(...)`) if you don't need a
custom-configured instance.
- **`SerializerSet` / `ParserSet` lookup methods now return `Optional<...>`
(TODO-190).** Every media-type lookup method on `SerializerSet` and `ParserSet`
now returns a `java.util.Optional` instead of `null` on no-match, aligning
these classes with the `Optional`-returning idiom already used by their
consumers (`RestResponse.getSerializerMatch()`,
`RequestContent.getParserMatch()`). Changed signatures:
- `SerializerSet`: `getSerializer(MediaType)` / `getSerializer(String)` →
`Optional<Serializer>`; `getSerializerMatch(MediaType)` /
`getSerializerMatch(String)` → `Optional<SerializerMatch>`;
`getStreamSerializer(MediaType)` / `getStreamSerializer(String)` →
`Optional<OutputStreamSerializer>`; `getWriterSerializer(MediaType)` /
`getWriterSerializer(String)` → `Optional<WriterSerializer>`.
