Apache Commons BeanUtils

1. Overview

Apache Commons BeanUtils contains all the tools necessary for working with Java Beans. Further, this library combines BeanUtils with Commons Collections to provide unified services for collections of beans.

Basically, a bean is a simple Java class containing fields, getters, setters, and a no-argument constructor.

Accordingly, Java provides reflection and introspection capabilities to identify getter and setter methods and call them dynamically. However, these APIs can be difficult to learn and may require developers to write boilerplate code to perform simple operations.

In this tutorial, we’ll explore some of the primary uses of Apache Commons BeanUtils while dealing with Java Beans.

2. Maven Dependencies

Let’s include the Maven dependency we need in the POM file before using it:

<dependency>
    <groupId>commons-beanutils</groupId>
    <artifactId>commons-beanutils</artifactId>
    <version>1.9.4</version>
</dependency>

In this case, common-beanutils is the only dependency we need for Apache Commons BeanUtils.

3. Creating a Java Bean

To begin with, let’s create two bean classes, Course and Student, with typical getter and setter methods:

public class Course {
    private String name;
    private List<String> codes;
    private Map<String, Student> enrolledStudent = new HashMap<>();

    //  standard getters/setters
}

public class Student {
    private String name;

    //  standard getters/setters
}

Thus, we have a Course class that has a course name, course codes, and enrolled students. Furthermore, we can identify enrolled students by a unique enrollment ID. In addition, the Course class maintains enrolled students in a Map object where enrollment ID is a key, and the student object is the value.

4. Setting Properties

At the outset, we can divide bean properties into three categories:

• simple properties
• indexed properties
• mapped properties

Let’s look at each type.

4.1. Simple Property

Further, single-value properties are also called simple or scalar. Specifically, their value might be a primitive such as int and float, or complex type objects.

BeanUtils has a PropertyUtils class that we can use to modify simple properties in a Java Bean. In particular, we use the static method PropertyUtils.setSimpleProperty(Object bean, String name, Object value) to set the value of a given simple property of the specified bean without type conversions.

Let’s use a basic example:

Course course = new Course();
String name = "Computer Science";
List<String> codes = Arrays.asList("CS", "CS01");

PropertyUtils.setSimpleProperty(course, "name", name);
PropertyUtils.setSimpleProperty(course, "codes", codes);

Thus, we set the properties for a Course bean.

4.2. Indexed Property

On the other hand, an indexed property has a collection as a value. We can access the individual elements of the collection using an index number. Naturally, as an extension to JavaBean, BeanUtils considers java.util.List type values as indexed as well.

Accordingly, we can modify an indexed property element value using the static method PropertyUtils.setIndexedProperty(Object bean,String name,Object value). It sets the value of the specified indexed property of a particular bean, without type conversions.

Again, let’s consider some example code:

PropertyUtils.setIndexedProperty(course, "codes[1]", "CS02");

In this case, we modify the indexed property for a collection of codes associated with a Course object.

4.3. Mapped Property

Lastly, any property that has a java.util.Map as the underlying type is called a mapped property. Of course, we can use BeanUtils to update an individual value in a map using a String-valued key. For this, we use the static method PropertyUtils.setMappedProperty(Object bean,String name,Object value). The name argument is the propertyname(key) of the property value to be set.

Let’s see how to use it:

Student student = new Student();
String studentName = "Joe";
student.setName(studentName);

PropertyUtils.setMappedProperty(course, "enrolledStudent(ST-1)", student);

This example modifies the value in a mapped property called enrolledStudent for a map of enrolled students.

5. Get Property Value by Property Name

Accordingly, we can get a property value from a bean by its name via the static methods of the org.apache.commons.beanutils.PropertyUtils class. Further, we use these methods to access simple, indexed, and mapped properties dynamically at runtime.

5.1. Simple Property

Specifically, we use the static method PropertyUtils.getSimpleProperty(Object bean,String name) to get the value of the specified simple property of the specified bean, without type conversions.

We can write a test method to get the value for a simple property by name:

@Test
public void givenCourse_whenGettingSimplePropertyValueUsingPropertyUtil_thenValueReturned() throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    Course course = new Course();
    String name = "Computer Science";
    List codes = Arrays.asList("CS101","CS102");
    CourseService.setValues(course, name, codes);
    String courseName = (String) PropertyUtils.getSimpleProperty(course, "name");

    assertEquals("Computer Science", courseName);
}

In this example, we use the getSimpleProperty() to retrieve the name property from the Course bean.

5.2. Indexed Property

We use the static method PropertyUtils.getIndexedProperty(Object bean,String name) to get the value of the specified indexed property. Here, name represents the propertyname[index] of the property value to be extracted.

Let’s get the value for an indexed property:

@Test
public void givenCourse_whenGettingIndexedPropertyValueUsingPropertyUtil_thenValueReturned() throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    Course course = new Course();
    String name = "Computer Science";
    List codes = Arrays.asList("CS101","CS102");
    CourseService.setValues(course, name, codes);
    String secondCode = (String) PropertyUtils.getIndexedProperty(course, "codes[1]");
		
    assertEquals("CS102", secondCode);
}

