juneau-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jamesbog...@apache.org
Subject [1/2] juneau git commit: Javadoc updates.
Date Tue, 09 Jan 2018 03:32:48 GMT
Repository: juneau
Updated Branches:
  refs/heads/master cea2a1d74 -> 474a143ce


http://git-wip-us.apache.org/repos/asf/juneau/blob/474a143c/juneau-doc/src/main/javadoc/overview.html
----------------------------------------------------------------------
diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html
index 64797e8..375a2ef 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -92,9 +92,21 @@
 			<li><p><a class='doclink' href='#juneau-marshall.Transforms'>Transforms</a></p>
 			<ol>
 				<li><p><a class='doclink' href='#juneau-marshall.PojoSwaps'>PojoSwaps</a></p>
-				<li><p><a class='doclink' href='#juneau-marshall.SwapAnnotation'>@Swap annotation</a></p>
-				<li><p><a class='doclink' href='#juneau-marshall.SwapMethods'>Swap methods</a></p>
-				<li><p><a class='doclink' href='#juneau-marshall.BeanFilters'>BeanFilters and @Bean annotations</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.PerMediaTypePojoSwaps'>Per-media-type PojoSwaps</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.OneWayPojoSwaps'>One-way PojoSwaps</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.SwapAnnotation'>@Swap Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.SwapMethods'>Swap Methods</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.SurrogateClasses'>Surrogate Classes</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.BeanAnnotation'>@Bean Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.BeanPropertyAnnotation'>@BeanProperty Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.BeanConstructorAnnotation'>@BeanConstructor Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.BeanIgnoreAnnotation'>@BeanIgnore Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.NamePropertyAnnotation'>@NameProperty Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.ParentPropertyAnnotation'>@ParentProperty Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.URIAnnotation'>@URI Annotation</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.BeanFilters'>BeanFilters</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.StopClasses'>Stop Classes</a></p>
+				<li><p><a class='doclink' href='#juneau-marshall.SerializingToObjectMaps'>Serializing to ObjectMaps</a></p>
 				<li><p><a class='doclink' href='#juneau-marshall.SerializingReadersAndInputStreams'>Serializing Readers and InputStreams</a></p>
 			</ol>
 			<li><p><a class='doclink' href='#juneau-marshall.BeanDictionaries'>Bean Name and Dictionaries</a></p>
@@ -971,22 +983,33 @@
 		<h4 class='topic' onclick='toggle(this)'>2.1.6 - Transforms</h4>
 		<div class='topic'>
 			<p>
-				By default, the Juneau framework can serialize and parse a wide variety of POJOs out-of-the-box. 
-				However, two special classes are provided tailor how certain Java objects are handled by the framework. 
-				These classes are:
+				By default, the Juneau framework can serialize and parse a wide variety of POJOs out-of-the-box.  
+				<br>However, two special classes are provided tailor how certain Java objects are handled by the framework.
+				<br>These classes are:
 			</p>
-			<ul class='doctree'>
-				<li class='jc'>
-					{@link org.apache.juneau.transform.PojoSwap} 
-					- Tailor how specific non-bean classes are handled by the framework.
-				<li class='jc'>
-					{@link org.apache.juneau.transform.BeanFilter} 
-					- Tailor how specific bean classes are handled by the framework.
+			<ul>
+				<li class='jc'>{@link org.apache.juneau.transform.BeanFilter} - Transforms that alter the way beans are handled.
+				<li class='jac'>{@link org.apache.juneau.transform.PojoSwap} - Transforms that swap non-serializable POJOs with 
+					serializable POJOs during serialization (and optionally vis-versa during parsing).
+					<ol>
+						<li class='jc'>{@link org.apache.juneau.transform.StringSwap} - Convenience subclass for swaps that convert 
+							objects to strings.
+						<li class='jc'>{@link org.apache.juneau.transform.MapSwap} - Convenience subclass for swaps that convert 
+							objects to maps.
+					</ol>
+				</li>
 			</ul>
 			<p>
-				Annotations are also provided that allow you to use transformations directly on class definitions:
+				Transforms are added to serializers and parsers (and REST clients) using the following configuration properties:
+			</p> 
+			<ul>
+				<li class='jm'>{@link org.apache.juneau.BeanContext#BEAN_beanFilters}
+				<li class='jm'>{@link org.apache.juneau.BeanContext#BEAN_pojoSwaps}
+			</ul>
+			<p>
+				Annotations are also provided for specifying transforms directly on classes and methods:
 			</p>
-			<ul class='doctree'>
+			<ul>
 				<li class='ja'>
 					{@link org.apache.juneau.annotation.Swap @Swap} 
 					- Used to tailor how non-bean POJOs get interpreted by the framework.
@@ -1022,8 +1045,7 @@
 					They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.
 				</p>
 				<p>
-					Swaps are very easy to understand.
-					Simply put, they can be thought of as 'object swappers' that swap in serializable objects for 
+					Swaps are, simply put, 'object swappers' that swap in serializable objects for 
 					non-serializable ones during serialization, and vis-versa during parsing.
 				</p>
 				<p>
@@ -1050,12 +1072,8 @@
 		
 		<jd>/** Converts an ISO8601 string to a Date object. */</jd>
 		<ja>@Override</ja>
-		<jk>public</jk> Date unswap(BeanSession session, String o, ClassMeta hint) <jk>throws</jk> ParseException {
-			<jk>try</jk> {
-				<jk>return</jk> <jf>format</jf>.parse(o);
-			} <jk>catch</jk> (java.text.ParseException e) {
-				<jk>throw new</jk> ParseException(e);
-			}
+		<jk>public</jk> Date unswap(BeanSession session, String o, ClassMeta hint) <jk>throws</jk> Exception {
+			<jk>return</jk> <jf>format</jf>.parse(o);
 		}
 	}
 				</p>
@@ -1069,14 +1087,82 @@
 	}
 
 	<jc>// Create a new JSON serializer, associate our date swap with it, and serialize a sample bean.</jc>
-	Serializer serializer = JsonSerializer.<jsm>create</jsm>().pojoSwaps(MyDateSwap.<jk>class</jk>).build();
-	String json = serializer.serialize(<jk>new</jk> MyBean());	<jc>// == "{date:'2012-03-03T04:05:06-0500'}"</jc>
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().simple().pojoSwaps(MyDateSwap.<jk>class</jk>).build();
+	String json = s.serialize(<jk>new</jk> MyBean());	<jc>// == "{date:'2012-03-03T04:05:06-0500'}"</jc>
 	
 	<jc>// Create a JSON parser, associate our date swap with it, and reconstruct our bean (including the date).</jc>
-	ReaderParser parser = JsonParser.<jsm>create</jsm>().pojoSwaps(MyDateSwap.<jk>class</jk>).build();
-	MyBean bean = parser.parse(json, MyBean.<jk>class</jk>);
+	ReaderParser p = JsonParser.<jsm>create</jsm>().pojoSwaps(MyDateSwap.<jk>class</jk>).build();
+	MyBean bean = p.parse(json, MyBean.<jk>class</jk>);
 	<jk>int</jk> day = bean.<jf>date</jf>.getDay(); 						<jc>// == 3</jc>
 				</p>
+			<p>
+				The {@link org.apache.juneau.BeanMap#get(Object)} and {@link org.apache.juneau.BeanMap#put(String,Object)} 
+				methods will automatically convert to swapped values as the following example shows:
+			</p>
+			<p class='bcode'>
+	<jc>// Create a new bean context and add our swap.</jc>
+	BeanContext bc = BeanContext.<jsm>create</jsm>().pojoSwaps(MyDateSwap.<jk>class</jk>).build();
+
+	<jc>// Create a new bean.</jc>
+	MyBean myBean = <jk>new</jk> MyBean();
+
+	<jc>// Wrap it in a bean map.</jc>
+	BeanMap&lt;Bean&gt; beanMap = bc.forBean(myBean);
+
+	<jc>// Use the get() method to get the date field as an ISO8601 string.</jc>
+	String date = (String)beanMap.get(<js>"date"</js>);				<jc>// == "2012-03-03T04:05:06-0500"</jc> 
+	
+	<jc>// Use the put() method to set the date field to an ISO8601 string.</jc>
+	beanMap.put(<js>"date"</js>, <js>"2013-01-01T12:30:00-0500"</js>);	<jc>// Set it to a new value.</jc> 
+	
+	<jc>// Verify that the date changed on the original bean.</jc>
+	<jk>int</jk> year = myBean.<jf>date</jf>.getYear(); 								<jc>// == 113</jc>
+			</p>
+			<p>
+				Another example of a <code>PojoSwap</code> is one that converts <code><jk>byte</jk>[]</code> arrays to '
+				BASE64-encoded strings:
+			</p>
+			<p class='bcode'>
+	<jk>public class</jk> ByteArrayBase64Swap <jk>extends</jk> StringSwap&lt;<jk>byte</jk>[]&gt; {
+	
+		<ja>@Override</ja>
+		<jk>public</jk> String swap(<jk>byte</jk>[] b) <jk>throws</jk> Exception {
+			ByteArrayOutputStream baos = <jk>new</jk> ByteArrayOutputStream();
+			OutputStream b64os = MimeUtility.encode(baos, <js>"base64"</js>);
+			b64os.write(b);
+			b64os.close();
+			<jk>return new</jk> String(baos.toByteArray());
+		}
+		
+		<ja>@Override</ja>
+		<jk>public byte</jk>[] unswap(String s, ClassMeta&lt;?&gt; hint) <jk>throws</jk> Exception {
+			<jk>byte</jk>[] b = s.getBytes();
+			ByteArrayInputStream bais = <jk>new</jk> ByteArrayInputStream(b);
+			InputStream b64is = MimeUtility.decode(bais, <js>"base64"</js>);
+			<jk>byte</jk>[] tmp = <jk>new byte</jk>[b.length];
+			<jk>int</jk> n = b64is.read(tmp);
+			<jk>byte</jk>[] res = <jk>new byte</jk>[n];
+			System.<jsm>arraycopy</jsm>(tmp, 0, res, 0, n);
+			<jk>return</jk> res;
+		}
+	}
+				</p>
+				<p>
+					The following example shows the BASE64 swap in use:
+				</p>
+				<p class='bcode'>
+	<jc>// Create a JSON serializer and register the BASE64 encoding swap with it.</jc>
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().simple().pojoSwaps(ByteArrayBase64Swap.<jk>class</jk>).build();
+	ReaderParser p = JsonParser.<jsm>create</jsm>().pojoSwaps(ByteArrayBase64Swap.<jk>class</jk>).build();
+	
+	<jk>byte</jk>[] bytes = {1,2,3};
+	String json = s.serialize(bytes);		<jc>// Produces "'AQID'"</jc>
+	bytes = p.parse(json, <jk>byte</jk>[].<jk>class</jk>);		<jc>// Reproduces {1,2,3}</jc>
+	
+	<jk>byte</jk>[][] bytes2d = {{1,2,3},{4,5,6},<jk>null</jk>};
+	json = s.serialize(bytes2d);		<jc>// Produces "['AQID','BAUG',null]"</jc>
+	bytes2d = p.parse(json, <jk>byte</jk>[][].<jk>class</jk>);		<jc>// Reproduces {{1,2,3},{4,5,6},null}</jc>
+				</p>
 				<p>
 					Several <code>PojoSwaps</code> are already provided for common Java objects:
 				</p>
@@ -1106,14 +1192,25 @@
 					{@link org.apache.juneau.transforms.DateSwap} transforms provide a large number of customized swaps to 
 					ISO, RFC, or localized strings.
 				</p>
-	
+				
+				<ul class='doctree'>
+					<li class='info'>
+						The 'swapped' class type must be a serializable type.
+						<br>See the definition for Category 4 objects in <a class='doclink' href='#juneau-marshall.PojoCategories'>POJO Categories</a>.  
+				</ul>
+			</div>
+			
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.PerMediaTypePojoSwaps"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.2 - Per-media-type PojoSwaps</h4>
+			<div class='topic'>
 				<p>
 					Swaps can also be defined per-media-type.			
-					The {@link org.apache.juneau.transform.PojoSwap#forMediaTypes()} method can be overridden to 
+					<br>The {@link org.apache.juneau.transform.PojoSwap#forMediaTypes()} method can be overridden to 
 					provide a set of media types that the swap is invoked on.
-					It's also possible to define multiple swaps against the same POJO as long as they're differentiated 
+					<br>It's also possible to define multiple swaps against the same POJO as long as they're differentiated 
 					by media type.
-					When multiple swaps are defined, the best-match media type is used.
+					<br>When multiple swaps are defined, the best-match media type is used.
 				</p>
 				<p>
 					In the following example, we define 3 swaps against the same POJO.  
@@ -1125,33 +1222,33 @@
 		<jk>public static class</jk> MyPojo {}
 
 		<jk>public static class</jk> MyJsonSwap <jk>extends</jk> PojoSwap&lt;MyPojo,String&gt; {
-
+			<ja>@Override</ja>
 			<jk>public</jk> MediaType[] forMediaTypes() {
 				<jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"&#42;/json"</js>);
 			}
-
+			<ja>@Override</ja>
 			<jk>public</jk> String swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception {
 				<jk>return</jk> <js>"It's JSON!"</js>;
 			}
 		}
 
 		<jk>public static class</jk> MyXmlSwap <jk>extends</jk> PojoSwap&lt;MyPojo,String&gt; {
-
+			<ja>@Override</ja>
 			<jk>public</jk> MediaType[] forMediaTypes() {
 				<jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"&#42;/xml"</js>);
 			}
-
+			<ja>@Override</ja>
 			<jk>public</jk> String swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception {
 				<jk>return</jk> <js>"It's XML!"</js>;
 			}
 		}
 
 		<jk>public static class</jk> MyOtherSwap <jk>extends</jk> PojoSwap&lt;MyPojo,String&gt; {
-
+			<ja>@Override</ja>
 			<jk>public</jk> MediaType[] forMediaTypes() {
 				<jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"&#42;/*"</js>);
 			}
-
+			<ja>@Override</ja>
 			<jk>public</jk> String swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception {
 				<jk>return</jk> <js>"It's something else!"</js>;
 			}
@@ -1179,23 +1276,68 @@
 		}
 	}
 				</p>
