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 leu of it's getter method, and the {@code Map.put(key, value)} method to set a property value in leu 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 class
The {@link org.apache.juneau.BeanContext} class is 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.
BeanContext beanContext = BeanContext.DEFAULT ;
// Create an instance of our bean and wrap it in a bean map.
Person p = new Person();
BeanMap<Person> m = beanContext.forBean(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 3 ways to get an instance of a {@link org.apache.juneau.BeanContext}:
// Use one of the default bean contexts.
BeanContext beanContext = BeanContext.DEFAULT ;
// Create a context from scratch with your own settings.
beanContext = new BeanContext().addPojoSwaps(DateSwap.ISO8601DT.class );
// Clone and modify an existing context.
beanContext = BeanContext.DEFAULT .clone().addPojoSwaps(DateSwap.ISO8601DT.class );
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.