Package org.apache.juneau.marshall.jcs

Class JcsSerializer

java.lang.Object

org.apache.juneau.marshall.Context

org.apache.juneau.marshall.MarshallingContextable

org.apache.juneau.marshall.MarshallingTraverseContext

org.apache.juneau.marshall.serializer.Serializer

org.apache.juneau.marshall.serializer.WriterSerializer

org.apache.juneau.marshall.json.JsonSerializer

org.apache.juneau.marshall.jcs.JcsSerializer

All Implemented Interfaces:

Function<Object,String>, ThrowingFunction<Object,String>, JsonMetaProvider, ArrayRecordWritable, RecordWritable, TokenWritable

public class JcsSerializer
extends JsonSerializer

Serializes POJO models to canonical JSON per RFC 8785 (JCS).

Media types

Produces media type: application/jcs+json

Description

JCS (JSON Canonicalization Scheme) produces a deterministic, byte-for-byte canonical representation of JSON, enabling reliable cryptographic operations such as hashing and digital signing. All canonicalization rules are defined in RFC 8785.

• No whitespace between tokens.
• Object properties sorted by UTF-16 code unit order, applied recursively to all nested objects.
• Numbers serialized using ECMAScript-compatible rules: shortest round-trip representation, no trailing zeros, lowercase e, positive exponent sign included (e.g. 1e+30).
• Negative zero serialized as 0.
• Non-ASCII characters emitted as literal UTF-8 bytes (no unnecessary unicode escape sequences).
• Array element order is preserved (not sorted).

Example:

// Create a bean. MyBean bean = new MyBean().name("Alice").age(30); // Serialize to canonical JSON. String json = JcsSerializer.DEFAULT.write(bean); // Or use the Jcs marshaller convenience method. String json = Jcs.of(bean);

Example output (bean with name/age):

{"age":30,"name":"Alice"}

Example output with nested object:

{"address":{"city":"Denver","zip":"80201"},"name":"Alice"}

Notes:

• This class is thread safe and reusable.
• JCS output is valid JSON and can be parsed using the standard JsonParser. The Jcs marshaller pairs this serializer with JsonParser for full round-trip support.
• BigDecimal and BigInteger values beyond IEEE 754 double precision range will lose precision or throw a SerializeException. This is a spec-level constraint defined by RFC 8785.
• Double.NaN, Double.POSITIVE_INFINITY, and Double.NEGATIVE_INFINITY are not permitted and will throw a SerializeException.
• Strings containing lone UTF-16 surrogate code units will throw SerializeException.
• Uses application/jcs+json to avoid content-negotiation collision with JsonSerializer (application/json). Request explicitly via Accept: application/jcs+json for canonical output.

See Also:

• RFC 8785 — JSON Canonicalization Scheme
• JCS
• Jcs
• JsonParser

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	JcsSerializer.Builder	Builder class.

Nested classes/interfaces inherited from class org.apache.juneau.marshall.json.JsonSerializer

JsonSerializer.DefaultBuilder, JsonSerializer.Readable

Nested classes/interfaces inherited from class org.apache.juneau.marshall.serializer.Serializer

Serializer.Null

Field Summary

Fields

Modifier and Type	Field	Description
static final JcsSerializer	DEFAULT	Default serializer.

Fields inherited from class org.apache.juneau.marshall.json.JsonSerializer

addBeanTypesJson, DEFAULT_READABLE, escapeSolidus

Fields inherited from class org.apache.juneau.marshall.serializer.WriterSerializer

maxIndent, quoteChar, quoteCharOverride, useWhitespace

Fields inherited from class org.apache.juneau.marshall.serializer.Serializer

accept, addBeanTypes, addRootType, keepNullProperties, listener, nonDefault, produces, sortCollections, sortMaps, trimEmptyCollections, trimEmptyMaps, trimStrings

Fields inherited from class org.apache.juneau.marshall.MarshallingContextable

marshallingContext

Fields inherited from class org.apache.juneau.marshall.Context

CONTEXT_APPLY_FILTER

Constructor Summary

Constructors

Constructor	Description
JcsSerializer(JcsSerializer.Builder builder)	Constructor.

Method Summary

Modifier and Type	Method	Description
JcsSerializer.Builder	copy()	Creates a builder from this context object.
static JcsSerializer.Builder	create()	Creates a new builder for this object.
JcsSerializerSession.Builder	createSession()	Create a session builder based on the properties defined on this context.
boolean	isRecordStreaming()	Streaming-quality signal queryable before opening a cursor.
RecordWriter	writeRecords(Object output)	Convenience delegator (default session args) for a record writer that emits canonical JCS for the value passed to write(...).
TokenWriter	writeTokens(Object output)	Convenience delegator (default session args) for the raw-JSON token writer.

