Package org.apache.juneau.marshall

Class MarshallingContext

java.lang.Object
org.apache.juneau.marshall.Context
org.apache.juneau.marshall.MarshallingContext
All Implemented Interfaces:
BeanTypeResolver, ConversionFinder
public class MarshallingContext extends Context implements ConversionFinder, BeanTypeResolver
Bean context.

This class servers multiple purposes:

  • Provides the ability to wrap beans inside Map interfaces.
  • Serves as a repository for metadata on POJOs, such as associated @Marshalled annotations, PropertyNamers, etc... which are used to tailor how POJOs are serialized and parsed.

All serializers and parsers use this context so that they can handle POJOs using a common framework.

Bean Contexts

Bean contexts are created through the MarshallingContext.create() and MarshallingContext.Builder.build() methods.
These context objects are read-only, reusable, and thread-safe.

Each bean context maintains a cache of ClassMeta objects that describe information about classes encountered. These ClassMeta objects are time-consuming to construct. Therefore, instances of MarshallingContext that share the same "MarshallingContext.*" property values share the same cache. This allows for efficient reuse of ClassMeta objects so that the information about classes only needs to be calculated once. Because of this, many of the properties defined on the MarshallingContext class cannot be overridden on the session.

Bean Sessions

Whereas MarshallingContext objects are permanent, unchangeable, cached, and thread-safe, MarshallingSession objects are ephemeral and not thread-safe. They are meant to be used as quickly-constructed scratchpads for creating bean maps. BeanMap objects can only be created through the session.

MarshallingContext configuration properties

BeanContexts have several configuration properties that can be used to tweak behavior on how beans are handled. These are denoted as the static BEAN_* fields on this class.

Some settings (e.g. MarshallingContext.Builder.beansRequireDefaultConstructor()) are used to differentiate between bean and non-bean classes. Attempting to create a bean map around one of these objects will throw a BeanRuntimeException. The purpose for this behavior is so that the serializers can identify these non-bean classes and convert them to plain strings using the Object.toString() method.

Some settings (e.g. MarshallingContext.Builder.beanFieldVisibility(Visibility)) are used to determine what kinds of properties are detected on beans.

Some settings (e.g. MarshallingContext.Builder.beanMapPutReturnsOldValue()) change the runtime behavior of bean maps.

Example:

// Construct a context from scratch. MarshallingContext marshallingContext = MarshallingContext .create() .beansRequireDefaultConstructor() .notBeanClasses(Foo.class) .build();

Bean Maps

BeanMaps are wrappers around Java beans that allow properties to be retrieved and set using the common Map.put(Object,Object) and Map.get(Object) methods.

Bean maps are created in two ways...

  1. MarshallingSession.toBeanMap() - Wraps an existing bean inside a Map wrapper.
  2. MarshallingSession.newBeanMap() - Create a new bean instance wrapped in a Map wrapper.
Example:

// A sample bean class public class Person { public String getName(); public void setName(String name); public int getAge(); public void setAge(int age); } // Create a new bean session MarshallingSession session = MarshallingContext.DEFAULT.createSession(); // Wrap an existing bean in a new bean map BeanMap<Person> map1 = session.toBeanMap(new Person()); map1.put("name", "John Smith"); map1.put("age", 45); // Create a new bean instance wrapped in a new bean map BeanMap<Person> map2 = session.newBeanMap(Person.class); map2.put("name", "John Smith"); map2.put("age", 45); Person person = map2.getBean(); // Get the bean instance that was created.

Notes:
  • This class is thread safe and reusable.
See Also: