Repository navigation
3.8.0
The marshaller can now change what it writes without changing the objects in memory. This is the runtime's counterpart of JAXB's XmlAdapter, set per call:
context.createMarshaller({
onAttributeValue: function (value, text, owner, propertyInfo, classInfo) { /* a string, null, or undefined */ },
omitElement: function (value, name, typeInfo, propertyInfo, classInfo) { /* true to leave it out */ }
})onAttributeValue is called for an attribute value that printed. It gets the value, text (what the runtime would write), owner (the typed object being marshalled, so sibling properties can be read), the property info and the class info that declares it.
- A returned string is written.
nullomits the attribute.undefinedkeepstext, so a callback can fall through for the properties it does not handle.
A value that fails to print still goes only to 3.7.0's onUnprintableValue.
omitElement is called before each element written from a property, with its value, name, type (after xsi:type), property info and owning class info. That covers element, elements and element-ref properties, revision lists included, and the typed items of a wildcard. Returning true leaves the element out: no start element, no content, no onElement report. The root passed to marshal* is never offered.
Scope. Both callbacks receive class or type infos carrying module.name, so a policy can be confined to one vocabulary. The typings add TypeInfo.module? for this.
Why. @docx4j/generated-objects-ts will normalise WordprocessingML on save the way docx4j does (docx4j CR-060 and CR-061, for core-ts CR-015): colours written upper-case, values Word rejects omitted or written auto, and run-property elements without a valid value left out. Without these hooks that would mean editing the marshalled DOM by element names.
Cost. With neither callback set, the output is byte-identical and the marshal cost is unchanged. With callbacks that fall through at once, it is also within noise: 50,000 elements, median of seven runs, 230 to 236 ms against 3.7.0's 243 to 249 ms.
Also in this release: jsonix-CR-010 section 13 records that Boolean.parse and EnumLeafInfo.parse compare exactly, with no whitespace collapse and no case folding. onInvalidValue callers depend on this: Word reads " false" as on. Tests now pin it. There is no behaviour change.
What a consumer must do. Nothing.
Change request: docs/change-requests/jsonix-CR-011-marshal-side-adapters.md