5. JavaBeans - Property Text Streams Mapping

This chapter describes the way bean objects are mapped to property text streams and vice-versa. In other words, it explains what TextUtils.beanToText() and TextUtils.textToBean() do.

5.1. Bean-to-Text Mapping

The beanToText() method of TextUtils takes a bean instance, a Hashtable that may contain mapping errors, an output stream, an optional logger object, an optional string prefix and an optional Locale object. The values of the bean properties are saved to the output stream as key-value pairs in the format used by java.util.Properties. The error table may be null or it must be a Hashtable returned by one of the mapping utilities of the framework. The error messages extracted from the error table are saved as comments.

5.1.1. Mapping a standard property

For each standard property, beanToText()

• stores the error message, if present, as a comment,
• computes a property key by concatenating the optional prefix, a dot (if the prefix is present) and the property name,
• stores the key-value pair.

propertyKey=propertyValue 

or

# errorMessage 
propertyKey=propertyValue 

where propertyKey is prefix.propertyName or just propertyName if the optional prefix is not present.

5.1.2. Mapping a standard indexed property

For each standard indexed property, beanToText()

• stores the error message, if present, as a comment,
• computes a property key by concatenating the optional prefix, a dot (if the prefix is present) and the property name,
• stores the length of the array, using propertyKey.length as key,
• stores the elements of the array, using propertyKey.index as keys.

# errorMessage 
propertyKey.length=N
# errorMessage0 
propertyKey.0=propertyValue0
# errorMessage1 
propertyKey.1=propertyValue1 
...
# errorMessageN 
propertyKey.N=propertyValueN 

Note: all or some of the error messages may not be present.

5.1.3. Mapping a contained data bean

For each contained data bean, beanToText()

• stores the error message, if present, as a comment,
• computes a sub-prefix by adding a dot ('.') and the property name (subBean) to the optional prefix, which is an empty string by default,
• passes the contained bean instance and the sub-prefix (prefix.subBean or just subBean) to a recursive call of beanToText()

5.1.4. Mapping a contained bean array

For each contained bean array, beanToText()

• stores the error message, if present, as a comment,
• stores the length of the array (using prefix.subBeanArray.length or just subBeanArray.length as key),
• passes each bean object of the array together with a sub-prefix (prefix.subBeanArray.index or just subBeanArray.index) to a recursive call of beanToText()

5.2. Text-to-Bean Mapping

The textToBean() method of TextUtils takes an input stream, a bean object, an optional logger object, an optional string prefix and an optional Locale object. It iterates over the properties of the bean object and tries to set them to the values encoded in the text document that is read from the input stream. It returns a Hashtable instance that contains the errors that occurred during the mapping process or null if no error occurred.

The text document is parsed using java.util.Properties.

5.2.1. Mapping to a standard property

For each standard property, textToBean()

• calls getProperty(propertyKey) of java.util.Properties, where propertyKey is "prefix.propertyName" or just "propertyName" if the optional prefix is not present,
• tries to convert the returned string to the property's type and
• sets the value of the property.

If the data is missing or the conversion of the string fails then a MappingError object is added to the error table and the property is set to its default value.

5.2.2. Mapping to a standard indexed property

For each standard indexed property, textToBean()

• gets the array's length, by calling getProperty(lengthKey) of java.util.Properties, where lengthKey is "prefix.propertyName.length" or just "propertyName.length" if the optional prefix is not present,
• calls getProperty(elementKey) of java.util.Properties for each array element, where elementKey is "prefix.propertyName.index" or just "propertyName.index" if the optional prefix is not present,
• tries to convert the strings of the array and
• sets the values of the indexed property. (note: All these values become the elements of a new array that is stored to the indexed property using the setter method.)

Any mapping error is stored in the error table. If there are multiple errors, the error table will use a vector of MappingError objects.

5.2.3. Mapping to a contained data bean

For each contained data bean, textToBean()

• creates a new instance of the contained bean by calling the no-arg constructor,
• computes a sub-prefix by adding a dot ('.') and the property name (subBean) to the optional prefix, which is an empty string by default,
• passes the contained bean instance and the sub-prefix ("prefix.subBean" or just "subBean") to a recursive call of textToBean(), and
• sets the subBean property of the bean object to the newly created object.

Note: All recursive calls of textToBean() get the property values from the same java.util.Properties instance, share the same error table and use the same logger and Locale objects that are passed to the initial textToBean() call.

5.2.4. Mapping to a contained bean array

For each contained bean array, textToBean()

• gets the array's length, by calling getProperty(lengthKey) of java.util.Properties, where lengthKey is "prefix.subBeanArray.length" or just "subBeanArray.length" if the optional prefix is not present,
• creates a new array with the obtained length,
• creates a bean instance for each array element and passes it together with a sub-prefix (prefix.subBeanArray.index or just subBeanArray.index) to a recursive call of textToBean(),
• sets the subBeanArray property of the bean object to the newly created array.

5.3. Hints and Tips

Web-based administration tools could use this mapping to save configuration parameters.

The FormMailer servlet converts any valid bean object to text and emails it to one or more addresses. The MailMonitor class uses StoreConnector, which gets the email messages, converts them back to objects and passes them to a dynamically loaded processor.

The .properties files created by TextUtils.beanToText()

• can be converted to objects by TextUtils.textToBean()
• can be loaded by Java applets using java.util.Properties
• can be loaded and parsed easily and efficiently by non-Java applications
• can be viewed and edited using any ASCII editor