juneau-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jamesbog...@apache.org
Subject [2/2] juneau git commit: Javadoc updates.
Date Tue, 09 Jan 2018 03:32:49 GMT
Javadoc updates.

Project: http://git-wip-us.apache.org/repos/asf/juneau/repo
Commit: http://git-wip-us.apache.org/repos/asf/juneau/commit/474a143c
Tree: http://git-wip-us.apache.org/repos/asf/juneau/tree/474a143c
Diff: http://git-wip-us.apache.org/repos/asf/juneau/diff/474a143c

Branch: refs/heads/master
Commit: 474a143ce44d5243d5af0f3cc3235bf72ee1c30d
Parents: cea2a1d
Author: JamesBognar <jamesbognar@apache.org>
Authored: Mon Jan 8 22:32:44 2018 -0500
Committer: JamesBognar <jamesbognar@apache.org>
Committed: Mon Jan 8 22:32:44 2018 -0500

----------------------------------------------------------------------
 .../java/org/apache/juneau/BeanContext.java     |  78 +-
 .../org/apache/juneau/transform/MapSwap.java    |  21 +
 .../org/apache/juneau/transform/PojoSwap.java   |  55 +-
 .../org/apache/juneau/transform/StringSwap.java |  21 +
 .../org/apache/juneau/transform/package.html    | 675 -------------
 juneau-doc/src/main/javadoc/overview.html       | 983 +++++++++++++++++--
 6 files changed, 1028 insertions(+), 805 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/juneau/blob/474a143c/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanContext.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanContext.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanContext.java
