Skip navigation links

Package org.apache.juneau

Base toolkit for serializers, parsers, and bean contexts

See: Description

Package org.apache.juneau Description

Base toolkit for serializers, parsers, and bean contexts

Table of Contents
  1. Bean Context API

    1. The BeanMap class

    2. The BeanContext class

    3. Bean annotations

1 - Bean Context API

The BeanContext class is the core class in the Juneau architecture. It serves multiple functions...

  • It provides the ability to create instances of BeanMaps.
  • It serves as a repository for BeanFilters and PojoSwaps, which are used to tailor how Java objects are handled.
  • It's used by all built-in Serializers and Parsers for working with POJOs in a consistent way.

1.1 - The BeanMap class

The BeanMap class allows you to access the properties of a bean through the familiar Map interface. So, for example, you can use the Map.get(key) method to retrieve a property value in lieu of it's getter method, and the 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 BeanMap.

Note: Instances of BeanMap objects are always retrieved through the BeanContext class. You cannot instantiate 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 BeanMap class to access properties is equivalent to using reflection directly.

See the BeanMap javadoc for more information.

1.2 - The BeanContext and BeanSession classes

The BeanContext and BeanSession classes are the workhorse class used to wrap Java beans inside BeanMaps. There are several options provided on the BeanContext class to tailor the definition of a bean.

The following is a very simple example of how to wrap a bean inside a 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 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 BeanContext class is a highly-customizable class. See the 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:

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

These annotations always override the settings defined in the 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 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, "Name" or "fullName" instead of "name").

It should be noted that the 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 Bean, BeanProperty, BeanConstructor, and BeanIgnore javadocs for more information.

Skip navigation links

Copyright © 2017 Apache. All rights reserved.