org.apache.juneau.package.html Maven / Gradle / Ivy
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.