(0) Rationale

Most Java developers are used to creating Java classes that conform to the JavaBeans naming patterns for property getters and setters. It is natural to then access these methods directly, using calls to the corresponding getXxx and setXxx methods. However, there are some occasions where dynamic access to Java object properties (without compiled-in knowledge of the property getter and setter methods to be called) is needed. Example use cases include:

• Building scripting languages that interact with the Java object model (such as the Bean Scripting Framework).
• Building template language processors for web presentation and similar uses (such as JSP or Velocity).
• Building custom tag libraries for JSP and XSP environments (such as Jakarta Taglibs, Struts, Cocoon).
• Consuming XML-based configuration resources (such as Ant build scripts, web application deployment descriptors, Tomcat's server.xml file).

The Java language provides Reflection and Introspection APIs (see the java.lang.reflect and java.beans packages in the JDK Javadocs). However, these APIs can be quite complex to understand and utilize. The proposed BeanUtils component provides easy-to-use wrappers around these capabilities.

(1) Scope of the Package

This proposal is to create a package of Java utility methods for accessing and modifying the properties of arbitrary JavaBeans. No dependencies outside of the JDK are required, so the use of this package is very lightweight.

In addition to wrapping the reflection and introspection APIs of the standard JDK, BeanUtils components shall support a syntax for directly accessing nested and indexed properties, in a manner that will be familar to users of scripting languages like JavaScript. For example, the following property accessor expressions are supported:

• customer - Equivalent to getCustomer().
• customer.address - Equivalent to getCustomer().getAddress().
• customer.address[2].street - Equivalent to getCustomer().getAddress(2).getStreet() (access to indexed properties also works if the underlying property is an array rather than providing indexed getter and setter methods).

(1.5) Interaction With Other Packages

BeanUtils relies only on standard JDK 1.2 (or later) APIs for production deployment. It utilizes the JUnit unit testing framework for developing and executing unit tests, but this is of interest only to developers of the component. BeanUtils will also be a dependency for several future proposed components for the Jakarta Commons subproject.

No external configuration files are utilized.

(2) Initial Source of the Package

The three original Java classes (BeanUtils, ConvertUtils, and PropertyUtils) are an integral part of the Struts Framework. However, they have very few dependencies on other aspects of Struts, and those dependencies have been removed in the proposed code base. Once accepted and released as a Jakarta Commons component, Struts will be modified to use the Commons version of these classes, and its internal versions will be deprecated.

The proposed package name for the new component is org.apache.commons.beanutils.

(3) Required Jakarta-Commons Resources

• CVS Repository - New directory beanutils in the jakarta-commons CVS repository. All initial committers are already committers on jakarta-commons, so no additional user setups are required.
• Mailing List - Discussions will take place on the general jakarta-commons@jakarta.apache.org mailing list. To help list subscribers identify messages of interest, it is suggested that the message subject of messages about this component be prefixed with [BeanUtils].
• Bugzilla - New component "BeanUtils" under the "Commons" product category, with appropriate version identifiers as needed.
• Jyve FAQ - New category "commons-beanutils" (when available).

(4) Initial Committers

The initial committers on the BeanUtils component shall be Craig McClanahan and Geir Magnusson Jr.