org.apache.juneau.uon

Class UonSerializer

java.lang.Object

org.apache.juneau.Context

org.apache.juneau.BeanContext

org.apache.juneau.BeanTraverseContext

org.apache.juneau.serializer.Serializer

org.apache.juneau.serializer.WriterSerializer

org.apache.juneau.uon.UonSerializer

All Implemented Interfaces:

HttpPartSerializer

Direct Known Subclasses:

OpenApiSerializer, UonSerializer.Encoding, UonSerializer.Readable, UrlEncodingSerializer

@ConfigurableContext
public class UonSerializer
extends WriterSerializer
implements HttpPartSerializer

Serializes POJO models to UON (a notation for URL-encoded query parameter values).

Media types

Handles Accept types: text/uon

Produces Content-Type types: text/uon

Description

This serializer provides several serialization options. Typically, one of the predefined DEFAULT serializers will be sufficient. However, custom serializers can be constructed to fine-tune behavior.

The following shows a sample object defined in Javascript:

{ id: 1, name: 'John Smith', uri: 'http://sample/addressBook/person/1', addressBookUri: 'http://sample/addressBook', birthDate: '1946-08-12T00:00:00Z', otherIds: null, addresses: [ { uri: 'http://sample/addressBook/address/1', personUri: 'http://sample/addressBook/person/1', id: 1, street: '100 Main Street', city: 'Anywhereville', state: 'NY', zip: 12345, isCurrent: true, } ] }

Using the "strict" syntax defined in this document, the equivalent UON notation would be as follows:

