You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2026/07/14 16:26:25 UTC
(juneau) branch docs updated: Docs: correct stale marshaller instance-API entry in 10.0.0 release notes
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 <ja...@apache.org>
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 <cu...@cursor.com>
---
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>`.