juneau-doc/docs/Topics/02.juneau-marshall/11.Transforms/05.OneWayPojoSwaps.html

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

One-way PojoSwaps

<p>
	In the previous sections, 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='bpcode w800'>
	<jk>public class</jk> IteratorSwap <jk>extends</jk> PojoSwap&lt;Iterator,List&gt; {
		<ja>@Override</ja> <jc>/* PojoSwap */</jc>
		<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 oaj.parser.ParseException} 
	to be thrown.
</p>
<p class='bpcode w800'>
	<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>