Marshallers

Marshallers are simple pairings of a Serializer and Parser with convenience methods for serializing and parsing POJOs.

MarshallerT to(Object,Class<T>)CharMarshallerString of(Object)Csv Hjson Hocon Html Ini Jcs Json Json5 Json5l Jsonl Markdown MarkdownDoc OpenApi PlainText Prototext Sse Toml Uon UrlEncoding Xml YamlStreamMarshallerbyte[] of(Object)Bson Cbor MsgPack Parquet Protobuf

Examples

// Using instance.
Json json = new Json();
MyPojo myPojo = json.to(string, MyPojo.class);
String string = json.of(myPojo);

// Using DEFAULT instance.
MyPojo myPojo = Json.DEFAULT.to(string, MyPojo.class);
String string = Json.DEFAULT.of(myPojo);

Juneau comes with the following predefined marshallers:

BsonCborCsvHjsonHoconHtmlIniJcsJsonJson5Json5lJsonlMarkdownMarkdownDocMsgPackOpenApiParquetPlainTextProtobufPrototextSseTomlUonUrlEncodingXmlYaml

Each predefined marshaller also includes static convenience from/to methods to make it even easier to perform marshalling on POJOs:

JsonString of(Object)T to(Object,Class)

Examples

// Using shortcut static methods.
MyPojo myPojo = Json.to(jsonString, MyPojo.class);
String json = Json.of(myPojo);

Stream-based static shortcuts

In addition to the String / byte[] static shortcuts shown above, every marshaller facade also provides static shortcuts that read from and write to streams:

• Character formats (Json, Xml, Html, Yaml, Ini, Hjson, …) add:
  • to(Reader, Class<T>)
  • to(Reader, Type, Type...)
  • of(Object, Writer)
• Binary formats (MsgPack, Cbor, Bson, Protobuf, Parquet) add:
  • to(InputStream, Class<T>)
  • to(InputStream, Type, Type...)
  • of(Object, OutputStream)

// Parse from a Reader / InputStream:
MyPojo a = Json.to(reader, MyPojo.class);
MyPojo b = MsgPack.to(inputStream, MyPojo.class);

// Serialize to a Writer / OutputStream:
Json.of(myPojo, writer);
MsgPack.of(myPojo, outputStream);

Unlike the instance read(...) / write(...) methods (which throw a checked IOException), these static shortcuts wrap any IOException from the underlying stream into an unchecked ParseException (on the to(...) read side) or SerializeException (on the of(...) serialize side), so they can be used directly in lambdas and streams without a checked-exception burden.

note

There are intentionally no File overloads. The core I/O surface is stream-only (see the 10.0.0 breaking-change note on narrowing serializer/parser I/O to streams). To read from or write to a file, open the Reader / Writer / InputStream / OutputStream yourself:

// Serialize to a file (character format):
try (Writer w = Files.newBufferedWriter(path)) {
    Json.of(myPojo, w);
}

// Parse from a file (binary format):
try (InputStream in = Files.newInputStream(path)) {
    MyPojo p = MsgPack.to(in, MyPojo.class);
}

Variant marshaller classes

Every format that has a non-default DEFAULT_* serializer/parser configuration ships a corresponding dedicated variant facade class. Each variant is a subclass of its base format facade with its own DEFAULT instance and the full static shortcut surface bound to that instance — so it exposes the same of(...) / to(...) API (including the stream-based shortcuts above) as any other marshaller:

// Readable JSON5:
String pretty = Json5R.of(myPojo);

// Compact Hjson:
String compact = HjsonC.of(myPojo);

These replace the former Json5.DEFAULT_READABLE, Ini.DEFAULT_READABLE, and Hjson.DEFAULT_COMPACT constants (removed in 10.0.0) and extend the same pattern to every other format for full symmetry.