( id=1, name='John+Smith', uri=http://sample/addressBook/person/1, addressBookUri=http://sample/addressBook, birthDate=1946-08-12T00:00:00Z, otherIds=null, addresses=@( ( uri=http://sample/addressBook/address/1, personUri=http://sample/addressBook/person/1, id=1, street='100+Main+Street', city=Anywhereville, state=NY, zip=12345, isCurrent=true ) ) )

Example:

// Serialize a Map Map m = new ObjectMap("{a:'b',c:1,d:false,e:['f',1,false],g:{h:'i'}}"); // Serialize to value equivalent to JSON. // Produces "(a=b,c=1,d=false,e=@(f,1,false),g=(h=i))" String s = UonSerializer.DEFAULT.serialize(s); // Serialize a bean public class Person { public Person(String s); public String getName(); public int getAge(); public Address getAddress(); public boolean deceased; } public class Address { public String getStreet(); public String getCity(); public String getState(); public int getZip(); } Person p = new Person("John Doe", 23, "123 Main St", "Anywhere", "NY", 12345, false); // Produces "(name='John Doe',age=23,address=(street='123 Main St',city=Anywhere,state=NY,zip=12345),deceased=false)" String s = UonSerializer.DEFAULT.serialize(s);

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UonSerializer.Encoding Equivalent to UonSerializer.create().encoding().build();.
static class	UonSerializer.Readable Equivalent to UonSerializer.create().ws().build();.

Nested classes/interfaces inherited from interface org.apache.juneau.httppart.HttpPartSerializer

HttpPartSerializer.Null

Field Summary

Fields

Modifier and Type	Field and Description
static UonSerializer	DEFAULT Reusable instance of UonSerializer, all default settings.
static UonSerializer	DEFAULT_ENCODING Reusable instance of UonSerializer.Encoding.
static UonSerializer	DEFAULT_READABLE Reusable instance of UonSerializer.Readable.
static String	UON_addBeanTypes Configuration property: Add "_type" properties when needed.
static String	UON_encoding Configuration property: Encode non-valid URI characters.
static String	UON_paramFormat Configuration property: Format to use for query/form-data/header values.

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

WSERIALIZER_fileCharset, WSERIALIZER_maxIndent, WSERIALIZER_quoteChar, WSERIALIZER_streamCharset, WSERIALIZER_useWhitespace

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

SERIALIZER_addBeanTypes, SERIALIZER_addRootType, SERIALIZER_listener, SERIALIZER_sortCollections, SERIALIZER_sortMaps, SERIALIZER_trimEmptyCollections, SERIALIZER_trimEmptyMaps, SERIALIZER_trimNullProperties, SERIALIZER_trimStrings, SERIALIZER_uriContext, SERIALIZER_uriRelativity, SERIALIZER_uriResolution

Fields inherited from class org.apache.juneau.BeanTraverseContext

BEANTRAVERSE_detectRecursions, BEANTRAVERSE_ignoreRecursions, BEANTRAVERSE_initialDepth, BEANTRAVERSE_maxDepth

Fields inherited from class org.apache.juneau.BeanContext

BEAN_beanClassVisibility, BEAN_beanConstructorVisibility, BEAN_beanDictionary, BEAN_beanDictionary_add, BEAN_beanDictionary_remove, BEAN_beanFieldVisibility, BEAN_beanFilters, BEAN_beanFilters_add, BEAN_beanFilters_remove, BEAN_beanMapPutReturnsOldValue, BEAN_beanMethodVisibility, BEAN_beansRequireDefaultConstructor, BEAN_beansRequireSerializable, BEAN_beansRequireSettersForGetters, BEAN_beansRequireSomeProperties, BEAN_beanTypePropertyName, BEAN_bpi, BEAN_bpro, BEAN_bpwo, BEAN_bpx, BEAN_debug, BEAN_examples, BEAN_excludeProperties, BEAN_fluentSetters, BEAN_ignoreInvocationExceptionsOnGetters, BEAN_ignoreInvocationExceptionsOnSetters, BEAN_ignorePropertiesWithoutSetters, BEAN_ignoreUnknownBeanProperties, BEAN_ignoreUnknownNullBeanProperties, BEAN_implClasses, BEAN_includeProperties, BEAN_locale, BEAN_mediaType, BEAN_notBeanClasses, BEAN_notBeanClasses_add, BEAN_notBeanClasses_remove, BEAN_notBeanPackages, BEAN_notBeanPackages_add, BEAN_notBeanPackages_remove, BEAN_pojoSwaps, BEAN_pojoSwaps_add, BEAN_pojoSwaps_remove, BEAN_propertyNamer, BEAN_sortProperties, BEAN_timeZone, BEAN_useEnumNames, BEAN_useInterfaceProxies, BEAN_useJavaBeanIntrospector, DEFAULT_SORTED

Constructor Summary

Constructors

Constructor and Description
UonSerializer(PropertyStore ps) Constructor.
UonSerializer(PropertyStore ps, String produces, String accept) Constructor.

Method Summary

Modifier and Type	Method and Description
UonSerializerBuilder	builder() Creates a builder from this context object.
static UonSerializerBuilder	create() Instantiates a new clean-slate UonSerializerBuilder object.
UonSerializerSession	createPartSession() Creates a new no-argument serializer session.
UonSerializerSession	createPartSession(SerializerSessionArgs args) Creates a new serializer session.
UonSerializerSession	createSession() Create a new bean session based on the properties defined on this context.
UonSerializerSession	createSession(SerializerSessionArgs args) Create the session object used for actual serialization of objects.
protected ParamFormat	getParamFormat() Configuration property: Format to use for query/form-data/header values.
protected boolean	isAddBeanTypes() Configuration property: Add "_type" properties when needed.
protected boolean	isEncoding() Configuration property: Encode non-valid URI characters.
String	serialize(HttpPartSchema schema, Object value) Convenience method for creating a no-arg session and serializing a part with no specified part type.
String	serialize(HttpPartType partType, HttpPartSchema schema, Object value) Convenience method for creating a no-arg session and serializing a part.
ObjectMap	toMap() Returns the properties defined on this bean context as a simple map for debugging purposes.

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

getFileCharset, getMaxIndent, getQuoteChar, getStreamCharset, isUseWhitespace, isWriterSerializer, println, serialize, toString, toStringObject

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

createDefaultSessionArgs, getAcceptMediaTypes, getListener, getMediaTypeRanges, getPrimaryMediaType, getResponseContentType, getUriContext, getUriRelativity, getUriResolution, isAddRootType, isSortCollections, isSortMaps, isTrimEmptyCollections, isTrimEmptyMaps, isTrimNullProperties, isTrimStrings, serialize, serializeToString

Methods inherited from class org.apache.juneau.BeanTraverseContext

createSession, getInitialDepth, getMaxDepth, isDetectRecursions, isIgnoreRecursions

Methods inherited from class org.apache.juneau.BeanContext

_class, createBeanSession, createBeanSession, createDefaultBeanSessionArgs, createSession, dumpCacheStats, getBeanClassVisibility, getBeanConstructorVisibility, getBeanDictionaryClasses, getBeanFieldVisibility, getBeanFilters, getBeanMeta, getBeanMethodVisibility, getBeanRegistry, getBeanTypePropertyName, getBpi, getBpi, getBpro, getBpro, getBpwo, getBpwo, getBpx, getBpx, getClassMeta, getClassMeta, getClassMetaForObject, getExamples, getImplClassConstructor, getImplClasses, getLocale, getMediaType, getNotBeanClasses, getNotBeanPackagesNames, getNotBeanPackagesPrefixes, getPojoSwaps, getPropertyNamer, getTimeZone, hasSameCache, isBean, isBeanMapPutReturnsOldValue, isBeansRequireDefaultConstructor, isBeansRequireSerializable, isBeansRequireSettersForGetters, isBeansRequireSomeProperties, isDebug, isFluentSetters, isIgnoreInvocationExceptionsOnGetters, isIgnoreInvocationExceptionsOnSetters, isIgnorePropertiesWithoutSetters, isIgnoreUnknownBeanProperties, isIgnoreUnknownNullBeanProperties, isNotABean, isSortProperties, isUseEnumNames, isUseInterfaceProxies, isUseJavaBeanIntrospector, object, resolveClassMeta, string

Methods inherited from class org.apache.juneau.Context

equals, getArrayProperty, getArrayProperty, getBooleanProperty, getCdlProperty, getClassArrayProperty, getClassArrayProperty, getClassArrayProperty, getClassListProperty, getClassListProperty, getClassMapProperty, getClassMapProperty, getClassProperty, getClassSetProperty, getClassSetProperty, getInstanceArrayProperty, getInstanceArrayProperty, getInstanceArrayProperty, getInstanceProperty, getInstanceProperty, getInstanceProperty, getIntegerProperty, getListProperty, getListProperty, getLongProperty, getMapProperty, getProperty, getProperty, getPropertyKeys, getPropertyStore, getSetProperty, getSetProperty, getStringProperty, getStringPropertyWithNone, hashCode, identityCode, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UON_addBeanTypes

public static final String UON_addBeanTypes

Configuration property: Add "_type" properties when needed.

Property:

• Name: "UonSerializer.addBeanTypes.b"
• Data type: Boolean
• Default: false
• Session property: false
• Methods:
  • UonSerializerBuilder.addBeanTypes(boolean)

Description:

If true, then "_type" properties will be added to beans if their type cannot be inferred through reflection.

When present, this value overrides the Serializer.SERIALIZER_addBeanTypes setting and is provided to customize the behavior of specific serializers in a SerializerGroup.

See Also:

Constant Field Values

UON_encoding

public static final String UON_encoding

Configuration property: Encode non-valid URI characters.

Property:

• Name: "UonSerializer.encoding.b"
• Data type: Boolean
• Default: false for UonSerializer, true for UrlEncodingSerializer
• Session property: false
• Methods:
  • UonSerializerBuilder.encoding(boolean)
  • UonSerializerBuilder.encoding()

Description:

Encode non-valid URI characters with "%xx" constructs.

If true, non-valid URI characters will be converted to "%xx" sequences.
Set to false if parameter value is being passed to some other code that will already perform URL-encoding of non-valid URI characters.

Example:

// Create a non-encoding UON serializer. UonSerializer s1 = UonSerializer. .create() .build(); // Create an encoding UON serializer. UonSerializer s2 = UonSerializer. .create() .encoding() .build(); ObjectMap m = new ObjectMap().append("foo", "foo bar"); // Produces: "(foo=foo bar)" String uon1 = s1.serialize(m) // Produces: "(foo=foo%20bar)" String uon2 = s2.serialize(m)

See Also:

Constant Field Values

UON_paramFormat

public static final String UON_paramFormat

Configuration property: Format to use for query/form-data/header values.

Property:

• Name: "UonSerializer.paramFormat.s"
• Data type: String (ParamFormat)
• Default: "UON"
• Session property: false
• Methods:
  • UonSerializerBuilder.paramFormat(ParamFormat)
  • UonSerializerBuilder.paramFormatPlain()

Description:

Specifies the format to use for URL GET parameter keys and values.

Possible values:

• ParamFormat.UON - Use UON notation for parameters.
• ParamFormat.PLAINTEXT - Use plain text for parameters.

Example:

// Create a normal UON serializer. UonSerializer s1 = UonSerializer. .create() .build(); // Create a plain-text UON serializer. UonSerializer s2 = UonSerializer. .create() .paramFormat(PLAIN_TEXT) .build(); ObjectMap m = new ObjectMap() .append("foo", "bar"); .append("baz", new String[]{"qux", "true", "123"}); // Produces: "(foo=bar,baz=@(qux,'true','123'))" String uon1 = s1.serialize(m) // Produces: "foo=bar,baz=qux,true,123" String uon2 = s2.serialize(m)

See Also:

Constant Field Values

DEFAULT

public static final UonSerializer DEFAULT

Reusable instance of UonSerializer, all default settings.

DEFAULT_READABLE

public static final UonSerializer DEFAULT_READABLE

Reusable instance of UonSerializer.Readable.

DEFAULT_ENCODING

public static final UonSerializer DEFAULT_ENCODING

Reusable instance of UonSerializer.Encoding.

Constructor Detail

UonSerializer

public UonSerializer(PropertyStore ps)

Constructor.

Parameters:

ps - The property store containing all the settings for this object.

UonSerializer

public UonSerializer(PropertyStore ps,
                     String produces,
                     String accept)

Constructor.

Parameters:

ps - The property store containing all the settings for this object.

produces - The media type that this serializer produces.

accept - The accept media types that the serializer can handle.

Can contain meta-characters per the media-type specification of RFC2616/14.1

If empty, then assumes the only media type supported is produces.

For example, if this serializer produces "application/json" but should handle media types of "application/json" and "text/json", then the arguments should be:

super(ps, "application/json", "application/json,text/json");

...or...

super(ps, "application/json", "*/json");

The accept value can also contain q-values.

Method Detail

builder

public UonSerializerBuilder builder()

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:

builder in class Serializer

Returns:

A new ContextBuilder object.

create

public static UonSerializerBuilder create()

Instantiates a new clean-slate UonSerializerBuilder object.

This is equivalent to simply calling new UonSerializerBuilder().

Note that this method creates a builder initialized to all default settings, whereas builder() copies the settings of the object called on.

Returns:

A new UonSerializerBuilder object.

createSession

public UonSerializerSession createSession()

Description copied from class: BeanContext

Create a new bean session based on the properties defined on this context.

Use this method for creating sessions if you don't need to override any properties or locale/timezone currently set on this context.

Overrides:

createSession in class WriterSerializer

Returns:

A new session object.

createSession

public UonSerializerSession createSession(SerializerSessionArgs args)

Description copied from class: Serializer

Create the session object used for actual serialization of objects.

Specified by:

createSession in class WriterSerializer

Parameters:

args - Runtime arguments. These specify session-level information such as locale and URI context. It also include session-level properties that override the properties defined on the bean and serializer contexts.

Returns:

The new session object.

createPartSession

public UonSerializerSession createPartSession(SerializerSessionArgs args)

Description copied from interface: HttpPartSerializer

Creates a new serializer session.

Specified by:

createPartSession in interface HttpPartSerializer

Parameters:

args - The runtime arguments for the session.

Returns:

A new serializer session.

createPartSession

public UonSerializerSession createPartSession()

Description copied from interface: HttpPartSerializer

Creates a new no-argument serializer session.

Specified by:

createPartSession in interface HttpPartSerializer

Returns:

A new serializer session.

serialize

public String serialize(HttpPartType partType,
                        HttpPartSchema schema,
                        Object value)
                 throws SchemaValidationException,
                        SerializeException

Description copied from interface: HttpPartSerializer

Convenience method for creating a no-arg session and serializing a part.

Specified by:

serialize in interface HttpPartSerializer

Parameters:

partType - The category of value being serialized.

schema - Schema information about the part.
May be null.
Not all part serializer use the schema information.

value - The value being serialized.

Returns:

The serialized value.

Throws:

SchemaValidationException - If the output fails schema validation.

SerializeException - If a problem occurred while trying to parse the input.

serialize

public String serialize(HttpPartSchema schema,
                        Object value)
                 throws SchemaValidationException,
                        SerializeException

Description copied from interface: HttpPartSerializer

Convenience method for creating a no-arg session and serializing a part with no specified part type.

Specified by:

serialize in interface HttpPartSerializer

Parameters:

schema - Schema information about the part.
May be null.
Not all part serializer use the schema information.

value - The value being serialized.

Returns:

The serialized value.

Throws:

SchemaValidationException - If the output fails schema validation.

SerializeException - If a problem occurred while trying to parse the input.

isAddBeanTypes

protected final boolean isAddBeanTypes()

Configuration property: Add "_type" properties when needed.

Overrides:

isAddBeanTypes in class Serializer

Returns:

true if "_type" properties will be added to beans if their type cannot be inferred through reflection.

See Also:

UON_addBeanTypes

isEncoding

protected final boolean isEncoding()

Configuration property: Encode non-valid URI characters.

Returns:

true if non-valid URI characters should be encoded with "%xx" constructs.

See Also:

UON_encoding

getParamFormat

protected final ParamFormat getParamFormat()

Configuration property: Format to use for query/form-data/header values.

Returns:

Specifies the format to use for URL GET parameter keys and values.

See Also:

UON_paramFormat

toMap

public ObjectMap toMap()

Description copied from class: Context

Returns the properties defined on this bean context as a simple map for debugging purposes.

Overrides:

toMap in class WriterSerializer

Returns:

A new map containing the properties defined on this context.