Methods inherited from class org.apache.juneau.marshall.json.JsonSerializer

getJsonBeanPropertyMeta, getJsonClassMeta, getSchemaSerializer, getSession, isAddBeanTypes, isEscapeSolidus, properties, writeArrayRecords

Methods inherited from class org.apache.juneau.marshall.serializer.WriterSerializer

applyThrows, getMaxIndent, getQuoteChar, getStreamCharset, isUseWhitespace, isWriterSerializer, println, quoteChar, toString, write

Methods inherited from class org.apache.juneau.marshall.serializer.Serializer

createSerializerBuilder, doWrite, forEachAcceptMediaType, getListener, getMediaTypeRanges, getPrimaryMediaType, getResponseContentType, getResponseHeaders, getUriContext, getUriRelativity, getUriResolution, isAddRootType, isKeepNullProperties, isNonDefault, isSortCollections, isSortMaps, isTrimEmptyCollections, isTrimEmptyMaps, isTrimStrings, write, writeToString

Methods inherited from class org.apache.juneau.marshall.MarshallingTraverseContext

getDetectRecursions, getIgnoreRecursions, getInitialDepth, getMaxDepth, isDetectRecursions, isIgnoreRecursions, shouldDetectRecursions

Methods inherited from class org.apache.juneau.marshall.MarshallingContextable

getDurationFormat, getMarshallingContext, getPeriodFormat

Methods inherited from class org.apache.juneau.marshall.Context

createBuilder, getAnnotationProvider, init, isDebug, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.juneau.marshall.stream.ArrayRecordWritable

isArrayRecordStreaming, writeArrayRecords

Methods inherited from interface java.util.function.Function

andThen, compose

Methods inherited from interface org.apache.juneau.commons.function.ThrowingFunction

apply

Field Details

DEFAULT

public static final JcsSerializer DEFAULT

Default serializer.

Constructor Details

JcsSerializer

public JcsSerializer(JcsSerializer.Builder builder)

Constructor.

Parameters:

builder - The builder for this object.

Method Details

create

public static JcsSerializer.Builder create()

Creates a new builder for this object.

Returns:

A new builder.

copy

public JcsSerializer.Builder copy()

Description copied from class: Context

Creates a builder from this context object.

Builders are used to define new contexts (e.g. serializers, parsers) based on existing configurations.

Overrides:

copy in class JsonSerializer

Returns:

A new Builder object.

createSession

public JcsSerializerSession.Builder createSession()

Description copied from class: Context

Create a session builder based on the properties defined on this context.

Use this method for creating sessions where you want to override basic settings. Otherwise, use Context.getSession() directly.

Overrides:

createSession in class JsonSerializer

Returns:

A new session builder.

writeTokens

public TokenWriter writeTokens(Object output)
                        throws IOException

Convenience delegator (default session args) for the raw-JSON token writer. Real impl on JcsSerializerSession.writeTokens(Object).

Note: the cursor's structural methods (startObject, fieldName, string, ...) produce ordinary JSON; they do not apply the JCS canonicalization rules (sorted keys, normalized number formatting, etc.) that WriterSerializer.write(Object) produces. The object(Object) bridge is disabled on this writer. Use WriterSerializer.write(Object) for canonical output.

Specified by:

writeTokens in interface TokenWritable

Overrides:

writeTokens in class JsonSerializer

Parameters:

output - The output.

Returns:

A new JsonTokenWriter with object(...) disabled.

Throws:

IOException - If the output type is not supported or could not be opened.

writeRecords

public RecordWriter writeRecords(Object output)
                          throws IOException

Convenience delegator (default session args) for a record writer that emits canonical JCS for the value passed to write(...). Real impl on JcsSerializerSession.writeRecords(Object).

Parameters:

output - The output.

Returns:

A new RecordWriter.

Throws:

IOException - If the output type is not supported or could not be opened.

isRecordStreaming

public boolean isRecordStreaming()

Description copied from interface: RecordWritable

Streaming-quality signal queryable before opening a cursor.

Returns:

true if RecordWritable.writeRecords(Object) returns an O(1)-memory streaming cursor; false for buffered (whole-value) formats backed by RecordAdapter.