In this case, we use getIndexedProperty() to retrieve the element at index 1 from the codes list.

Alternatively, we can use the overloaded version getIndexedProperty(Object bean,String name,int index), in which the name argument is the simple property name of the property value to be extracted, and the index argument is the index of the property value to be extracted.

5.3. Mapped Property

We use the static method PropertyUtils.getMappedProperty(Object bean,String name) to get the value of a mapped property in the specified bean, with no type conversions. In this, the name argument is the propertyname(key) of the property value to be extracted.

Let’s write a test method to get the value for a mapped property:

@Test
public void givenCourse_whenGettingMappedPropertyValueUsingPropertyUtil_thenValueReturned() throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    Course course = new Course();
    String name = "Computer Science";
    List codes = Arrays.asList("CS101","CS102");
    CourseService.setValues(course, name, codes);
	
    Student student = new Student();
    student.setName("John Doe");
    CourseService.setMappedValue(course, STUDENT_ID, student);
    Student enrolledStudent = (Student) PropertyUtils.getMappedProperty(course, "enrolledStudent(" + STUDENT_ID + ")");
    
    assertEquals("John Doe", enrolledStudent.getName());
}

In this example, we create a Student and add it to the enrolledStudent map. Then, we use getMappedProperty() to retrieve the value associated with the STUDENT_ID key from the enrolledStudent map.

On the other hand, we can use the overloaded version getMappedProperty(Object bean,String name,String key), in which the name argument is the mapped property name of the property value to be extracted, and the key argument is the key of the property value to be extracted.

6. Nested Property Access

If a property value is an object and we need to access a property value inside that object, it’s called accessing a nested property. We can use PropertyUtils to access and modify nested properties as well.

Let’s assume we want to access the name property of the Student class through the Course object:

String name = course.getEnrolledStudent("ST-1").getName();

Of course, we can access the nested property values using the getNestedProperty method in PropertyUtils:

Student student = new Student();
String studentName = "Joe";
student.setName(studentName);

String nameValue = (String) PropertyUtils.getNestedProperty(course, "enrolledStudent(ST-1).name");

Further, we can modify the nested property using the setNestedProperty method in PropertyUtils.

7. Copying Bean Properties

Copying properties from one object to another object can be tedious and error-prone for developers. Hence, BeanUtils provides targeted options for this action.

7.1. Copy All Properties

The BeanUtils class provides a copyProperties method that copies the property values of the source object to the target object, where the property name is the same in both objects.

Let’s create another bean class. It has the same properties as Course, apart from a students property that replaces the enrolledStudent Course property. In particular, we name that new class CourseEntity:

public class CourseEntity {
    private String name;
    private List<String> codes;
    private Map<String, Student> students = new HashMap<>();

    //  standard getters/setters
}

Now, we copy all properties of the Course object to the CourseEntity object:

Course course = new Course();
course.setName("Computer Science");
course.setCodes(Arrays.asList("CS"));
course.setEnrolledStudent("ST-1", new Student());

CourseEntity courseEntity = new CourseEntity();
BeanUtils.copyProperties(courseEntity, course);

Notably, the code above copies the properties with the same name only. Therefore, it doesn’t copy the property enrolledStudent in the Course class because there’s no property with the same name in the CourseEntity class.

7.2. Ignore Null Fields During Copy

Sometimes, it can be handy to copy only non-null fields. To do so, we can define a custom BeanUtilsBean and override the definition of copyProperty():

public class IgnoreNullBeanUtilsBean extends BeanUtilsBean {
    @Override
    public void copyProperty(Object dest, String name, Object value) throws IllegalAccessException, InvocationTargetException {
        if (value != null) {
            super.copyProperty(dest, name, value);
        }
    }
}

As we can see, the copy proceeds only if the initial property value isn’t null.

Let’s now test the code:

Course originalCourse = new Course();
originalCourse.setName(null);
originalCourse.setCodes(Arrays.asList("CS"));
originalCourse.setEnrolledStudent("ST-1", new Student());

CourseEntity destCourse = new CourseEntity();
destCourse.setName("entityName");

IgnoreNullBeanUtilsBean ignoreNullBeanUtilsBean = new IgnoreNullBeanUtilsBean();
ignoreNullBeanUtilsBean.copyProperties(destCourse, originalCourse);
        
assertEquals("entityName", destCourse.getName());
assertThat(destCourse.getCodes()).containsExactly("CS");
assertThat(destCourse.getStudents()).isEmpty();

There are several steps to the code above:

1. instantiate a Course object with a null name
2. create a CourseEntity object with the name entityName
3. copy all non-null properties from the Course object to their corresponding property in the CourseEntity object

As expected, we can check that the name of the CourseEntity object didn’t change. In a word, it ignores the null name in the Course object.

8. Conclusion

In this quick article, we went over the utility classes provided by BeanUtils. We also looked into different types of properties and how we can set, get, and modify their values.

Finally, we looked into accessing nested property values and copying properties from one object to another.

Of course, we can use reflection and introspection capabilities in the Java SDK to access properties dynamically; however, it can be difficult to learn and requires some boilerplate code. Instead, we might benefit from BeanUtils to access and modify these values with a single method call.