BeanProperty is used to access local properties. The properties can be of any type supported by Java including primitive types. Although when using primitive types, JBeans either requires them to be wrapped or will wrap them automatically. The classes it uses are the standard wrapper classes in the java.lang package of the core Java API.

The BeanProperty object is constructed using the Java Class object, which describes a Java bean class and the name of the property. This name is the Java bean property name, NOT the name of the method used to access the property. The Java Class object can be replaced by the fully qualified name of the class. The constructor have these signatures:

    public BeanProperty(String propertyName, Class beanClass) throws BeanException;
    
    public BeanProperty(String propertyName, String beanClass) throws BeanException;
    

Once the BeanProperty class has been constructed it describes a property of a Java bean class. This is an important distiction between a property of a Java bean instance. The same BeanProperty object can be used to access the same property on multiple Java bean instances. This saves on both access time and memory. This way a new BeanProperty object does not need to be constructed for each Java bean instance. One thing to notice is that the constructors thrown BeanExceptions. If the propertyName used to construct the BeanProperty is invalid, a BeanException will be thrown.

After constructing a BeanProperty the Java bean property can be accessed using a few different methods. If you are trying to retrieve the value of the property, you should use the getPropertyValue method. This method calls the get method for the property on a specific bean instance. So, what you need to provide to this method is only the bean instance beacuse the BeanProperty class knows what property it was constructed for. The getPropertyValue method has this signature:

    public Object getPropertyValue(Object beanInstance) throws BeanException;
    

This method returns the value of the property as an Object. This means that all primitive types are wrapped in the java.lang wrapper classes mentioned above. This method can return null if the property's current value is null. The beanInstance that is passed to the method is an instance of the class that the BeanProperty was constructed for. Like mentioned above, a single BeanProperty instance can be used to access Java bean properties on an unlimited number of instances of the same Java bean class.

The method throws a org.jbeans.BeanException exception if anything went wrong. What could go wrong you ask? If the beanInstance is not the same type as the class setup for the BeanProperty instance; if the get method threw an exception; or if the get method was not accessible for any reason, then a BeanException would be thrown.

If you are trying to change the value of the property, you should use the setPropertyValue method. This method calls the set method for the property on a specific bean instance. So, what you need to provide to this method is the bean instance and the value to set the property to. The setPropertyValue method has these signatures:

    public void setPropertyValue(Object beanInstance, Object value) 
    throws BeanException, ConversionException;
    
    public void setPropertyValue(Object beanInstance, Object value, boolean convert) 
    throws BeanException, ConversionException;
    

The second version of this method is used when doing auto-converion. This is discussed more later in this document. For now, we will examine the first version of the method. This version sets the value of the property to the given value. All primitive types need to be converted to the wrapper classes before calling this method. In the future, primitive versions of this method might be added to the BeanProperty class, but for now, you must handle the wrapping yourself.

Just like the getPropertyValue method, this method takes the beanInstance which the properties value will be set on. It also throws a BeanException if anything went wrong. What could go wrong you ask? If the beanInstance is not the same type as the class setup for the BeanProperty instance; if the set method threw an exception; if the value parameter was not the correct type for the set method; or if the set method was not accessible for any reason, then a BeanException would be thrown.

Here are a few examples of using the BeanProperty class to access Java bean properties:

    /* We'll use this Java bean for our example */
    public class User {
        private String name;
        private int age;
        
        public String getName() { return name; }
        public void setName(String value) { name = value; }
        
        public int getAge() { return age; }
        public void setAge(int value) { age = value; }
    }
    
    // Retrieving the name property using BeanProperty
    User userInstance = new User();
    userInstance.setName("Fred");
    
    try {
        BeanProperty property = new BeanProperty("name", User.class);
        
        // Gets the users name from the userInstance instance of the User class
        String name = (String) property.getPropertyValue(userInstance); 
        System.out.println("The user's name: " + name);
    } catch (BeanException be) {
        be.printStackTrace();
    }
    
    /*
    Output:
    The user's name: Fred
    */
    

In this example, you can see that the name property of the User Java bean instance is being retrieved using the BeanProperty class. This is the simplest of examples, but shows you how easy it is to use the BeanProperty class.

    // Retrieving the age property using BeanProperty
    User userInstance = new User();
    userInstance.setAge(42);
    
    try {
        BeanProperty property = new BeanProperty("age", User.class);
        
        // Gets the users age from the userInstance instance of the User class
        Integer age = (Integer) property.getPropertyValue(userInstance); 
        System.out.println("The user's age: " + age);
    } catch (BeanException be) {
        be.printStackTrace();
    }
    
    /*
    Output:
    The user's age: 42
    */
    

In this example, you can see that the age property, which is a Java primitive type, is being wrapped up by the BeanProperty class on retrieval. This is how all of the JBeans package handles primitive types.

    // Changing the name property using BeanProperty
    User userInstance = new User();
    
    try {
        BeanProperty property = new BeanProperty("name", User.class);
        property.setPropertyValue(userInstance, "Wilma");
        System.out.println("The user's name: " + userInstance.getName());
    } catch (BeanException be) {
        be.printStackTrace();
    }
    
    /*
    Output:
    The user's name: Wilma
    */
    

In this example, you can see that the name property is being changed using the BeanProperty class. The value is set only for the instance of the User Java bean in the example.