Skip to main content

MarshalledFilter

MarshalledFilter is the class in org.apache.juneau.marshall that customizes how a POJO or bean is handled during serialization and parsing. It is the programmatic, runtime equivalent of the @Marshalled and @BeanType annotations combined — it is the single concrete BeanFilter implementation in the framework.

In normal use you never construct a MarshalledFilter yourself. When Juneau analyzes a class it reads the @Marshalled and @BeanType annotations (plus any config-level overrides) and builds a MarshalledFilter internally — this is what ClassMeta and MarshalledBeanMetaInitializer do behind the scenes. The filter is then consulted for every property during marshalling.

What a Filter Controls​

A MarshalledFilter captures both the format-side (@Marshalled) and model-side (@BeanType) decisions for a class:

Filter attributeAnnotation sourcePurpose
properties@BeanType(properties)Property inclusion and ordering.
excludeProperties@BeanType(excludeProperties)Properties to omit.
readOnlyProperties@BeanType(readOnlyProperties)Serialized but not parsed.
writeOnlyProperties@BeanType(writeOnlyProperties)Parsed but not serialized.
propertyNamer@BeanType(propertyNamer)Property-name transformation.
interfaceClass@BeanType(interfaceClass)Limit properties to an interface.
stopClass@BeanType(stopClass)Halt hierarchy traversal.
unsortedProperties@BeanType(unsorted)Opt out of alphabetical sorting.
fluentSetters@BeanType(findFluentSetters)Detect fluent setters.
typeName@Marshalled(typeName)Bean dictionary type name.
dictionary@Marshalled(dictionary)Bean dictionary classes.
implClass@Marshalled(implClass)Concrete class for an interface/abstract type.
interceptor@Marshalled(interceptor)Getter/setter interceptor.
example@Marshalled(example)POJO example value.

Building a Filter Programmatically​

For advanced or dynamic scenarios you can build a filter directly with MarshalledFilter.create(...), which returns a Builder. The builder mirrors the annotation attributes:

MarshalledFilter filter = MarshalledFilter
    .create(ClassInfo.of(Address.class))
    .properties("id,name,email")     // include only these, in this order
    .excludeProperties("password")   // never serialize sensitive data
    .readOnlyProperties("id")        // id is serialized but ignored on parse
    .typeName("address")             // dictionary name
    .unsortedProperties()            // keep declared order
    .build();

The builder also has two apply methods used by the framework to fold annotations into a filter:

  • applyAnnotations(List<Marshalled>) — applies the marshalling-side attributes (typeName, interceptor, implClass, dictionary, example).
  • applyBeanTypeAnnotations(List<BeanType>) — applies the bean-modeling attributes (properties, excludeProperties, readOnly/writeOnly, propertyNamer, interfaceClass, stopClass, unsorted, findFluentSetters).

The Filter at Runtime​

Once built, a MarshalledFilter exposes read-only getters (getProperties(), getExcludeProperties(), getExample(), getTypeName(), getImplClass(), getInterfaceClass(), getStopClass(), getBeanDictionary(), ...) that the serializer and parser query. It also implements the interceptor hooks readProperty(bean, name, value) (on serialize) and writeProperty(bean, name, value) (on parse), delegating to the configured BeanInterceptor.

note

Because a filter is derived from @Marshalled and @BeanType, the recommended way to customize a class is to declare those annotations (or their config-level equivalents) rather than building filters by hand. Reach for MarshalledFilter.create(...) only when the class cannot be annotated or the configuration must be computed at runtime.

See Also