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

Interface Filters

<p>
	Occasionally, you may want to limit bean properties to only those defined on a parent class or interface.  
	This is accomplished through interface filters.
</p>
<p>
	Interface filters are defined through the following:
</p>
<ul class='javatree'>
	<li class='jf'>{@link oaj.BeanContext#BEAN_beanFilters}
	<li class='ja'>{@link oaj.annotation.Bean#interfaceClass() Bean(interfaceClass)}
	<li class='jm'>{@link oaj.transform.BeanFilterBuilder#interfaceClass(Class)}
</ul>
<p>
	For example, let's define the following interface and implementation:
</p>
<p class='bpcode w800'>
	<jc>// Interface</jc>
	<jk>public class</jk> MyInterface {
		<jk>public</jk> String getFoo();
	}

	<jc>// Implementation</jc>
	<jk>public class</jk> MyInterfaceImpl <jk>implements</jk> MyInterface {
		<jk>public</jk> String getFoo() {...}
		<jk>public</jk> String getBar() {...}
	}
</p>
<p>
	Suppose we only want to render the properties defined on our interface, not the implementation. 
	To do so, we can define the following bean filter:
</p>
<p class='bpcode w800'>
	<jc>// Define transform that limits properties to only those defined on MyClass</jc>
	<jk>public class</jk> MyInterfaceFilter <jk>extends</jk> BeanFilter&lt;MyInterface&gt; {
		<jk>public</jk> MyInterfaceFilter() {
			interfaceClass(MyInterface.<jk>class</jk>);
		}
	}
</p>
<p>
	When serialized, the serialized bean will only include properties defined on the interface.
</p>
<p class='bpcode w800'>
	WriterSerializer s = JsonSerializer
		.<jsm>create</jsm>()
		.simple()
		.beanFilters(MyInterfaceFilter.<jk>class</jk>)
		.build();
		
	MyInterface o = <jk>new</jk> MyInterfaceImpl();
	
	<jc>// Prints "{foo:'foo'}"</jc>
	<jc>// bar is ignored because it's not on the interface</jc>
	String json = s.serialize(o);  
</p>	
<p>
	The {@link oaj.BeanContextBuilder#beanFilters(Object...)} method will automatically interpret any 
	non-<c>BeanFilter</c> classes passed in as meaning interface classes. 
	So in the previous example, the <c>BeanFilter</c> class could have been avoided altogether by just 
	passing in <c>MyInterface.<jk>class</jk></c> to the serializer, like so:
</p>
<p class='bpcode w800'>
	WriterSerializer s = JsonSerializer
		.<jsm>create</jsm>()
		.beanFilters(MyInterface.<jk>class</jk>)  <jc>Shortcut!</jc>
		.build();
</p>
<p>
	The annotation equivalent is {@link oaj.annotation.Bean#interfaceClass() Bean#interfaceClass()}.
</p>
<p class='bpcode w800'>
	<ja>@Bean</ja>(interfaceClass=MyInterface.<jk>class</jk>)
	<jk>public class</jk> MyInterfaceImpl <jk>implements</jk> MyInterface {
		<jk>public</jk> String getFoo() {...}
		<jk>public</jk> String getBar() {...}
	}
</p>
<p>
	The annotation can be used in a couple of ways.
</p>
<p>
	Using the annotation on an interface will be inherited by all children.
</p>
<p class='bpcode w800'>
	<ja>@Bean</ja>(interfaceClass=MyInterface.<jk>class</jk>)
	<jk>public class</jk> MyInterface {
		<jk>public</jk> String getFoo();
	}
</p>
<p>
	The annotation can be used on parent classes as well.
	Child beans will only serialize properties defined on the parent class.
<p class='bpcode w800'>
	<ja>@Bean</ja>(interfaceClass=MyAbstractClass.<jk>class</jk>)
	<jk>public abstract class</jk> MyAbstractClass {
		<jk>public</jk> String getFoo() {...};
	}
</p>