Variant class	Base	Backed by	Notes
Json5R	Json5	Json5Serializer.DEFAULT_READABLE	Readable (indented) JSON5
JsonR	Json	JsonSerializer.DEFAULT_READABLE	Readable (indented) JSON
IniR	Ini	IniSerializer.DEFAULT_READABLE	Readable (spaced) INI
HjsonC	Hjson	HjsonSerializer.DEFAULT_COMPACT	Compact (single-line) Hjson
TomlR	Toml	TomlSerializer.DEFAULT_READABLE	Readable TOML
YamlR	Yaml	YamlSerializer.DEFAULT_READABLE	Readable YAML
PrototextR	Prototext	PrototextSerializer.DEFAULT_READABLE	Readable Protobuf Text Format
UonR	Uon	UonSerializer.DEFAULT_READABLE	Readable (multi-line) UON
UonE	Uon	UonSerializer.DEFAULT_ENCODING	Percent-encodes reserved/URL-unsafe characters
UrlEncodingR	UrlEncoding	UrlEncodingSerializer.DEFAULT_READABLE	Readable (whitespace-separated) URL-encoding
UrlEncodingPlain	UrlEncoding	UrlEncodingSerializer.DEFAULT_PLAINTEXT	Value parts are not percent-encoded
UrlEncodingExpanded	UrlEncoding	UrlEncodingSerializer.DEFAULT_EXPANDED	Arrays/collections repeat key=value per element instead of comma-joining
HoconBraces	Hocon	HoconSerializer.DEFAULT_BRACES	Same as Hocon.DEFAULT but includes root { } braces
HoconC	Hocon	HoconSerializer.DEFAULT_COMPACT	Compact (single-line), JSON-compatible HOCON
XmlSq	Xml	XmlSerializer.DEFAULT_SQ	Single-quoted attributes
XmlSqR	Xml	XmlSerializer.DEFAULT_SQ_READABLE	Single-quoted attributes + readable
XmlNs	Xml	XmlSerializer.DEFAULT_NS	Namespace-aware output
XmlNsSq	Xml	XmlSerializer.DEFAULT_NS_SQ	Namespace-aware + single-quoted attributes
XmlNsSqR	Xml	XmlSerializer.DEFAULT_NS_SQ_READABLE	Namespace-aware + single-quoted attributes + readable
HtmlSq	Html	HtmlSerializer.DEFAULT_SQ	Single-quoted attributes
HtmlSqR	Html	HtmlSerializer.DEFAULT_SQ_READABLE	Single-quoted attributes + readable
HtmlSimpleSq	Html	HtmlSerializer.DEFAULT_SIMPLE_SQ	Single-quoted attributes + JSON type-hint tags disabled
BsonSpacedHex	Bson	BsonSerializer.DEFAULT_SPACED_HEX / BsonParser.DEFAULT_SPACED_HEX	Spaced-hex byte[] binary format
BsonBase64	Bson	BsonSerializer.DEFAULT_BASE64 / BsonParser.DEFAULT_BASE64	Base64 byte[] binary format
CborSpacedHex	Cbor	CborSerializer.DEFAULT_SPACED_HEX / CborParser.DEFAULT_SPACED_HEX	Spaced-hex byte[] binary format
CborBase64	Cbor	CborSerializer.DEFAULT_BASE64 / CborParser.DEFAULT_BASE64	Base64 byte[] binary format
CborNative	Cbor	CborSerializer.DEFAULT / CborParser.DEFAULT_NATIVE	Native-mode parsing (exposes low-level CBOR tag/type info)
MsgPackSpacedHex	MsgPack	MsgPackSerializer.DEFAULT_SPACED_HEX / MsgPackParser.DEFAULT_SPACED_HEX	Spaced-hex byte[] binary format
MsgPackBase64	MsgPack	MsgPackSerializer.DEFAULT_BASE64 / MsgPackParser.DEFAULT_BASE64	Base64 byte[] binary format
MsgPackNative	MsgPack	MsgPackSerializer.DEFAULT / MsgPackParser.DEFAULT_NATIVE	Native-mode parsing (exposes low-level MessagePack extension-type info)

note

CborNative and MsgPackNative pair the plain (non-variant) serializer with a native-mode parser — only the low-level token-stream interpretation changes, not the serialized bytes.

MarshallUtils

MarshallUtils provides a single set of statically-imported convenience methods that cover every serialization format. Instead of referencing a specific marshaller class, you import MarshallUtils.* and call format-named methods directly.

import static org.apache.juneau.marshall.marshaller.MarshallUtils.*;

// Serialize to any text format
String a = json(myBean);
String b = json5(myBean);
String c = xml(myBean);
String d = yaml(myBean);
String e = toml(myBean);
String f = csv(myBean);

// Serialize to binary formats
byte[] m = msgPack(myBean);
byte[] n = cbor(myBean);
byte[] o = bson(myBean);

// Parse — same method name, overloaded by input
MyBean b1 = json(jsonString,  MyBean.class);
MyBean b2 = xml(xmlString,    MyBean.class);
MyBean b3 = msgPack(bytes,    MyBean.class);

Supported Formats

Method	Format	Serialize output
json(o)	Standard JSON (RFC 8259)	String
json5(o)	JSON5	String
jsonl(o)	JSON Lines (NDJSON)	String
jcs(o)	Canonical JSON (RFC 8785)	String
hjson(o)	HJSON	String
xml(o)	XML	String
html(o)	HTML	String
uon(o)	URL-Encoded Object Notation	String
urlEncoding(o)	URL Encoding	String
yaml(o)	YAML	String
csv(o)	CSV	String
openApi(o)	OpenAPI	String
plainText(o)	Plain text	String
markdown(o)	Markdown (fragment)	String
markdownDoc(o)	Markdown (document)	String
ini(o)	INI / properties	String
toml(o)	TOML	String
hocon(o)	HOCON	String
proto(o)	Protobuf Text Format	String
msgPack(o)	MessagePack	byte[]
cbor(o)	CBOR (RFC 8949)	byte[]
bson(o)	BSON	byte[]
parquet(o)	Apache Parquet	byte[]

Overload Set

Every format method provides the following overloads:

Signature	Purpose
format(Object)	Serialize to String or byte[]
format(Object, Object)	Serialize to a Writer or OutputStream
format(Object, Class<T>)	Parse from any input — throws checked IOException
format(Object, Type, Type...)	Parse from any input with a parameterized type — throws checked IOException
format(String, Class<T>)	Parse from String — exceptions wrapped as unchecked
format(String, Type, Type...)	Parse from String with a parameterized type — unchecked
format(byte[], Class<T>)	Parse from byte[] (binary formats) — unchecked
format(byte[], Type, Type...)	Parse from byte[] with a parameterized type — unchecked

The String- and byte[]-input overloads wrap ParseException / IOException in unchecked runtime exceptions so they can be used directly in lambdas and streams.

// Checked overload — use when the caller can handle IOException
MyBean bean = json(reader, MyBean.class);

// Unchecked overload — convenient in lambdas/streams
List<MyBean> beans = inputStrings.stream()
    .map(s -> json(s, MyBean.class))
    .toList();

// Parameterized type
List<MyBean> list = json(jsonString, List.class, MyBean.class);
Map<String, MyBean> map = json(jsonString, Map.class, String.class, MyBean.class);

// Write to an existing Writer or OutputStream
json(myBean, responseWriter);
msgPack(myBean, outputStream);