org.apache.juneau.urlencoding

Class UrlEncodingSerializer

java.lang.Object

org.apache.juneau.Context

org.apache.juneau.BeanContext

org.apache.juneau.serializer.Serializer

org.apache.juneau.serializer.WriterSerializer

org.apache.juneau.uon.UonSerializer

org.apache.juneau.urlencoding.UrlEncodingSerializer

Direct Known Subclasses:

UrlEncodingSerializer.Expanded, UrlEncodingSerializer.PlainText, UrlEncodingSerializer.Readable

public class UrlEncodingSerializer
extends UonSerializer

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

Media types:

Handles Accept types: application/x-www-form-urlencoded

Produces Content-Type types: application/x-www-form-urlencoded

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 URL-encoded 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 = UrlEncodingSerializer.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 = UrlEncodingSerializer.DEFAULT.serialize(s);

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UrlEncodingSerializer.Expanded Equivalent to UrlEncodingSerializer.create().expandedParams().build();.
static class	UrlEncodingSerializer.PlainText Equivalent to UrlEncodingSerializer.create().plainTextParts().build();.
static class	UrlEncodingSerializer.Readable Equivalent to UrlEncodingSerializer.create().useWhitespace().build();.

Nested classes/interfaces inherited from class org.apache.juneau.uon.UonSerializer

UonSerializer.Encoding

Field Summary

Fields

Modifier and Type	Field and Description
static UrlEncodingSerializer	DEFAULT Reusable instance of UrlEncodingSerializer, all default settings.
static UrlEncodingSerializer	DEFAULT_EXPANDED Reusable instance of UrlEncodingSerializer.Expanded.
static UrlEncodingSerializer	DEFAULT_PLAINTEXT Reusable instance of UrlEncodingSerializer.PlainText.
static UrlEncodingSerializer	DEFAULT_READABLE Reusable instance of UrlEncodingSerializer.Readable.
static String	URLENC_expandedParams Configuration property: Serialize bean property collections/arrays as separate key/value pairs.

Fields inherited from class org.apache.juneau.uon.UonSerializer

DEFAULT_ENCODING, UON_addBeanTypeProperties, UON_encoding, UON_paramFormat

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

SERIALIZER_abridged, SERIALIZER_addBeanTypeProperties, SERIALIZER_detectRecursions, SERIALIZER_ignoreRecursions, SERIALIZER_initialDepth, SERIALIZER_listener, SERIALIZER_maxDepth, SERIALIZER_maxIndent, SERIALIZER_quoteChar, SERIALIZER_sortCollections, SERIALIZER_sortMaps, SERIALIZER_trimEmptyCollections, SERIALIZER_trimEmptyMaps, SERIALIZER_trimNullProperties, SERIALIZER_trimStrings, SERIALIZER_uriContext, SERIALIZER_uriRelativity, SERIALIZER_uriResolution, SERIALIZER_useWhitespace

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_debug, BEAN_excludeProperties, 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_useInterfaceProxies, BEAN_useJavaBeanIntrospector, DEFAULT_SORTED

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
ObjectMap	asMap() Returns the properties defined on this bean context as a simple map for debugging purposes.
UrlEncodingSerializerBuilder	builder() Creates a builder from this context object.
static UrlEncodingSerializerBuilder	create() Instantiates a new clean-slate UrlEncodingSerializerBuilder object.
WriterSerializerSession	createSession(SerializerSessionArgs args) Create the session object used for actual serialization of objects.

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

isWriterSerializer, println, serialize, toString, toStringObject

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

createDefaultSessionArgs, createSession, getMediaTypes, getResponseContentType, serialize

Methods inherited from class org.apache.juneau.BeanContext

_class, createBeanSession, createBeanSession, createDefaultBeanSessionArgs, createSession, createSession, dumpCacheStats, getBeanMeta, getBeanRegistry, getBeanTypePropertyName, getClassMeta, getClassMeta, getClassMetaForObject, getExcludeProperties, getImplClassConstructor, getIncludeProperties, hasSameCache, isBean, isNotABean, newInstance, newInstance, newInstanceFromOuter, object, resolveClassMeta, string

Methods inherited from class org.apache.juneau.Context

equals, getArrayProperty, getArrayProperty, getBooleanProperty, 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, hashCode, toString

Methods inherited from class java.lang.Object

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

Field Detail

URLENC_expandedParams

public static final String URLENC_expandedParams

Configuration property: Serialize bean property collections/arrays as separate key/value pairs.

Property:

• Name: "UrlEncodingSerializer.expandedParams.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • UrlEncodingSerializerBuilder.expandedParams(boolean)
  • UrlEncodingSerializerBuilder.expandedParams()

Description:

If false, serializing the array [1,2,3] results in ?key=$a(1,2,3).
If true, serializing the same array results in ?key=1&key=2&key=3.

This option only applies to beans.

Notes:

• If parsing multi-part parameters, it's highly recommended to use Collections or Lists as bean property types instead of arrays since arrays have to be recreated from scratch every time a value is added to it.

Example:

// A sample bean. public class A { public String[] f1 = {"a","b"}; public List<String> f2 = Arrays.asList(new String[]{"c","d"}); } // Normal serializer. WriterSerializer s1 = UrlEncodingSerializer.DEFAULT; // Expanded-params serializer. WriterSerializer s2 = UrlEncodingSerializer.create().expandedParams().build(); // Produces "f1=(a,b)&f2=(c,d)" String ss1 = s1.serialize(new A()); // Produces "f1=a&f1=b&f2=c&f2=d" String ss2 = s2.serialize(new A());

See Also:

Constant Field Values

DEFAULT

public static final UrlEncodingSerializer DEFAULT

Reusable instance of UrlEncodingSerializer, all default settings.

DEFAULT_PLAINTEXT

public static final UrlEncodingSerializer DEFAULT_PLAINTEXT

Reusable instance of UrlEncodingSerializer.PlainText.

DEFAULT_EXPANDED

public static final UrlEncodingSerializer DEFAULT_EXPANDED

Reusable instance of UrlEncodingSerializer.Expanded.

DEFAULT_READABLE

public static final UrlEncodingSerializer DEFAULT_READABLE

Reusable instance of UrlEncodingSerializer.Readable.

Constructor Detail

UrlEncodingSerializer

public UrlEncodingSerializer(PropertyStore ps)

Constructor.

Parameters:

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

UrlEncodingSerializer

public UrlEncodingSerializer(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");

Method Detail

builder

public UrlEncodingSerializerBuilder 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 UonSerializer

Returns:

A new ContextBuilder object.

create

public static UrlEncodingSerializerBuilder create()

Instantiates a new clean-slate UrlEncodingSerializerBuilder object.

This is equivalent to simply calling new UrlEncodingSerializerBuilder().

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 UrlEncodingSerializerBuilder object.

createSession

public WriterSerializerSession createSession(SerializerSessionArgs args)

Description copied from class: Serializer

Create the session object used for actual serialization of objects.

Overrides:

createSession in class UonSerializer

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.

asMap

public ObjectMap asMap()

Description copied from class: Context

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

Overrides:

asMap in class UonSerializer

Returns:

A new map containing the properties defined on this context.