Base toolkit for serializers, parsers, and bean contexts

##### Table of Contents

## 1 - Bean Context API

The {@link org.apache.juneau.BeanContext} class is the core class in the Juneau architecture. It serves multiple functions...

- It provides the ability to create instances of {@link org.apache.juneau.BeanMap BeanMaps}.
- It serves as a repository for {@link org.apache.juneau.transform.BeanFilter BeanFilters} and {@link org.apache.juneau.transform.PojoSwap PojoSwaps}, which are used to tailor how Java objects are handled.
- It's used by all built-in {@link org.apache.juneau.serializer.Serializer Serializers} and {@link org.apache.juneau.parser.Parser Parsers} for working with POJOs in a consistent way.

### 1.1 - The BeanMap class

The {@link org.apache.juneau.BeanMap} class allows you to access the properties of a bean through the familiar {@code Map} interface. So, for example, you can use the {@code Map.get(key)} method to retrieve a property value in lieu of it's getter method, and the {@code Map.put(key, value)} method to set a property value in lieu of it's setter method.

The serialization and parsing of beans in Juneau is accomplished by wrapping Java beans inside instances of the class {@code BeanMap}.

Note: Instances of {@link org.apache.juneau.BeanMap} objects are always retrieved through the {@link org.apache.juneau.BeanContext} class. You cannot instantiate {@code BeanMaps} directly since the rules for defining what constitutes a bean depend on various settings in the bean context.

In general, the performance on using the {@link org.apache.juneau.BeanMap} class to access properties is equivalent to using reflection directly.

See the {@link org.apache.juneau.BeanMap} javadoc for more information.

### 1.2 - The BeanContext and BeanSession classes

The {@link org.apache.juneau.BeanContext} and {@link org.apache.juneau.BeanSession} classes are the workhorse class used to wrap Java beans inside {@link org.apache.juneau.BeanMap BeanMaps}. There are several options provided on the {@link org.apache.juneau.BeanContext} class to tailor the definition of a bean.

The following is a very simple example of how to wrap a bean inside a {@link org.apache.juneau.BeanMap} wrapper and use the wrapper interface to get and set property values on the bean. In this case, we're using the DEFAULT bean context.

// A sample pseudo bean class. public class Person { public String getName(); public void setName(String name); public int getAge(); public void setAge(int age); } // Get an instance of a bean context. // In this case, just use the default bean context. BeanSession beanSession = BeanContext.DEFAULT.createSession(); // Create an instance of our bean and wrap it in a bean map. Person p = new Person(); BeanMap<Person> m = beanSession.toBeanMap(p); // Set some properties on the bean. m.put("name", "John Smith"); m.put("age", 21); // Print out bean properties. System.out.println(m.get("name")); // Prints "John Smith" System.out.println(p.getName()); // Prints "John Smith" System.out.println(m.get("age")); // Prints 21 System.out.println(p.getAge()); // Prints 21 // The bean context class can also create instances of bean maps. m = beanContext.newBeanMap(Person.class); p = m.getBean(); // Get the new wrapped bean. // The bean context class can also create instances of beans. p = beanContext.newBean(Person.class);

There are 2 ways to get an instance of a {@link org.apache.juneau.BeanContext}:

// Use one of the default bean contexts. BeanContext beanContext = BeanContext.DEFAULT; // Use the PropertyStore class. beanContext = new PropertyStore().pojoSwaps(DateSwap.ISO8601DT.class).getBeanContext();

The {@link org.apache.juneau.BeanContext} class is a highly-customizable class. See the {@link org.apache.juneau.BeanContext} javadoc for more information.

### 1.3 - Bean annotations

Juneau provides the following annotations that can be used to fine-tune what properties are associated with beans:

- {@link org.apache.juneau.annotation.Bean} - Fine-tune properties associated with beans.
- {@link org.apache.juneau.annotation.BeanProperty} - Fine-tune bean properties (fields / getters / setters).
- {@link org.apache.juneau.annotation.BeanConstructor} - Define read-only bean properties that can only be set through constructor arguments.
- {@link org.apache.juneau.annotation.BeanIgnore} - Prevent bean classes/methods/fields from being interpreted as bean constructs.

These annotations always override the settings defined in the {@link org.apache.juneau.BeanContext} class.

For example, the following bean class will only have one property associated with it, "name", since it's the only one listed in the list of properties.

// Bean with only one 'name' property @Bean(properties="name") public class Person { public String getName(); public void setName(String name); public int getAge(); public void setAge(int age); }

When this bean is serialized using one of the {@link org.apache.juneau.serializer.Serializer Serializers}, the age property will be ignored.

Using the @Bean and @BeanProperty annotations, it's also possible to include non-standard properties (for example, getters or setters with non-standard names), or override the names of properties (for example, {@code "Name"} or {@code "fullName"} instead of {@code "name"}).

It should be noted that the {@link org.apache.juneau.transform.BeanFilter} class can also be used to exclude properties from beans. However, only the annotations can be used to include non-standard properties or override property names.

See the {@link org.apache.juneau.annotation.Bean}, {@link org.apache.juneau.annotation.BeanProperty}, {@link org.apache.juneau.annotation.BeanConstructor}, and {@link org.apache.juneau.annotation.BeanIgnore} javadocs for more information.