-				
-				<ul class='doctree'>
-					<li class='info'>
-						The 'swapped' class type must be a serializable type.
-						<br>See the definition for Category 4 objects in <a class='doclink' 
-						href='#juneau-marshall.PojoCategories'>POJO Categories</a>.  
-				</ul>
 			</div>
 	
 			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.OneWayPojoSwaps"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.3 - One-way PojoSwaps</h4>
+			<div class='topic'>
+				<p>
+					In the previous sections, we defined two-way swaps, meaning swaps where the original objects could be 
+					reconstructing during parsing. 
+					<br>However, there are certain kinds of POJOs that we may want to support for serializing, but that are not 
+					possible to reconstruct during parsing.  
+					<br>For these, we can use one-way object swaps.
+				</p>
+				<p>
+					A one-way POJO swap is simply an object transform that only implements the {@code swap()} method.  
+					<br>The {@code unswap()} method is simply left unimplemented.
+				</p>
+				<p>
+					An example of a one-way swaps would be one that allows {@code Iterators} to be serialized as JSON arrays.  
+					<br>It can make sense to be able to render {@code Iterators} as arrays, but in general it's not possible to 
+					reconstruct an {@code Iterator} during parsing. 
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> IteratorSwap <jk>extends</jk> PojoSwap&lt;Iterator,List&gt; {
+		<ja>@Override</ja>
+		<jk>public</jk> List swap(Iterator o) {
+			List l = <jk>new</jk> LinkedList();
+			<jk>while</jk> (o.hasNext())
+				l.add(o.next());
+			<jk>return</jk> l;
+		}
+	}
+				</p>
+				<p>
+					Here is an example of our one-way swap being used.  
+					<br>Note that trying to parse the original object will cause a {@link org.apache.juneau.parser.ParseException} 
+					to be thrown.
+				</p>
+				<p class='bcode'>
+	<jc>// Create a JSON serializer that can serialize Iterators.</jc>
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().simple().pojoSwaps(IteratorSwap.<jk>class</jk>).build();
+	
+	<jc>// Construct an iterator we want to serialize.</jc>
+	Iterator i = <jk>new</jk> ObjectList(1,2,3).iterator();
+	
+	<jc>// Serialize our Iterator</jc>
+	String json = s.serialize(i);		<jc>// Produces "[1,2,3]"</jc>
+	
+	<jc>// Try to parse it.</jc>
+	ReaderParser p = JsonParser.<jsm>create</jsm>().pojoSwaps(IteratorSwap.<jk>class</jk>).build();
+	i = p.parse(s, Iterator.<jk>class</jk>);		<jc>// Throws ParseException!!!</jc>
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
 			<a id="juneau-marshall.SwapAnnotation"></a>
-			<h4 class='topic' onclick='toggle(this)'>2.1.6.2 - @Swap annotation</h4>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.4 - @Swap Annotation</h4>
 			<div class='topic'>
 				<p>
 					{@link org.apache.juneau.annotation.Swap @Swap} can be used to associate a swap class using an 
 					annotation.
-					This is often cleaner than using the builder <code>pojoSwaps()</code> method since you can keep
+					<br>This is often cleaner than using the builder <code>pojoSwaps()</code> method since you can keep
 					your swap class near your POJO class. 
 				</p>
 				<p class='bcode'>
@@ -1213,7 +1355,6 @@
 		}
 	}
 				</p>
-				
 				<p>
 					Multiple swaps can be associated with a POJO by using the {@link org.apache.juneau.annotation.Swaps @Swaps} annotation:
 				</p>
@@ -1243,16 +1384,15 @@
 		}
 	}
 				</p>
-				
 			</div>
 
 			<!-- ======================================================================================================= -->
 			<a id="juneau-marshall.SwapMethods"></a>
-			<h4 class='topic' onclick='toggle(this)'>2.1.6.3 - Swap methods</h4>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.5 - Swap Methods</h4>
 			<div class='topic'>
 				<p>
 					Various methods can be defined on a class directly to affect how it gets serialized.
-					This can often be simpler than using <code>PojoSwaps</code>.
+					<br>This can often be simpler than using <code>PojoSwaps</code>.
 				</p>
 				<p>
 					Objects serialized as <code>Strings</code> can be parsed back into their original objects by 
@@ -1303,7 +1443,7 @@
 				<p>
 					The <code>BeanSession</code> parameter allows you access to various information about the current 
 					serialization session.
-					For example, you could provide customized results based on the media type being produced 
+					<br>For example, you could provide customized results based on the media type being produced 
 					({@link org.apache.juneau.BeanSession#getMediaType()}).
 				</p>
 				<p>
@@ -1388,40 +1528,572 @@
 		}
 	}
 				</p>