index dd681f7..7769f1c 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanContext.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanContext.java
@@ -426,6 +426,10 @@ public class BeanContext extends Context {
 	 * 	<li><b>Data type:</b>  <code>List&lt;Class&gt;</code>
 	 * 	<li><b>Default:</b>  empty list
 	 * 	<li><b>Session-overridable:</b>  <jk>false</jk>
+	 * 	<li><b>Annotations:</b> 
+	 * 		<ul>
+	 * 			<li class='ja'>{@link Bean} 
+	 * 		</ul>
 	 * 	<li><b>Methods:</b> 
 	 * 		<ul>
 	 * 			<li class='jm'>{@link BeanContextBuilder#beanFilters(Object...)}
@@ -479,8 +483,9 @@ public class BeanContext extends Context {
 	 * 
 	 *	<h5 class='section'>Documentation:</h5>
 	 *	<ul>
-	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.BeanFilters">Overview &gt; BeanFilters and @Bean annotations</a>
-	 *		<li><a class="doclink" href="transform/package-summary.html#BeanFilters">org.apache.juneau.transform &gt; BeanFilter Class</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.BeanAnnotation">Overview &gt; @Bean Annotation</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.BeanFilters">Overview &gt; BeanFilters</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.StopClasses">Overview &gt; Stop Classes</a>
 	 *	</ul>
 	 */
 	public static final String BEAN_beanFilters = PREFIX + "beanFilters.lc";
@@ -1056,7 +1061,7 @@ public class BeanContext extends Context {
 	public static final String BEAN_notBeanPackages_remove = PREFIX + "notBeanPackages.ss/remove";
 
 	/**
-	 * Configuration property:  POJO swaps to apply to Java objects.
+	 * Configuration property:  POJO swaps.
 	 *
 	 *	<h5 class='section'>Property:</h5>
 	 * <ul>
@@ -1071,8 +1076,8 @@ public class BeanContext extends Context {
 	 * 		</ul>
 	 * 	<li><b>Methods:</b> 
 	 * 		<ul>
-	 * 			<li class='jm'>{@link BeanContextBuilder#pojoSwaps(Class...)}
 	 * 			<li class='jm'>{@link BeanContextBuilder#pojoSwaps(Object...)}
+	 * 			<li class='jm'>{@link BeanContextBuilder#pojoSwaps(Class...)}
 	 * 			<li class='jm'>{@link BeanContextBuilder#pojoSwaps(boolean, Object...)}
 	 * 			<li class='jm'>{@link BeanContextBuilder#pojoSwapsRemove(Object...)}
 	 * 		</ul>
@@ -1080,16 +1085,67 @@ public class BeanContext extends Context {
 	 *
 	 *	<h5 class='section'>Description:</h5>
 	 * <p>
-	 * There are two category of classes that can be passed in through this method:
-	 * <ul>
-	 * 	<li>Subclasses of {@link PojoSwap}.
-	 * 	<li>Surrogate classes.  A shortcut for defining a {@link SurrogateSwap}.
-	 * </ul>
-	 *
+	 * POJO swaps are used to "swap out" non-serializable classes with serializable equivalents during serialization,
+	 * and "swap in" the non-serializable class during parsing.
+	 * 
+	 * <p>
+	 * An example of a POJO swap would be a <code>Calendar</code> object that gets swapped out for an ISO8601 string.
+	 * 
 	 * <p>
 	 * Multiple POJO swaps can be associated with a single class.
-	 * When multiple swaps are applicable to the same class, the media type pattern defined by
+	 * <br>When multiple swaps are applicable to the same class, the media type pattern defined by
 	 * {@link PojoSwap#forMediaTypes()} or {@link Swap#mediaTypes()} are used to come up with the best match.
+	 * 
+	 * <p>
+	 * Values can consist of any of the following types:
+	 * <ul>
+	 * 	<li>Any subclass of {@link PojoSwap}.
+	 * 	<li>Any surrogate class.  A shortcut for defining a {@link SurrogateSwap}.
+	 * 	<li>Any array or collection of the objects above.
+	 * </ul>
+	 * 
+	 *	<h5 class='section'>Example:</h5>
+	 * <p class='bcode'>
+	 * 	<jc>// Sample swap for converting Dates to ISO8601 strings.</jc>
+	 * 	<jk>public class</jk> MyDateSwap <jk>extends</jk> StringSwap&lt;Date&gt; {
+	 * 		<jc>// ISO8601 formatter.</jc>
+	 * 		<jk>private</jk> DateFormat <jf>format</jf> = <jk>new</jk> SimpleDateFormat(<js>"yyyy-MM-dd'T'HH:mm:ssZ"</js>);
+	 * 		
+	 * 		<ja>@Override</ja>
+	 * 		<jk>public</jk> String swap(BeanSession session, Date o) {
+	 * 			<jk>return</jk> <jf>format</jf>.format(o);
+	 * 		}
+	 * 		
+	 * 		<ja>@Override</ja>
+	 * 		<jk>public</jk> Date unswap(BeanSession session, String o, ClassMeta hint) <jk>throws</jk> Exception {
+	 * 			<jk>return</jk> <jf>format</jf>.parse(o);
+	 * 		}
+	 * 	}
+	 * 
+	 * 	<jc>// Sample bean with a Date field.</jc>
+	 * 	<jk>public class</jk> MyBean {
+	 * 		<jk>public</jk> Date <jf>date</jf> = <jk>new</jk> Date(112, 2, 3, 4, 5, 6);
+	 * 	}
+	 * 
+	 * 	<jc>// Create a new JSON serializer, associate our date swap with it, and serialize a sample bean.</jc>
+	 * 	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().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 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>
+	 * 
+	 *	<h5 class='section'>Documentation:</h5>
+	 *	<ul>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.PojoSwaps">Overview &gt; PojoSwaps</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.PerMediaTypePojoSwaps">Overview &gt; Per-media-type PojoSwaps</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.OneWayPojoSwaps">Overview &gt; One-way PojoSwaps</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.SwapAnnotation">Overview &gt; @Swap Annotation</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.SwapMethods">Overview &gt; Swap Methods</a>
+	 *		<li><a class="doclink" href="../../../overview-summary.html#juneau-marshall.SurrogateClasses">Overview &gt; Surrogate Classes</a>
+	 *	</ul>
 	 */
 	public static final String BEAN_pojoSwaps = PREFIX + "pojoSwaps.lc";
 

http://git-wip-us.apache.org/repos/asf/juneau/blob/474a143c/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/MapSwap.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/MapSwap.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/MapSwap.java
index 8f521c0..a2f1904 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/MapSwap.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/MapSwap.java
@@ -17,6 +17,27 @@ import org.apache.juneau.*;
 /**
  * Abstract subclass for POJO swaps that swap objects for object maps.
  *
+ * <h6 class='topic'>Example</h6>
+ * <p class='bcode'>
+ * 	<jc>// A swap that converts beans into generic maps.</jc>
+ * 	<jk>public class</jk> MyBeanSwap <jk>extends</jk> MapSwap&lt;<jk>byte</jk>[]&gt; {
+ * 		
+ * 		<ja>@Override</ja>
+ * 		<jk>public</jk> ObjectMap swap(BeanSession session, MyBean myBean) <jk>throws</jk> Exception {
+ * 			<jk>return new</jk> ObjectMap().append(<js>"foo"</js>, myBean.getFoo());
+ * 		}
+ * 		
+ * 		<ja>@Override</ja>
+ * 		<jk>public</jk> MyBean unswap(BeanSession session, ObjectMap m, ClassMeta&lt;?&gt; hint) <jk>throws</jk> Exception {
+ * 			<jk>return new</jk> MyBean(m.get(<js>"foo"</js>));
+ * 		}
+ * 	}
+ * 
+ * 	<jc>// Use it to serialize a byte array.</jc>
+ * 	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().simple().pojoSwaps(MyBeanSwap.<jk>class</jk>).build();
+ * 	String json = s.serialize(<jk>new</jk> MyBean(<js>"bar"</js>));  <jc>// Produces "{foo:'bar'}"</jc>
+ * </p>
+ * 
  * @param <T> The normal form of the class.
  */
 public abstract class MapSwap<T> extends PojoSwap<T,ObjectMap> {

http://git-wip-us.apache.org/repos/asf/juneau/blob/474a143c/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java
index 3d47fc4..58d9669 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java
@@ -26,8 +26,7 @@ import org.apache.juneau.serializer.*;
  * Used to swap out non-serializable objects with serializable replacements during serialization, and vis-versa during
  * parsing.
  *
- *
- * <h6 class='section'>Description:</h6>
+ * <h5 class='topic'>Description</h5>
  *
  * <p>
  * <code>PojoSwaps</code> are used to extend the functionality of the serializers and parsers to be able to handle
@@ -41,10 +40,15 @@ import org.apache.juneau.serializer.*;
  * Swaps MUST declare a public no-arg constructor so that the bean context can instantiate them.
  *
  * <p>
- * <code>PojoSwaps</code> are associated with instances of {@link BeanContext BeanContexts} by passing the swap
- * class to the {@link SerializerBuilder#pojoSwaps(Class...)} and {@link ParserBuilder#pojoSwaps(Class...)} methods.
- * <br>When associated with a bean context, fields of the specified type will automatically be converted when the
- * {@link BeanMap#get(Object)} or {@link BeanMap#put(String, Object)} methods are called.
+ * <code>PojoSwaps</code> are associated with serializers and parsers through the following:
+ * <ul>
+ * 	<li class='ja'>{@link Swap} 
+ * 	<li class='ja'>{@link Swaps} 
+ * 	<li class='jm'>{@link BeanContextBuilder#pojoSwaps(Object...)}
+ * 	<li class='jm'>{@link BeanContextBuilder#pojoSwaps(Class...)}
+ * 	<li class='jm'>{@link BeanContextBuilder#pojoSwaps(boolean, Object...)}
+ * 	<li class='jm'>{@link BeanContextBuilder#pojoSwapsRemove(Object...)}
+ * </ul>
  *
  * <p>
  * <code>PojoSwaps</code> have two parameters:
@@ -62,8 +66,8 @@ import org.apache.juneau.serializer.*;
  *
  * The following abstract subclasses are provided for common swap types:
  * <ol>
- * 	<li>{@link StringSwap} - Objects swapped with strings.
- * 	<li>{@link MapSwap} - Objects swapped with {@link ObjectMap ObjectMaps}.
+ * 	<li class='jac'>{@link StringSwap} - Objects swapped with strings.
+ * 	<li class='jac'>{@link MapSwap} - Objects swapped with {@link ObjectMap ObjectMaps}.
  * </ol>
  *
  *
@@ -96,24 +100,27 @@ import org.apache.juneau.serializer.*;
  *
  *
  * <h6 class='topic'>Overview</h6>
- *
+ * 
+ * <p>
  * The following is an example of a swap that replaces byte arrays with BASE-64 encoded strings:
- *
+ * 
  * <p class='bcode'>
- * 	<jk>public class</jk> ByteArrayBase64Swap <jk>extends</jk> PojoSwap<<jk>byte</jk>[],String> {
- *
- * 		<jk>public</jk> String swap(BeanSession session, <jk>byte</jk>[] b) <jk>throws</jk> SerializeException {
+ * 	<jk>public class</jk> ByteArrayBase64Swap <jk>extends</jk> PojoSwap&lt;<jk>byte</jk>[],String&gt; {
+ * 		
+ * 		<ja>@Override</ja>
+ * 		<jk>public</jk> String swap(BeanSession session, <jk>byte</jk>[] b) <jk>throws</jk> Exception {
  * 			<jk>return</jk> StringUtils.<jsm>base64Encode</jsm>(b);
  * 		}
- *
- * 		<jk>public byte</jk>[] unswap(BeanSession session, String s, ClassMeta&lt;?&gt; hint) <jk>throws</jk> ParseException {
+ * 		
+ * 		<ja>@Override</ja>
+ * 		<jk>public byte</jk>[] unswap(BeanSession session, String s, ClassMeta&lt;?&gt; hint) <jk>throws</jk> Exception {
  * 			<jk>return</jk> StringUtils.<jsm>base64Decode</jsm>(s);
  * 		}
  * 	}
  * </p>
  *
  * <p class='bcode'>
- * 	WriterSerializer s = JsonSerializer.<jsf>DEFAULT_LAX</jsf>.builder().pojoSwaps(ByteArrayBase64Swap.<jk>class</jk>).build();
+ * 	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().simple().pojoSwaps(ByteArrayBase64Swap.<jk>class</jk>).build();
  * 	String json = s.serialize(<jk>new byte</jk>[] {1,2,3});  <jc>// Produces "'AQID'"</jc>
  * </p>
  *
@@ -148,11 +155,11 @@ import org.apache.juneau.serializer.*;
  * Note that while there is a unified interface for handling swaps during both serialization and parsing,
  * in many cases only one of the {@link #swap(BeanSession, Object)} or {@link #unswap(BeanSession, Object, ClassMeta)}
  * methods will be defined because the swap is one-way.
- * For example, a swap may be defined to convert an {@code Iterator} to a {@code ObjectList}, but
+ * <br>For example, a swap may be defined to convert an {@code Iterator} to a {@code ObjectList}, but
  * it's not possible to unswap an {@code Iterator}.
- * In that case, the {@code swap(Object}} method would be implemented, but the {@code unswap(ObjectMap)} object would
+ * <br>In that case, the {@code swap(Object}} method would be implemented, but the {@code unswap(ObjectMap)} object would
  * not, and the swap would be associated on the serializer, but not the parser.
- * Also, you may choose to serialize objects like {@code Dates} to readable {@code Strings}, in which case it's not
+ * <br>Also, you may choose to serialize objects like {@code Dates} to readable {@code Strings}, in which case it's not
  * possible to re-parse it back into a {@code Date}, since there is no way for the {@code Parser} to know it's a
  * {@code Date} from just the JSON or XML text.
  *
@@ -160,7 +167,7 @@ import org.apache.juneau.serializer.*;
  * <h6 class='topic'>Per media-type swaps</h6>
  * <p>
  * The {@link #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 by media type.
+ * <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.
  *
  * <p>
@@ -311,9 +318,13 @@ import org.apache.juneau.serializer.*;
  * <code>Time-Zone</code> headers on the request.
  *
  *
- * <h6 class='section'>Additional information:</h6>
+ * <h6 class='topic'>Documentation</h6>
+ *	<ul>
+ *		<li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.PojoSwaps">Overview &gt; PojoSwaps</a>
+ *		<li><a class="doclink" href="package-summary.html#PojoSwaps">org.apache.juneau.transform &gt; PojoSwap Class</a>
+ *		<li><a class='doclink' href='org/apache/juneau/transform/package-summary.html#PojoSwaps_OneWay'>org.apache.juneau.transform &gt; One-Way PojoSwaps</a>
+ *	</ul>
  *
- * See <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.transform</a> for more information.
  *
  * @param <T> The normal form of the class.
  * @param <S> The swapped form of the class.

http://git-wip-us.apache.org/repos/asf/juneau/blob/474a143c/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/StringSwap.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/StringSwap.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/StringSwap.java
index 6002086..4980a00 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/StringSwap.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/StringSwap.java
@@ -17,6 +17,27 @@ import org.apache.juneau.*;
 /**
  * Abstract subclass for POJO swaps that swap objects for strings.
  *
+ * <h6 class='topic'>Example</h6>
+ * <p class='bcode'>
+ * 	<jc>// A swap that converts byte arrays to BASE64-encoded strings.</jc>
+ * 	<jk>public class</jk> ByteArrayBase64Swap <jk>extends</jk> StringSwap&lt;<jk>byte</jk>[]&gt; {
+ * 		
+ * 		<ja>@Override</ja>
+ * 		<jk>public</jk> String swap(BeanSession session, <jk>byte</jk>[] b) <jk>throws</jk> Exception {
+ * 			<jk>return</jk> StringUtils.<jsm>base64Encode</jsm>(b);
+ * 		}
+ * 		
+ * 		<ja>@Override</ja>
+ * 		<jk>public byte</jk>[] unswap(BeanSession session, String s, ClassMeta&lt;?&gt; hint) <jk>throws</jk> Exception {
+ * 			<jk>return</jk> StringUtils.<jsm>base64Decode</jsm>(s);
+ * 		}
+ * 	}
+ * 
+ * 	<jc>// Use it to serialize a byte array.</jc>
+ * 	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().simple().pojoSwaps(ByteArrayBase64Swap.<jk>class</jk>).build();
+ * 	String json = s.serialize(<jk>new byte</jk>[] {1,2,3});  <jc>// Produces "'AQID'"</jc>
+ * </p>
+ *
  * @param <T> The normal form of the class.
  */
 public abstract class StringSwap<T> extends PojoSwap<T,String> {

http://git-wip-us.apache.org/repos/asf/juneau/blob/474a143c/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/package.html
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/package.html b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/package.html
index f351735..faf5634 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/package.html
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/package.html
@@ -56,680 +56,5 @@
 	}
 </script>
 
-<a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
-<ol class='toc'>
-	<li><p><a class='doclink' href='#Transforms'>Transforms</a></p>
-	<ol>
-		<li><p><a class='doclink' href='#BeanFilters'>BeanFilter Class</a></p>
-		<li><p><a class='doclink' href='#PojoSwaps'>PojoSwap Class</a></p>
-		<li><p><a class='doclink' href='#PojoSwaps_OneWay'>One-Way PojoSwaps</a></p>
-		<li><p><a class='doclink' href='#StopClasses'>Stop Classes</a></p>
-		<li><p><a class='doclink' href='#SurrogateClasses'>Surrogate Classes</a></p>
-		<li><p><a class='doclink' href='#ToObjectMaps'>Serializing to ObjectMaps</a></p>
-	</ol>
-</ol>
-
-<!-- ======================================================================================================== -->
-<a id="Transforms"></a>
-<h2 class='topic' onclick='toggle(this)'>1 - Transforms</h2>
-<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:
-	</p>
-	<ul class='spaced-list'>
-		<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>
-		Transforms are added to serializers and parsers (and REST clients) using the following methods:
-	</p> 
-	<ul class='spaced-list'>
-		<li class='jm'>{@link org.apache.juneau.BeanContextBuilder#beanFilters(Object[])}
-		<li class='jm'>{@link org.apache.juneau.BeanContextBuilder#pojoSwaps(Object[])}
-	</ul>
-	<p>
-		Annotations are also provided for specifying transforms directly on classes:
-	</p>
-	<ul class='spaced-list'>
-		<li class='ja'>{@link org.apache.juneau.annotation.Bean @Bean}
-		<li class='ja'>{@link org.apache.juneau.annotation.Swap @Swap}
-	</ul>
-		
-	<!-- ======================================================================================================== -->
-	<a id="BeanFilters"></a>
-	<h3 class='topic' onclick='toggle(this)'>1.1 - BeanFilter Class</h3>
-	<div class='topic'>
-		<p>
-			Bean filters are used to tailor how Juneau handles bean classes.
-			They can be used for the following purposes:
-		</p>
-		<ul class='spaced-list'>
-			<li>
-				Include or exclude which properties are exposed in beans, or the order those properties are serialized.
-			<li>
-				Define property-namers for customizing bean property names.
-			<li>
-				Define bean subtypes.
-			<li>
-				Define bean interface classes.
-		</ul>
-		<p>
-			It should be noted that the {@link org.apache.juneau.annotation.Bean @Bean} annotation provides equivalent 
-			functionality through annotations.  
-			<br>However, the {@link org.apache.juneau.transform.BeanFilter} and {@link org.apache.juneau.transform.BeanFilterBuilder}
-			classes allows you to provide the same features when you do not have access to the source code.
-		<p>
-		
-		<h6 class='topic'>Explicitly specify which properties are visible on a bean class</h6>
-		<p class='bcode'>
-	<jc>// Define bean filter that orders properties by "age" then "name"</jc>
-	<jk>public class</jk> MyBeanFilter <jk>extends</jk> BeanFilterBuilder {
-		<jk>public</jk> MyBeanFilter() {
-			<jk>super</jk>(Person.<jk>class</jk>);
-			properties(<js>"age"</js>,<js>"name"</js>);
-		}
-	}
-	
-	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().beanFilters(MyBeanFilter.<jk>class</jk>).build();
-	Person p = getPerson();
-	String json = s.serialize(p);  <jc>// Prints "{age:45,name:'John Smith'}"</jc>
-		</p>
-		<p>
-			Note that this is equivalent to specifying the following annotation on the bean class:
-		</p>
-		<p class='bcode'>
-	<ja>@Bean</ja>(properties=<js>"age,name"</js>)
-	<jk>public class</jk> Person {
-		...
-	}
-		</p>
-
-		<h6 class='topic'>Exclude which properties are visible on a bean class</h6>
-		<p class='bcode'>
-	<jc>// Define bean filter that excludes "name"</jc>
-	<jk>public class</jk> MyBeanFilter <jk>extends</jk> BeanFilterBuilder {
-		<jk>public</jk> MyBeanFilter() {
-			<jk>super</jk>(Person.<jk>class</jk>);
-			excludeProperties(<js>"name"</js>);
-		}
-	}
-	
-	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().beanFilters(MyBeanFilter.<jk>class</jk>).build();
-	Person p = getPerson();
-	String json = s.serialize(p);  <jc>// Prints "{age:45}"</jc>
-		</p>
-		<p>
-			Note that this is equivalent to specifying the following annotation on the bean class:
-		</p>
-		<p class='bcode'>
-	<ja>@Bean</ja>(excludeProperties={<js>"name"</js>})
-	<jk>public class</jk> Person {
-		...
-	}
-		</p>
-
-		<h6 class='topic'>Define specialized property namers</h6>
-		<p class='bcode'>
-	<jc>// Define bean filter with our own property namer.</jc>
-	<jk>public class</jk> MyBeanFilter <jk>extends</jk> BeanFilterBuilder {
-		<jk>public</jk> MyBeanFilter() {
-			<jk>super</jk>(Person.<jk>class</jk>);
-			propertyNamer(UpperCasePropertyNamer.<jk>class</jk>);
-		}
-	}
-
-	<jc>// Define property namer that upper-cases the property names</jc>	
-	<jk>public class</jk> UpperCasePropertyNamer <jk>implements</jk> PropertyNamer {
-		<ja>@Override</ja>
-		<jk>public</jk> String getPropertyName(String name) {
-			<jk>return</jk> name.toUpperCase();
-		}
-	}
-	
-	<jc>// Serialize to JSON</jc>
-	WriterSerializer s = JsonSerializer.<jsm>create</jsm>().beanFilters(MyBeanFilter.<jk>class</jk>).build();
-	Person person = getPerson();
-	String json = s.serialize(p);  <jc>// Prints "{AGE:45,NAME:'John Smith'}"</jc>
-	
-	<jc>// Parse back into bean</jc>
-	ReaderParser p = JsonParser.<jsm>create</jsm>().beanFilters(MyBeanFilter.<jk>class</jk>).build();
-	person = p.parse(json, Person.class); <jc>// Read back into original object</jc>
-		</p>
-		<p>
-			Note that this is equivalent to specifying the following annotation on the bean class:
-		</p>
-		<p class='bcode'>
-	<ja>@Bean</ja>(propertyNamer=UpperCasePropertyNamer.<jk>class</jk>)
-	<jk>public class</jk> Person {
-		...
-	}
-		</p>
-		
-		<h6 class='topic'>Limiting bean properties to parent bean classes</h6>
-		<p>
-			Occasionally, you may want to limit bean properties to some parent interface.
-			For example, in the <code>RequestEchoResource</code> class in the sample war file, we serialize instances of
-			<code>HttpServletRequest</code> and <code>HttpServletResponse</code>.
-			However, we really only want to serialize the properties defined on those specific APIs, not 
-			vendor-specific methods on the instances of those classes.
-			This can be done through the <code>interfaceClass</code> property of a bean filter.
-		</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.
-			To do so, we can define the following bean filter:
-		</p>
-		<p class='bcode'>
-	<jc>// Define bean filter that limits properties to only those defined on MyClass</jc>
-	<jk>public class</jk> MyBeanFilter <jk>extends</jk> BeanFilterBuilder {
-		<jk>public</jk> MyBeanFilter() {
-			<jk>super</jk>(MyClass.<jk>class</jk>);
-			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>().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>
-		<p>
-			In fact, this is the shortcut used in the <code>RequestEchoResource</code> sample class:
-		</p>
-		<p class='bcode'>
-	<ja>@RestResource</ja>(
-		beanFilters={
-			<jc>// Interpret these as their parent classes, not subclasses</jc>
-			HttpServletRequest.<jk>class</jk>, HttpSession.<jk>class</jk>, ServletContext.<jk>class</jk>
-		}
-	)
-	<jk>public class</jk> RequestEchoResource <jk>extends</jk> RestServletDefault {
-		</p>
-		
-		<h6 class='topic'>Allowing non-public bean classes/methods/fields to be used by the framework</h6>
-		<p>
-			By default, only public classes are interpreted as beans.  Non-public classes are treated as 'other' POJOs 
-			that are typically just serialized to strings using the <code>toString()</code> method.
-			Likewise, by default, only public fields/methods are interpreted as bean properties.
-		</p>
-		<p>
-			The following bean context properties can be used to allow non-public classes/methods/fields to be
-			used by the framework:
-		</p>
-		<ul>
-			<li class='jf'>{@link org.apache.juneau.BeanContext#BEAN_beanClassVisibility}
-			<li class='jf'>{@link org.apache.juneau.BeanContext#BEAN_beanConstructorVisibility}
-			<li class='jf'>{@link org.apache.juneau.BeanContext#BEAN_beanMethodVisibility}
-			<li class='jf'>{@link org.apache.juneau.BeanContext#BEAN_beanFieldVisibility}
-		</ul>
-		<p>
-			Also, specifying a {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotation on non-public 
-			getters/setters/fields will also allow them to be detected by the framework.
-		</p>
-		<p class='bcode'>
-	<jk>public class</jk> MyBean {
-		<jc>// A normal bean property</jc>
-		<jk>public int</jk> f1;    
-		
-		<jc>// Not a bean property even though it's public</jc>
-		<ja>@BeanIgnore</ja>
-		<jk>public int</jk> f2;     
-		
-		<jc>// A bean property even though it's protected</jc>
-		<ja>@BeanProperty</ja>    
-		<jk>protected int</jk> f3;  
-		
-		<jc>// A bean property even though it's private</jc>
-		<ja>@BeanProperty</ja>    
-		<jk>private int</jk> getF3() {...}
-	}
-		</p>
-	</div>
-
-	<!-- ======================================================================================================== -->
-	<a id="PojoSwaps"></a>
-	<h3 class='topic' onclick='toggle(this)'>1.2 - PojoSwap Class</h3>
-	<div class='topic'>
-		<p>
-			{@link org.apache.juneau.transform.PojoSwap PojoSwaps} are a critical component of the Juneau architecture.  
-			They allow the Juneau serializers and parsers to be extended to handle virtually any kind of Java object. 
-		</p>
-		<p>
-			As explained in the overview, Juneau has built-in support for serializing and parsing specific kinds of 
-			objects, like primitive objects, bean, maps, collections, and arrays.  
-			Other kinds of POJOs, such as {@code Date} objects, cannot be serialized properly, since they are not true 
-			beans.  
-			This is where <code>PojoSwaps</code> come into play.
-		</p>
-		<p>
-			The purpose of an <code>PojoSwap</code> is to convert a non-serializable object to a serializable surrogate 
-			form during serialization, and to optionally convert that surrogate form back into the original object 
-			during parsing.
-		</p>
-		<p>
-			For example, the following swap can be used to convert {@link java.util.Date} objects to ISO8601 strings 
-			during serialization, and {@link java.util.Date} objects from ISO8601 string during parsing:
-		</p>
-		<p class='bcode'>
-	<jc>// Sample swap for converting Dates to ISO8601 strings.</jc>
-	<jk>public class</jk> MyDateSwap <jk>extends</jk> StringSwap&lt;Date&gt; {
-		
-		<jc>// ISO8601 formatter.</jc>
-		<jk>private</jk> DateFormat <jf>format</jf> = <jk>new</jk> SimpleDateFormat(<js>"yyyy-MM-dd'T'HH:mm:ssZ"</js>);
-		
-		<jd>/** Converts a Date object to an ISO8601 string. */</jd>
-		<ja>@Override</ja>
-		<jk>public</jk> String swap(BeanSession session, Date o) {
-			<jk>return</jk> <jf>format</jf>.format(o);
-		}
-		
-		<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);
-			}
-		}
-	}
-		</p>
-		<p>
-			The swap above can then be associated with serializers and parsers as the following example shows:
-		</p>
-		<p class='bcode'>
-	<jc>// Sample bean with a Date field.</jc>
-	<jk>public class</jk> MyBean {
-		<jk>public</jk> Date <jf>date</jf> = <jk>new</jk> Date(112, 2, 3, 4, 5, 6);
-	}
-
-	<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>
-	
-	<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>);
-	<jk>int</jk> day = bean.<jf>date</jf>.getDay(); 						<jc>// == 3</jc>
-		</p>
-		<p>
-			In addition, 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 beanContext = <jk>new</jk> BeanContext().pojoSwaps(MyDateSwap.<jk>class</jk>);
-
-	<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 = beanContext.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> SerializeException {
-			<jk>try</jk> {
-				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());
-			} <jk>catch</jk> (Exception e) {
-				<jk>throw new</jk> SerializeException(e);
-			}
-		}
-		
-		<ja>@Override</ja>
-		<jk>public byte</jk>[] unswap(String s, ClassMeta&lt;?&gt; hint) <jk>throws</jk> ParseException {
-			<jk>try</jk> {
-				<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;
-			} <jk>catch</jk> (Exception e) {
-				<jk>throw new</jk> ParseException(e);
-			}
-		}
-	}
-		</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>
-	Serializer serializer = JsonSerializer.<jsm>create</jsm>().pojoSwaps(ByteArrayBase64Swap.<jk>class</jk>).build();
-	ReaderParser parser = JsonParser.<jsm>create</jsm>().pojoSwaps(ByteArrayBase64Swap.<jk>class</jk>).build();
-	
-	<jk>byte</jk>[] a1 = {1,2,3};
-	String s1 = serializer.serialize(a1);		<jc>// Produces "'AQID'"</jc>
-	a1 = parser.parse(s1, <jk>byte</jk>[].<jk>class</jk>);		<jc>// Reproduces {1,2,3}</jc>
-	
-	<jk>byte</jk>[][] a2 = {{1,2,3},{4,5,6},<jk>null</jk>};
-	String s2 = serializer.serialize(a2);		<jc>// Produces "['AQID','BAUG',null]"</jc>
-	a2 = parser.parse(s2, <jk>byte</jk>[][].<jk>class</jk>);		<jc>// Reproduces {{1,2,3},{4,5,6},null}</jc>
-		</p>
-		<p>
-			It should be noted that the sample swaps shown above have already been implemented in the 
-			<a class='doclink' href='../transforms/package-summary.html#TOC'>org.apache.juneau.transforms</a> package.
-			The following are a list of out-of-the-box swaps:
-		</p>
-		<ul class='spaced-list'>
-			<li>{@link org.apache.juneau.transforms.ByteArrayBase64Swap} 
-				- Converts byte arrays to BASE64 encoded strings.
-			<li>{@link org.apache.juneau.transforms.CalendarSwap} 
-				- Swaps for converting <code>Calendar</code> objects to various date format strings.
-			<li>{@link org.apache.juneau.transforms.DateSwap} 
-				- Swaps for converting <code>Date</code> objects to various date format strings.
-			<li>{@link org.apache.juneau.transforms.EnumerationSwap} 
-				- Swaps for converting <code>Enumeration</code> objects to arrays.
-			<li>{@link org.apache.juneau.transforms.IteratorSwap} 
-				- Swaps for converting <code>Iterator</code> objects to arrays.
-			<li>{@link org.apache.juneau.transforms.ReaderSwap} 
-				- Swaps for converting <code>Readers</code> to objects before serialization.
-			<li>{@link org.apache.juneau.transforms.XMLGregorianCalendarSwap} 
-				- Swaps for converting <code>XMLGregorianCalendar</code> objects to ISO8601 strings.
-		</ul>
-		
-		<h6 class='topic'>Valid swapped class types</h6>
-		<p>
-			The swapped class type can be any serializable class type as defined in the 
-			<a href='../../../../overview-summary.html#juneau-marshall.PojoCategories'>POJO categories</a> table.
-		</p>
-	</div>
-	
-
-	<!-- ======================================================================================================== -->
-	<a id="PojoSwaps_OneWay"></a>
-	<h3 class='topic' onclick='toggle(this)'>1.3 - One-Way PojoSwaps</h3>
-	<div class='topic'>
-		<p>
-			In the previous section, we defined two-way swaps, meaning swaps where the original objects could be 
-			reconstructing during parsing. 
-			However, there are certain kinds of POJOs that we may want to support for serializing, but that are not 
-			possible to reconstruct during parsing.  
-			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.  
-			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.  
-			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.  
-			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>
-	Serializer serializer = JsonSerializer.<jsm>create</jsm>().pojoSwaps(IteratorSwap.<jk>class</jk>).build();
-	
-	<jc>// Construct an iterator we want to serialize.</jc>
-	Iterator iterator = <jk>new</jk> ObjectList(1,2,3).iterator();
-	
-	<jc>// Serialize our Iterator</jc>
-	String s = serializer.serialize(iterator);		<jc>// Produces "[1,2,3]"</jc>
-	
-	<jc>// Try to parse it.</jc>
-	ReaderParser parser = JsonParser.<jsm>create</jsm>().pojoSwaps(IteratorSwap.<jk>class</jk>).build();
-	iterator = parser.parse(s, Iterator.<jk>class</jk>);		<jc>// Throws ParseException!!!</jc>
-		</p>
-	</div>
-
-	<!-- ======================================================================================================== -->
-	<a id="StopClasses"></a>
-	<h3 class='topic' onclick='toggle(this)'>1.4 - Stop Classes</h3>
-	<div class='topic'>
-		<p>
-			Occasionally, you may want to limit bean properties to only those defined on a parent class or interface.  
-			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. 
-			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() {
-			setInterfaceClass(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>().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. 
-			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="SurrogateClasses"></a>
-	<h3 class='topic' onclick='toggle(this)'>1.5 - Surrogate Classes</h3>
-	<div class='topic'>
-		<p>
-			Surrogate classes are very similar in concept to one-way <code>PojoSwaps</code> except they represent a 
-			simpler syntax.
-		</p>
-		<p>
-			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) {
-			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>
-	Serializer serializer = 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="ToObjectMaps"></a>
-	<h3 class='topic' onclick='toggle(this)'>1.6 - Serializing to ObjectMaps</h3>
-	<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>
-	</div>
-</div>
 </body>
 </html>
\ No newline at end of file



Mime
View raw message