juneau-doc/docs/Topics/02.juneau-marshall/11.Transforms/04.PerMediaTypePojoSwaps.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.
 ***************************************************************************************************************************/
 -->

Per-media-type PojoSwaps

<p>
	Swaps can also be defined per-media-type.		
</p>
<p>	
	The {@link oaj.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 
	by media type.
	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.  
	One for JSON, one for XML, and one for all other types.
</p>
<p class='bpcode w800'>
	<jk>public class</jk> PojoSwapTest {

		<jk>public static class</jk> MyPojo {}

		<jk>public static class</jk> MyJsonSwap <jk>extends</jk> StringSwap&lt;MyPojo&gt; {
			<ja>@Override</ja> <jc>/* PojoSwap */</jc>
			<jk>public</jk> MediaType[] forMediaTypes() {
				<jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"&#42;/json"</js>);
			}
			<ja>@Override</ja> <jc>/* PojoSwap */</jc>
			<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> StringSwap&lt;MyPojo&gt; {
			<ja>@Override</ja> <jc>/* PojoSwap */</jc>
			<jk>public</jk> MediaType[] forMediaTypes() {
				<jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"&#42;/xml"</js>);
			}
			<ja>@Override</ja> <jc>/* PojoSwap */</jc>
			<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> StringSwap&lt;MyPojo&gt; {
			<ja>@Override</ja> <jc>/* PojoSwap */</jc>
			<jk>public</jk> MediaType[] forMediaTypes() {
				<jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"&#42;/*"</js>);
			}
			<ja>@Override</ja> <jc>/* PojoSwap */</jc>
			<jk>public</jk> String swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception {
				<jk>return</jk> <js>"It's something else!"</js>;
			}
		}

		<ja>@Test</ja>
		<jk>public void</jk> doTest() <jk>throws</jk> Exception {

			SerializerGroup g = SerializerGroup.<jsm>create</jsm>()
				.append(JsonSerializer.<jk>class</jk>, XmlSerializer.<jk>class</jk>, HtmlSerializer.<jk>class</jk>)
				.sq()
				.pojoSwaps(MyJsonSwap.<jk>class</jk>, MyXmlSwap.<jk>class</jk>, MyOtherSwap.<jk>class</jk>)
				.build();

			MyPojo myPojo = <jk>new</jk> MyPojo();

			String json = g.getWriterSerializer(<js>"text/json"</js>).serialize(myPojo);
			<jsm>assertEquals</jsm>(<js>"'It\\'s JSON!'"</js>, json);

			String xml = g.getWriterSerializer(<js>"text/xml"</js>).serialize(myPojo);
			<jsm>assertEquals</jsm>(<js>"&lt;string&gt;It's XML!&lt;/string&gt;"</js>, xml);

			String html = g.getWriterSerializer(<js>"text/html"</js>).serialize(myPojo);
			<jsm>assertEquals</jsm>(<js>"&lt;string&gt;It's something else!&lt;/string&gt;"</js>, html);
		}
	}
</p>
<p>
	When multiple swaps match the same media type, a best-match algorithm is applied to find the correct
	swap to use.
</p>
<p>
	In later sections we describe how annotations can be used to shorten this syntax:
</p>
<p class='bpcode w800'>
	<ja>@Swaps</ja>({MyJsonSwap.<jk>class</jk>,MyXmlSwap.<jk>class</jk>,MyOtherSwap.<jk>class</jk>})
	<jk>public static class</jk> MyPojo {}

	<ja>@Swap</ja>(mediaTypes=<js>"&#42;/json"</js>)
	<jk>public static class</jk> MyJsonSwap <jk>extends</jk> PojoSwap&lt;MyPojo,String&gt; {...}

	<ja>@Swap</ja>(mediaTypes=<js>"&#42;/xml"</js>)
	<jk>public static class</jk> MyXmlSwap <jk>extends</jk> PojoSwap&lt;MyPojo,String&gt; {...}

	<ja>@Swap</ja>(mediaTypes=<js>"&#42;/*"</js>)
	<jk>public static class</jk> MyOtherSwap <jk>extends</jk> PojoSwap&lt;MyPojo,String&gt; {...}
</p>