-				
-				<h6 class='toc'>Additional Information - org.apache.juneau.transform</h6>
-				<ol class='toc'>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#PojoSwaps'>PojoSwap Class</a></p>
-				</ol>
-				
 			</div>
 	
-			<!-- ======================================================================================================= -->
-			<a id="juneau-marshall.BeanFilters"></a>
-			<h4 class='topic' onclick='toggle(this)'>2.1.6.4 - BeanFilters and @Bean annotations</h4>
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.SurrogateClasses"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.6 - Surrogate Classes</h4>
 			<div class='topic'>
 				<p>
-					{@link org.apache.juneau.transform.BeanFilter BeanFilters} are used to control aspects of how beans are 
-					handled during serialization and parsing.
-					They allow you to control various aspects of beans, such as...
+				<p>
+					Surrogate classes are very similar in concept to one-way <code>PojoSwaps</code> except they represent a 
+					simpler syntax.
 				</p>
-				<ul>
-					<li>Which properties to include or exclude.
-					<li>Property order.
-					<li>Property naming conventions.
-					<li>Overriding reading and writing of properties.
-				</ul>
 				<p>
-					In practice, however, it's simpler to use the {@link org.apache.juneau.annotation.Bean @Bean} and 
-					{@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotations on your bean classes.
-					The annotations are functionally equivalent to the bean filter class.
+					For example, let's say we want to be able to serialize the following class, but it's not serializable for 
+					some reason (for example, there are no properties exposed):  
+				<p class='bcode'>
+	<jk>public class</jk> MyNonSerializableClass {
+		<jk>protected</jk> String <jf>foo</jf>;
+	}
+				</p>
+				<p>
+					This could be solved with the following <code>PojoSwap</code>.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> MySerializableSurrogate {
+		<jk>public</jk> String <jf>foo</jf>;
+	}
+		
+	<jk>public class</jk> MySwap <jk>extends</jk> PojoSwap&lt;MyNonSerializableClass,MySerializableSurrogate&gt; {
+		<ja>@Override</ja>
+		<jk>public</jk> MySerializableSurrogate swap(MyNonSerializableClass o) {
+			
+			<jc>// Create some serializable class and manually copy the data into it.</jc>
+			MySerializableSurrogate s = <jk>new</jk> MySerializableSurrogate();
+			s.<jf>foo</jf> = o.<jf>foo</jf>;
+			<jk>return</jk> s;
+		}
+	}
+				</p>
+				<p>
+					However, the same can be accomplished by using a surrogate class that simply contains a constructor with 
+					the non-serializable class as an argument:
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> MySerializableSurrogate {
+		<jk>public</jk> String <jf>foo</jf>;
+		
+		<jk>public</jk> MySerializableSurrogate(MyNonSerializableClass c) {
+			<jk>this</jk>.<jf>foo</jf> = c.<jf>foo</jf>;
+		}
+	}
+				</p>
+				<p>
+					The surrogate class is registered in the same way as a <code>PojoSwap</code>:
+				</p>
+				<p class='bcode'>
+	<jc>// Create a JSON serializer that can serialize Iterators.</jc>
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().pojoSwaps(MySerializableSurrogate.<jk>class</jk>).build();
+				</p>
+				<p>
+					When the serializer encounters the non-serializable class, it will serialize an instance of the surrogate 
+					instead.
+				</p>
+			</div>
+	
+			<!-- ======================================================================================================= -->
+			<a id="juneau-marshall.BeanAnnotation"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.7 - @Bean Annotation</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.annotation.Bean @Bean} annotation is used to tailor how beans are 
+					interpreted by the framework.
+				</p>
+				<p> 
+					Bean property inclusion and ordering on a bean class can be done using the 
+					{@link org.apache.juneau.annotation.Bean#properties() @Bean.properties()} annotation.
 				</p>
 				<p class='bcode'>
 	<jc>// Address class with only street/city/state properties (in that order).</jc>
 	<jc>// All other properties are ignored.</jc>
 	<ja>@Bean</ja>(properties=<js>"street,city,state"</js>)
-	<jk>public class</jk> Address {
- 			...
+	<jk>public class</jk> Address { ... }
+				</p>
+				<p> 
+					Bean properties can be excluded using the {@link org.apache.juneau.annotation.Bean#excludeProperties() @Bean.excludeProperties()}
+					annotation.
+				</p>
+				<p class='bcode'>
+	<jc>// Address class with only street/city/state properties (in that order).</jc>
+	<jc>// All other properties are ignored.</jc>
+	<ja>@Bean</ja>(excludeProperties=<js>"city,state"</js>})
+	<jk>public class</jk> Address { ... }
+				</p>
+				<p>
+					Bean properties can be sorted alphabetically using {@link org.apache.juneau.annotation.Bean#sort() @Bean.sort()}
+				</p>
+				<p class='bcode'>
+	<jc>// Address class with only street/city/state properties (in that order).</jc>
+	<jc>// All other properties are ignored.</jc>
+	<ja>@Bean</ja>(sort=<jk>true</jk>)
+	<jk>public class</jk> MyBean { ... }
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.Bean#propertyNamer() @Bean.propertyNamer()} annotation
+					is used to provide customized naming of properties.
+				</p>
+				<p>
+					Property namers are used to transform bean property names from standard form to some other form.
+					<br>For example, the {@link org.apache.juneau.PropertyNamerDLC} will convert property names to 
+					dashed-lowercase, and these will be used as attribute names in JSON and element names in XML.
+				</p>
+				<p>
+				<p class='bcode'>
+	<jc>// Define a class with dashed-lowercase property names.</jc>
+	<ja>@Bean</ja>(propertyNamer=PropertyNamerDashedLC.<jk>class</jk>)
+	<jk>public class</jk> MyBean { ... }
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.Bean#interfaceClass @Bean.interfaceClass()} annotation is used
+					to limit properties on beans to specific interface classes.
+					<br>When specified, only the list of properties defined on the interface class will be used during 
+					serialization.
+					<br>Additional properties on subclasses will be ignored.
+				</p>
+				<p class='bcode'>
+	<jc>// Parent class</jc>
+	<ja>@Bean</ja>(interfaceClass=A.<jk>class</jk>)
+	<jk>public abstract class</jk> A {
+		<jk>public</jk> String <jf>f0</jf> = <js>"f0"</js>;
+	}
+	
+	<jc>// Sub class</jc>
+	<jk>public class</jk> A1 <jk>extends</jk> A {
+		<jk>public</jk> String <jf>f1</jf> = <js>"f1"</js>;
+	}
+
+	JsonSerializer s = JsonSerializer.<jsf>DEFAULT_LAX</jsf>;
+	A1 a1 = <jk>new</jk> A1();
+	String r = s.serialize(a1);
+	<jsm>assertEquals</jsm>(<js>"{f0:'f0'}"</js>, r);  <jc>// Note f1 is not serialized.</jc>
+				</p>
+				<p>
+					Note that this annotation can be used on the parent class so that it filters to all child classes,
+					or can be set individually on the child classes.
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.Bean#stopClass @Bean.stopClass()} annotation is another
+					way to limit which properties are serialized.
+					<br>It's identical in purpose to the stop class specified by {@link java.beans.Introspector#getBeanInfo(Class, Class)}.
+					<br>Any properties in the stop class or in its base classes will be ignored during analysis.
+				</p>
+				<p>
+					For example, in the following class hierarchy, instances of <code>C3</code> will include property 
+					<code>p3</code>, but not <code>p1</code> or <code>p2</code>.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> C1 {
+		<jk>public int</jk> getP1();
+	}
+
+	<jk>public class</jk> C2 <jk>extends</jk> C1 {
+		<jk>public int</jk> getP2();
+	}
+
+	<ja>@Bean</ja>(stopClass=C2.<jk>class</jk>)
+	<jk>public class</jk> C3 <jk>extends</jk> C2 {
+		<jk>public int</jk> getP3();
+	}
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.BeanPropertyAnnotation"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.8 - @BeanProperty Annotation</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotation is used to tailor how 
+					individual bean properties are interpreted by the framework.
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanProperty#name() @BeanProperty.name()} annotation
+					is used to override the name of the bean property.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> MyBean {
+		<ja>@BeanProperty</ja>(name=<js>"Bar"</js>)
+		<jk>public</jk> String getFoo() {...}
+	}
+				</p>
+				<p>
+					If the {@link org.apache.juneau.BeanContext#BEAN_beanFieldVisibility} setting on the bean context excludes this field 
+					(e.g. the visibility is set to the default of PUBLIC, but the field is PROTECTED), this annotation 
+					can be used to force the field to be identified as a property.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> MyBean {
+		<ja>@BeanProperty</ja>
+		<jk>protected</jk> String getFoo() {...}
+	}
+				</p>
+				<p>
+					The bean property named <js>"*"</js> is the designated "dynamic property" which allows for "extra" bean
+					properties not otherwise defined.
+					<br>This is similar in concept to the Jackson <ja>@JsonGetterAll</ja> and <ja>@JsonSetterAll</ja> 
+					annotations, but generalized for all supported marshall languages.
+					<br>The primary purpose is for backwards compatibility in parsing newer streams with addition 
+					information into older beans.
+				</p>
+				<p>
+					The following shows various ways of using dynamic bean properties.
+				</p>
+				<p class='bcode'>
+	<jc>// Option #1 - A simple public Map field.</jc>
+	<jc>// The field name can be anything.</jc>
+	<jk>public class</jk> BeanWithDynaField {
+
+		<ja>@BeanProperty</ja>(name=<js>"*"</js>)
+		<jk>public</jk> Map&lt;String,Object&gt; extraStuff = <jk>new</jk> LinkedHashMap&lt;String,Object&gt;();
+	}
+
+	<jc>// Option #2 - Getters and setters.</jc>
+	<jc>// Method names can be anything.</jc>
+	<jc>// Getter must return a Map with String keys.</jc>
+	<jc>// Setter must take in two arguments, a String and Object.</jc>
+	<jk>public class</jk> BeanWithDynaMethods {
+
+		<ja>@BeanProperty</ja>(name=<js>"*"</js>)
+		<jk>public</jk> Map&lt;String,Object&gt; getMyExtraStuff() {
+			...
+		}
+
+		<ja>@BeanProperty</ja>(name=<js>"*"</js>)
+		<jk>public void</jk> setAnExtraField(String name, Object value) {
+			...
+		}
+	}
+
+	<jc>// Option #3 - Getter only.</jc>
+	<jc>// Properties will be added through the getter.</jc>
+	<jk>public class</jk> BeanWithDynaGetterOnly {
+
+		<ja>@BeanProperty</ja>(name=<js>"*"</js>)
+		<jk>public</jk> Map&lt;String,Object&gt; getMyExtraStuff() {
+			...
+		}
+	}
+				</p>
+				<p>
+					Similar rules apply for value types and swaps.
+					<br>The property values optionally can be any serializable type or use swaps.
+				</p>
+				<p class='bcode'>
+	<jc>// A serializable type other than Object.</jc>
+	<jk>public class</jk> BeanWithDynaFieldWithListValues {
+
+		<ja>@BeanProperty</ja>(name=<js>"*"</js>)
+		<jk>public</jk> Map&lt;String,List&lt;String&gt;&gt; getMyExtraStuff() {
+			...
+		}
+	}
+
+	<jc>// A swapped value.</jc>
+	<jk>public class</jk> BeanWithDynaFieldWithSwappedValues {
+
+		<ja>@BeanProperty</ja>(name=<js>"*"</js>, swap=CalendarSwap.<jsf>ISO8601DTZ</jsf>.<jk>class</jk>)
+		<jk>public</jk> Map&lt;String,Calendar&gt; getMyExtraStuff() {
+			...
+		}
+	}
+				</p>
+				<ul class='doctree'>
+					<li class='info'>
+						Note that if you're not interested in these additional properties, you can also use the
+						{@link org.apache.juneau.BeanContext#BEAN_ignoreUnknownBeanProperties} setting to ignore values 
+						that don't fit into existing properties.
+				</ul>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanProperty#value() @BeanProperty.value()} annotation
+					is a synonym for {@link org.apache.juneau.annotation.BeanProperty#name() @BeanProperty.name()}.
+					<br>Use it in cases where you're only specifying a name so that you can shorten your annotation.
+				</p>
+				<p>
+					The following annotations are equivalent:
+				</p>
+				<p class='bcode'>
+	<ja>@BeanProperty</ja>(name=<js>"foo"</js>)
+
+	<ja>@BeanProperty</ja>(<js>"foo"</js>)
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanProperty#type() @BeanProperty.type()} annotation
+					is used to identify a specialized class type for a generalized property.
+					<br>Normally the type is inferred through reflection of the field type or getter return type.
+					<br>However, you'll want to specify this value if you're parsing beans where the bean property class 
+					is an interface or abstract class to identify the bean type to instantiate.
+					<br>Otherwise, you may cause an {@link java.lang.InstantiationException} when trying to set these fields.
+				</p>
+				<p>
+					This property must denote a concrete class with a no-arg constructor.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> MyBean {
+
+		<jc>// Identify concrete type as a HashMap.</jc>
+		<ja>@BeanProperty</ja>(type=HashMap.<jk>class</jk>)
+		<jk>public</jk> Map <jf>p1</jf>;
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanProperty#params() @BeanProperty.params()} annotation
+					is for bean properties of type map or collection.
+					<br>It's used to identify the class types of the contents of the bean property object when
+					the general parameter types are interfaces or abstract classes.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> MyBean {
+
+		<jc>// Identify concrete map type with String keys and Integer values.</jc>
+		<ja>@BeanProperty</ja>(type=HashMap.<jk>class</jk>, params={String.<jk>class</jk>,Integer.<jk>class</jk>})
+		<jk>public</jk> Map <jf>p1</jf>;
+	}
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanProperty#properties() @BeanProperty.properties()} 
+					annotation is used to limit which child properties are rendered by the serializers.
+					<br>It can be used on any of the following bean property types:
+				</p>
+				<ul class='spaced-list'>
+					<li>Beans - Only render the specified properties of the bean.
+					<li>Maps - Only render the specified entries in the map.
+					<li>Bean/Map arrays - Same, but applied to each element in the array.
+					<li>Bean/Map collections - Same, but applied to each element in the collection.
+				</ul>
+				<p class='bcode'>
+	<jk>public class</jk> MyClass {
+
+		<jc>// Only render 'f1' when serializing this bean property.</jc>
+		<ja>@BeanProperty</ja>(properties={<js>"f1"</js>})
+		<jk>public</jk> MyChildClass x1 = <jk>new</jk> MyChildClass();
+	}
+
+	<jk>public class</jk> MyChildClass {
+		<jk>public int</jk> f1 = 1;
+		<jk>public int</jk> f2 = 2;
+	}
+
+	<jc>// Renders "{x1:{f1:1}}"</jc>
+	String json = JsonSerializer.<jsf>DEFAULT</jsf>.serialize(<jk>new</jk> MyClass());
+				</p>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanProperty#format() @BeanProperty.format()} 
+					annotation specifies a String format for converting a bean property value to a formatted string.
+				</p>
+				<p class='bcode'>
+	<jc>// Serialize a float as a string with 2 decimal places.</jc>
+	<ja>@BeanProperty</ja>(format=<js>"$%.2f"</js>)
+	<jk>public float</jk> <jf>price</jf>;
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.BeanConstructorAnnotation"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.9 - @BeanConstructor Annotation</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} annotation is used to 
+					map constructor arguments to property names on bean with read-only properties.
+					<br>Since method parameter names are lost during compilation, this annotation essentially redefines 
+					them so that they are available at runtime.
+				</p>
+				<p>
+					The definition of a read-only bean is a bean with properties with only getters, like shown below:
+				</p>	
+				<p class='bcode'>
+	<jc>// Our read-only bean.</jc>
+	<jk>public class</jk> Person {
+		<jk>private final</jk> String <jf>name</jf>;
+		<jk>private final int</jk> <jf>age</jf>;
+
+		<ja>@BeanConstructor</ja>(properties=<js>"name,age"</js>})
+		<jk>public</jk> Person(String name, <jk>int</jk> age) {
+			<jk>this</jk>.<jf>name</jf> = name;
+			<jk>this</jk>.<jf>age</jf> = age;
+		}
+
+		<jc>// Read only properties.</jc>
+
+		<jk>public</jk> String getName() {
+			<jk>return</jk> <jf>name</jf>;
+		}
+
+		<jk>public int</jk> getAge() {
+			<jk>return</jk> <jf>age</jf>;
+		}
+	}			
+				</p>
+				<p class='bcode'>
+	<jc>// Parsing into a read-only bean.</jc>
+	String json = <js>"{name:'John Smith',age:45}"</js>;
+	Person p = JsonParser.<jsf>DEFAULT</jsf>.parse(json);
+	String name = p.getName();  <jc>// "John Smith"</jc>
+	<jk>int</jk> age = p.getAge();   <jc>// 45</jc>
+				</p>
+				<p>
+					Beans can also be defined with a combination of read-only and read-write properties.
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.BeanIgnoreAnnotation"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.10 - @BeanIgnore Annotation</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} annotation is used to
+					ignore classes, fields, and methods from being interpreted as beans or bean components.
+				</p> 
+				<p>
+					When applied to classes, objects will be converted to strings even though they look like beans.
+				</p>
+				<p class='bcode'>
+	<jc>// Not really a bean!  Use toString() instead!</jc>
+	<ja>@BeanIgnore</ja>
+	<jk>public class</jk> MyBean {...}
+				</p>
+				<p>
+					When applied to fields and getters/setters, they will be ignored as bean properties.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> MyBean {
+		
+		<jc>// Not a bean property!</jc>
+		<ja>@BeanIgnore</ja>
+		<jk>public</jk> String <jf>foo</jf>;
+		
+		<jc>// Not a bean property!</jc>
+		<ja>@BeanIgnore</ja>
+		<jk>public</jk> String getBar() {...}
+	}
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.NamePropertyAnnotation"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.11 - @NameProperty Annotation</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.annotation.NameProperty @NameProperty} annotation is used to
+					identify a setter as a method for setting the name of a POJO as it's known by its parent object.
+				</p>
+				<p>
+					A commonly-used case is when you're parsing a JSON map containing beans where one of the bean 
+					properties is the key used in the map.
+				</p>
+				<p class='bcode'>
+	<jc>// JSON</jc> 
+	{
+		id1: {name: <js>'John Smith'</js>, sex:<js>'M'</js>},
+		id2: {name: <js>'Jane Doe'</js>, sex:<js>'F'</js>}
+	}
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> Person {
+		
+		<ja>@NameProperty</ja> 
+		<jk>public</jk> String <jf>id</jf>;  <jc>// Value gets assigned from object key</jc>
+		
+		<jk>public</jk> String <jf>name</jf>;
+		
+		<jk>public char</jk> <jf>sex</jf>;
+	}
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.ParentPropertyAnnotion"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.12 - @ParentProperty Annotation</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.annotation.ParentProperty @ParentProperty} annotation is used to
+					identify a setter as a method for adding a parent reference to a child object.
+				</p>
+				<p>
+					A commonly-used case is when you're parsing beans and a child bean has a reference to a parent bean.
+				</p>
+				<p class='bcode'>
+	<jk>public class</jk> AddressBook {
+		<jk>public</jk> List&lt;Person&gt; <jf>people</jf>;
+	}
+
+	<jk>public class</jk> Person {
+	
+		<ja>@ParentProperty</ja> 
+		<jk>public</jk> AddressBook <jf>addressBook</jf>;  <jc>// A reference to the containing address book.</jc>
+		
+		<jk>public</jk> String <jf>name</jf>;
+		
+		<jk>public char</jk> <jf>sex</jf>;
+	}
+				</p>
+				<p>
+					Parsers will automatically set this field for you in the child beans.
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.URIAnnotation"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.13 - @URI Annotation</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.annotation.URI @URI} annotation is used to identify a class or bean 
+					property as a URI.
+				</p>
+				<p>
+					By default, instances of {@link java.net.URL} and {@link java.net.URI} are considered URIs during serialization and 
+					are handled differently depending on the serializer (e.g. <code>HtmlSerializer</code> creates a 
+					hyperlink, <code>RdfXmlSerializer</code> creates an <code>rdf:resource</code> object, etc...).
+					<br>This annotation allows you to identify other classes that return URIs via <code>toString()</code> 
+					as URI objects.
+				</p>
+				<p>
+					URIs are automatically resolved to absolute or root-relative form based on the serializer
+					{@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriResolution} and 
+					{@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriRelativity}
+					configuration settings, and the URI context defined by the {@link org.apache.juneau.UriContext} that's part of the 
+					serializer session.
+					<br>Refer to the {@link org.apache.juneau.UriResolver} class for information about the types of URIs that can be 
+					resolved during serialization.
+				</p>
+				<p>
+					This annotation can be applied to classes, interfaces, or bean property methods for fields.
+				</p>
+				<p class='bcode'>
+	<jc>// Applied to a class whose toString() method returns a URI.</jc>
+	<ja>@URI</ja>
+	<jk>public class</jk> MyURI {
+		<ja>@Override</ja>
+		<jk>public</jk> String toString() {
+			<jk>return</jk> <js>"http://localhost:9080/foo/bar"</js>;
+		}
+	}
+
+	<jc>// Applied to bean properties</jc>
+	<jk>public class</jk> MyBean {
+
+		<ja>@URI</ja>
+		<jk>public</jk> String <jf>beanUri</jf>;
+
+		<ja>@URI</ja>
+		<jk>public</jk> String getParentUri() {
+			...
+		}
+	}
+				</p>
+			</div>
+
+			<!-- ======================================================================================================= -->
+			<a id="juneau-marshall.BeanFilters"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.14 - BeanFilter Class</h4>
+			<div class='topic'>
+				<p>
+					The {@link org.apache.juneau.transform.BeanFilter} class is the programmatic equivalent to the
+					{@link org.apache.juneau.annotation.Bean @Bean} annotation.
+				</p>
+				<p>
+					In practice, it's usually simpler to use the {@link org.apache.juneau.annotation.Bean @Bean} and 
+					{@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotations on your bean classes.
+					<br>However, bean filters make it possible to accomplish the same when you can't add annotations
+					to existing code.
 				</p>
 				<p>
 					Bean filters are defined through {@link org.apache.juneau.transform.BeanFilterBuilder BeanFilterBuilders}.
@@ -1443,7 +2115,7 @@
 				</p>
 				<p class='bcode'>			
 	<jc>// Create a new JSON serializer and associate a bean filter with it.</jc>
-	Serializer serializer = JsonSerializer.<jsm>create</jsm>().beanFilters(MyAddressBeanFilter.<jk>class</jk>).build();
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().beanFilters(MyAddressBeanFilter.<jk>class</jk>).build();
 				</p>
 				<p>
 					Note that if you use the annotation, you do NOT need to set anything on the serializers/parsers.
@@ -1470,18 +2142,117 @@
 	}
 	
 	<jc>// Create a new JSON serializer that only exposes street,city,state on Address bean.</jc>
-	Serializer serializer = JsonSerializer.<jsm>create</jsm>().beanFilters(AddressInterface.<jk>class</jk>).build();
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().beanFilters(AddressInterface.<jk>class</jk>).build();
+				</p>				
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.StopClasses"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.15 - Stop Classes</h4>
+			<div class='topic'>
+				<p>
+					Occasionally, you may want to limit bean properties to only those defined on a parent class or interface.  
+					<br>There are a couple of ways of doing this.
+				</p>
+				<p>
+					For example, let's define the following parent class and subclass:
+				</p>
+				<p class='bcode'>
+	<jc>// Abstract parent class</jc>
+	<jk>public abstract class</jk> MyClass {
+		<jk>public</jk> String <jf>foo</jf>=<js>"foo"</js>;
+	}
+
+	<jc>// Subclass 1</jc>
+	<jk>public class</jk> MyClassBar <jk>extends</jk> MyClass {
+		<jk>public</jk> String <jf>bar</jf>=<js>"bar"</js>;
+	}
+				</p>
+				<p>
+					Suppose we only want to render the properties defined on <code>MyClass</code>, not those defined on 
+					child classes. 
+					<br>To do so, we can define the following bean filter:
+				</p>
+				<p class='bcode'>
+	<jc>// Define transform that limits properties to only those defined on MyClass</jc>
+	<jk>public class</jk> MyBeanFilter <jk>extends</jk> BeanFilter&lt;MyClass&gt; {
+		<jk>public</jk>  MyBeanFilter() {
+			interfaceClass(MyClass.<jk>class</jk>);
+		}
+	}
+				</p>
+				<p>
+					When serialized, the serialized bean will only include properties defined on the parent class.
+				</p>
+				<p class='bcode'>
+	<jc>// Serialize to JSON</jc>
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().simple().beanFilters(MyBeanFilter.<jk>class</jk>).build();
+	MyClass c = <jk>new</jk> MyClassBar();
+	String json = s.serialize(p);  <jc>// Prints "{foo:'foo'}"</jc>
+				</p>	
+				<p>
+					The equivalent can be done through an annotation on the parent class, which applies to all child classes:
+				</p>
+				<p class='bcode'>
+	<ja>@Bean</ja>(interfaceClass=MyClass.<jk>class</jk>)
+	<jk>public abstract class</jk> MyClass {
+		<jk>public</jk> String <jf>foo</jf>=<js>"foo"</js>;
+	}
+				</p>
+				<p>
+					The annotation can also be applied on the individual child classes, like so...
+				</p>
+				<p class='bcode'>
+	<ja>@Bean</ja>(interfaceClass=MyClass.<jk>class</jk>)
+	<jk>public class</jk> MyClassBar <jk>extends</jk> MyClass {
+		<jk>public</jk> String <jf>bar</jf>=<js>"bar"</js>;
+	}
+				</p>
+				<p>
+					Also, the <code>beanFilters()</code> methods will automatically interpret any non-<code>BeanFilter</code> 
+					classes passed in as meaning interface classes. 
+					<br>So in the previous example, the <code>BeanFilter</code> class could have been avoided altogether by just 
+					passing in <code>MyClass.<jk>class</jk></code> to the serializer, like so:
+				</p>
+				<p class='bcode'>
+	<jc>// Serialize to JSON</jc>
+	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().beanFilters(MyClass.<jk>class</jk>).build();
+				</p>
+			</div>
+
+			<!-- =================================================================================================== -->
+			<a id="juneau-marshall.SerializingToObjectMaps"></a>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.16 - Serializing to ObjectMaps</h4>
+			<div class='topic'>
+				<p>
+					A shortcut method for transforming is provided that can often be simpler than defining transforms.
+					In this case, we add methods to our class to serialize to {@link org.apache.juneau.ObjectMap ObjectMaps}
+				</p>
+				<p>
+				<p class='bcode'>
+	<jk>public class</jk> MyClass {
+		<jk>private</jk> String <jf>f1</jf>;
+		
+		<jc>// Constructor that takes in an ObjectMap</jc>
+		<jk>public</jk> MyClass(ObjectMap m) {
+			<jf>f1</jf> = m.getString(<js>"f1"</js>);
+		}
+		
+		<jc>// Method that converts object to an ObjectMap</jc>
+		<jk>public</jk> ObjectMap toObjectMap() {
+			<jk>return new</jk> ObjectMap().append(<js>"f1"</js>, <jf>f1</jf>);
+		}
+				</p>
+				<p>
+					The <code>toObjectMap()</code> method will automatically be used during serialization, and 
+					the constructor will automatically be used during parsing.
+					This will work for all serializers and parsers.
 				</p>
-				
-				<h6 class='toc'>Additional Information - org.apache.juneau.transform</h6>
-				<ol class='toc'>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#BeanFilters'>BeanFilter Class</a></p>
-				</ol>
 			</div>
 
 			<!-- =================================================================================================== -->
 			<a id="juneau-marshall.SerializingReadersAndInputStreams"></a>
-			<h4 class='topic' onclick='toggle(this)'>2.1.6.5 - Serializing Readers and InputStreams</h4>
+			<h4 class='topic' onclick='toggle(this)'>2.1.6.17 - Serializing Readers and InputStreams</h4>
 			<div class='topic'>
 				<p>
 					Juneau serializers treat instances of <code>Readers</code> and <code>InputStreams</code> special by 
@@ -1527,20 +2298,6 @@
 						access to the underlying stream.
 				</ul>
 			</div>
-			
-				
-			<h6 class='toc'>Additional Information - org.apache.juneau.transform</h6>
-			<ol class='toc'>
-				<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#Transforms'>Transforms</a></p>
-				<ol>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#BeanFilters'>BeanFilter Class</a></p>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#PojoSwaps'>PojoSwap Class</a></p>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#PojoSwaps_OneWay'>One-Way PojoSwaps</a></p>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#StopClasses'>Stop Classes</a></p>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#SurrogateClasses'>Surrogate Classes</a></p>
-					<li><p><a class='doclink' href='org/apache/juneau/transform/package-summary.html#ToObjectMaps'>Serializing to ObjectMaps</a></p>
-				</ol>
-			</ol>
 		</div>
 	
 		<!-- ======================================================================================================= -->
@@ -8108,6 +8865,38 @@
 				</ul>
 		</ul>
 
+		<h6 class='topic'>Documentation</h6>
+		<ul class='spaced-list'>
+			<li>
+				New and updated sections in overview document:
+				<ul>
+					<li><p><a class='doclink' href='#juneau-marshall.PojoSwaps'>PojoSwaps</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.PerMediaTypePojoSwaps'>Per-media-type PojoSwaps</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.OneWayPojoSwaps'>One-way PojoSwaps</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.SwapAnnotation'>@Swap Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.SwapMethods'>Swap Methods</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.SurrogateClasses'>Surrogate Classes</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.BeanAnnotation'>@Bean Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.BeanPropertyAnnotation'>@BeanProperty Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.BeanConstructorAnnotation'>@BeanConstructor Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.BeanIgnoreAnnotation'>@BeanIgnore Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.NamePropertyAnnotation'>@NameProperty Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.ParentPropertyAnnotation'>@ParentProperty Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.URIAnnotation'>@URI Annotation</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.BeanFilters'>BeanFilters</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.StopClasses'>Stop Classes</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.SerializingToObjectMaps'>Serializing to ObjectMaps</a></p>
+					<li><p><a class='doclink' href='#juneau-marshall.SerializingReadersAndInputStreams'>Serializing Readers and InputStreams</a></p>
+				</ul>		
+			<li>
+				Updated javadocs:
+				<ul>
+					<li>{@link org.apache.juneau.BeanContext}
+					<li>{@link org.apache.juneau.BeanContextBuilder}
+					<li>{@link org.apache.juneau.rest.RestContext}
+					<li>{@link org.apache.juneau.rest.RestContextBuilder}
+				</ul>		
+		</ul>
 	</div>
 
 	<!-- =========================================================================================================== -->
@@ -12991,4 +13780,4 @@
 
 </div>
 </body>								
-	
\ No newline at end of file
+	


Mime
View raw message