org.apache.juneau.uon.UonSerializer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of juneau-all
Apache Juneau UberJar
There is a newer version: 9.0.1
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
// * with the License.  You may obtain a copy of the License at                                                              *
// *                                                                                                                         *
// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
// *                                                                                                                         *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
// * specific language governing permissions and limitations under the License.                                              *
// ***************************************************************************************************************************
package org.apache.juneau.uon;

import org.apache.juneau.*;
import org.apache.juneau.serializer.*;
import org.apache.juneau.urlencoding.*;

/**
 * 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);
 * 
 */
public class UonSerializer extends WriterSerializer {

	//-------------------------------------------------------------------------------------------------------------------
	// Configurable properties
	//-------------------------------------------------------------------------------------------------------------------

	private static final String PREFIX = "UonSerializer.";

	/**
	 * Configuration property:  Encode non-valid URI characters.
	 *
	 * 
	 * 	Name: "UonSerializer.encodeChars"
	 * 	
Data type: Boolean
	 * 	
Default: false for {@link UonSerializer}, true for {@link UrlEncodingSerializer}
	 * 	
Session-overridable: true
	 * 
	 *
	 * 
	 * 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.
	 */
	public static final String UON_encodeChars = PREFIX + "encodeChars";

	/**
	 * Configuration property:  Add "_type" properties when needed.
	 *
	 * 

	 * 	Name: "UonSerializer.addBeanTypeProperties"
	 * 	
Data type: Boolean
	 * 	
Default: false
	 * 	
Session-overridable: true
	 * 
	 *
	 * 
	 * If true, then "_type" properties will be added to beans if their type cannot be inferred
	 * through reflection.
	 * This is used to recreate the correct objects during parsing if the object types cannot be inferred.
	 * For example, when serializing a {@code Map} field, where the bean class cannot be determined from
	 * the value type.
	 *
	 * 

	 * When present, this value overrides the {@link #SERIALIZER_addBeanTypeProperties} setting and is
	 * provided to customize the behavior of specific serializers in a {@link SerializerGroup}.
	 */
	public static final String UON_addBeanTypeProperties = PREFIX + "addBeanTypeProperties";

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

	 * 	Name: "UrlEncodingSerializer.paramFormat"
	 * 	
Data type: ParamFormat
	 * 	
Default: UON
	 * 	
Session-overridable: true
	 * 
	 *
	 * 
	 * Specifies the format to use for URL GET parameter keys and values.
	 */
	public static final String UON_paramFormat = PREFIX + "paramFormat";


	//-------------------------------------------------------------------------------------------------------------------
	// Predefined instances
	//-------------------------------------------------------------------------------------------------------------------

	/** Reusable instance of {@link UonSerializer}, all default settings. */
	public static final UonSerializer DEFAULT = new UonSerializer(PropertyStore.create());

	/** Reusable instance of {@link UonSerializer.Readable}. */
	public static final UonSerializer DEFAULT_READABLE = new Readable(PropertyStore.create());

	/** Reusable instance of {@link UonSerializer.Encoding}. */
	public static final UonSerializer DEFAULT_ENCODING = new Encoding(PropertyStore.create());


	//-------------------------------------------------------------------------------------------------------------------
	// Predefined subclasses
	//-------------------------------------------------------------------------------------------------------------------

	/**
	 * Equivalent to new UonSerializerBuilder().ws().build();.
	 */
	public static class Readable extends UonSerializer {

		/**
		 * Constructor.
		 *
		 * @param propertyStore The property store containing all the settings for this object.
		 */
		public Readable(PropertyStore propertyStore) {
			super(propertyStore.copy().append(SERIALIZER_useWhitespace, true));
		}
	}

	/**
	 * Equivalent to new UonSerializerBuilder().encoding().build();.
	 */
	public static class Encoding extends UonSerializer {

		/**
		 * Constructor.
		 *
		 * @param propertyStore The property store containing all the settings for this object.
		 */
		public Encoding(PropertyStore propertyStore) {
			super(propertyStore.copy().append(UON_encodeChars, true));
		}
	}


	//-------------------------------------------------------------------------------------------------------------------
	// Instance
	//-------------------------------------------------------------------------------------------------------------------

	private final UonSerializerContext ctx;

	/**
	 * Constructor.
	 *
	 * @param propertyStore
	 * 	The property store containing all the settings for this object.
	 */
	public UonSerializer(PropertyStore propertyStore) {
		this(propertyStore, "text/uon");
	}

	/**
	 * Constructor.
	 *
	 * @param propertyStore
	 * 	The property store containing all the settings for this object.
	 * @param produces
	 * 	The media type that this serializer produces.
	 * @param 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(propertyStore, "application/json", "application/json", "text/json");
	 * 	
...or...
	 * 	
super(propertyStore, "application/json", "*/json");
	 */
	public UonSerializer(PropertyStore propertyStore, String produces, String...accept) {
		super(propertyStore, produces, accept);
		this.ctx = createContext(UonSerializerContext.class);
	}

	@Override /* CoreObject */
	public UonSerializerBuilder builder() {
		return new UonSerializerBuilder(propertyStore);
	}



	//--------------------------------------------------------------------------------
	// Entry point methods
	//--------------------------------------------------------------------------------

	@Override /* Serializer */
	public WriterSerializerSession createSession(SerializerSessionArgs args) {
		return new UonSerializerSession(ctx, null, args);
	}
}