This appendix describes the errors that may occur during the execution of the framework's methods. You also find out how to customize the output of the error messages and how to localize the resources.

A.1. Error Messages

There are two kinds of errors: fatal errors and mapping errors.

A fatal error interrupts the execution of a method by throwing an exception. Any IOException is a fatal error. In addition, the methods may throw a runtime exception if one of their parameters has an invalid value.

A mapping error is a non-fatal error that occurs during the mapping process. The mapping errors can be application errors or user errors. An application error signals a problem that has to be corrected by the application developer. A user error occurs when the user doesn't provide necessary data or when the provided data is invalid. The mapping process isn't stopped by a mapping error. The mapping errors can be logged and/or shown to the user whether they are user or application errors.

A.1.1. Fatal Errors

Many of the fatal errors are signaled when the mapping process cannot start because of an invalid parameter value that is passed to a mapping utility. Also, there are other methods of the framework that signal a fatal error if they cannot perform their task because of an invalid parameter value. After the mapping process or the performing of any other task starts, the only possible fatal error is IOException.

[FATAL_NULL_PARAMETER]={0} cannot be null

When a non-optional parameter is null, the framework's methods throw a NullPointerException that contains this message. The {0} string is replaced with the name of the parameter.

[FATAL_EXTERNAL_OBJECT]={0} created externally

FormUtils.beanToForm(), TextUtils.beanToText(), XMLUtils.beanToXML() and HandlerUtils.removeUserErrors() take an optional java.util.Hashtable parameter called errorTable. This parameter may be null or it must be a Hashtable returned by one of the following methods: FormUtils.formToBean(), TextUtils.textToBean() or XMLUtils.xmlToBean().

FormUtils.beanToForm() takes a FormDocument parameter called document. All FormDocument instances used by the framework must be created by the getDocument() method of FormTemplate. All FormTemplate instances that create documents must be created by FormUtils.getTemplate().

If one of the above rules is broken, the framework's methods throw an IllegalArgumentException that contains this message. The {0} string is replaced with the name of the parameter that caused the error (document or errorTable).

[FATAL_INVALID_ENCODING]=Invalid encoding: {0}

Many of the framework's methods take an encoding ID parameter. The CharacterEncoding class associates an ID to each character encoding recognized by Java 2. All these IDs are declared as constants. If a Java version recognizes a new encoding you can get an ID for it by using CharacterEncoding.register().

A framework's method that gets an invalid encoding ID, will throw an IllegalArgumentException that contains this message. The {0} string is replaced with the invalid encoding ID.

[FATAL_DOCUMENT_WITHOUT_FORMS]={0} contains no forms

FormUtils.beanToForm() will throw an IllegalArgumentException that contains this message if it gets a FormDocument that contains no forms. The {0} string is replaced with the name of the parameter that caused the error (document).

[FATAL_FORM_NOT_FOUND]=Form not found: {0}

FormUtils.beanToForm() will throw an IllegalArgumentException that contains this message if it gets a FormDocument and a form name, but the HTML document doesn't contain any form with the given name. The {0} string is replaced with the form's name.

[FATAL_VARIABLE_NOT_FOUND]=Variable not found: {0}

The setValue() and getValue() methods of FormDocument throw an IllegalArgumentException with this message if the variable whose name is passed as parameter doesn't exist. The {0} string is replaced with the variable's name.

[FATAL_INVALID_VARIABLE_INDEX]=Invalid variable index: {0}

The setValue() and getValue() methods of FormDocument throw an ArrayIndexOutOfBoundsException with this message if the variable index that is passed as parameter is invalid. The {0} string is replaced with the invalid variable index.

[FATAL_PARSING_MULTIPART]=Parsing error of the multipart/form-data input: {0}

The ServletFormData() constructor throws an IOException with this message if the parsing of the multipart form data fails. The {0} string is replaced with the parsing error's message.

[FATAL_MULTIPART_PARSER_NOT_FOUND]=The "multipart/form-data" parser was not found. JavaMail must be in CLASSPATH

JavaMail provides the MIME multipart parser used by the framework. The ServletFormData() constructor throws an InternalError with this message if the .jar files that contain the necessary classes (mail.jar of JavaMail and activation.jar of JavaBeans Activation Framework) aren't in CLASSPATH.

[FATAL_PARSING_XML]=Parsing error of the XML content: {0}

The XMLUtils.xmlToBean() method throws an IOException with this message if the parsing of the XML content fails. The {0} string is replaced with the parsing error's message.

[FATAL_XML_PARSER_NOT_FOUND]=The XML parser was not found. A JAXP conformant XML parser must be in CLASSPATH

The XMLUtils.xmlToBean() method throws an IOException with this message if a JAXP conformant XML parser isn't found in CLASSPATH.

[FATAL_MISSING_KEY]=The license information is missing. Please, run the Setup utility and provide Serial Number and Key [FATAL_INVALID_KEY]=The license information is invalid. Please, run the Setup utility and correct Serial Number and Key [FATAL_TRIAL_EXPIRED]=The license information expired. Please, order Devsphere Mapping Framework at http://www.devsphere.com [FATAL_DEFINITIVE_KEY_NEEDED]=The temporary license information expired. Please, run the Setup utility and provide definitive Serial Number and Key

These errors occur when the license information (Serial Number and Key) is missing, is invalid or has expired. No exception is thrown, but the mapping process doesn't start and the above error messages are shown and/or logged as they would be application errors.

A.1.2. Application Errors

The application errors are mapping errors that aren't caused by the user. By default, they are logged and shown. No exception is thrown.

The error messages described in this section have three or four parameters. The {0} string is always replaced with the name of the mapping utility: formToBean, beanToForm, textToBean, beanToText, xmlToBean or beanToXML. The {1} string is replaced with the name of the bean whose instance participates to the mapping process.

[INITIALIZATION_ERROR]={0} ({1}): Initialization error ({2})

An initialization error occurred during the initialization of the mapping utility. The {2} string is replaced with a message describing the error. It could be an error that occurred during the introspection of the bean class. The contained beans may generate an initialization error too.

[SELF_CONTAINED_BEAN]={0} ({1}): Bean contained directly or indirectly by its own class or by one of the superclasses ({2})

A bean may not be contained directly or indirectly by its own class or by one of its superclasses. The {2} string is replaced with the name of the property that breaks this rule.

If a bean class B defines/inherits a contained bean property whose type is C then B and C must be different classes and C may not be a subclass of B. In addition, none of the properties of C may have the type B or a subclass of B, none of the properties of the properties of C may have the type B or a subclass of B, and so on.

[MULTIDIMENSIONAL_ARRAY]={0} ({1}): Multidimensional arrays are not supported ({2})

The type of a property may not be a multidimensional array. The {2} string is replaced with the name of the property that breaks this rule.

[MAPPING_ERROR]={0} ({1}): Mapping error ({2})

An unexpected error occurred during the mapping process after the initialization. The {2} string is replaced with a message describing the error.

[WRONG_CLASS]={0} ({1}): Wrong bean type ({2})

This is an error that may not occur because the API, which could generate it, was not made public.

[INSTANTIATION_ERROR]={0} ({1}): Instantiation error ({2} -- {3})

An error occurred during the instantiation of a contained bean. The {2} string is replaced with the property's name. The {3} string is replaced with a message describing the error.

[NO_GETTER]={0} ({1}): No getter ({2})

There is no get method for one of the bean's properties. The {2} string is replaced with the name of the property whose getter is missing. You have to edit the source code, add the get method and recompile the bean class. Then, you'll have to restart/reload the whole application so that the bean class is reloaded and reintrospected.

[GETTER_ERROR]={0} ({1}): Getting error ({2} -- {3})

An exception occurred at the invocation of a get method or, more likely, the getter method itself threw the exception. The {2} string is replaced with the name of the property. The {3} string is replaced with the message of the getter exception caught by the mapping utility.

[MULTIREFERENCED_BEAN]={0} ({1}): Multiple references to the same bean object ({2})

A bean object is contained at least twice by an object tree whose root was passed to a mapping utility. The {2} string is replaced with the name of the property that contains the second reference.

The bean-to mapping does not allow multiple references to a contained bean object. In other words, a single call to a mapping utility may not map the properties of the same bean object to multiple groups of elements contained by the same document.

[NO_SETTER]={0} ({1}): No setter ({2})

There is no set method for one of the bean's properties. The {2} string is replaced with the name of the property whose setter is missing. You have to edit the source code, add the set method and recompile the bean class. Then, you'll have to restart/reload the whole application so that the bean class is reloaded and reintrospected.

[SETTER_ERROR]={0} ({1}): Setting error ({2} -- {3})

An exception occurred at the invocation of a set method or, more likely, the setter method itself threw the exception. The {2} string is replaced with the name of the property. The {3} string is replaced with the message of the setter exception caught by the mapping utility.

[MISSING_ARRAY_LENGTH]={0} ({1}): Missing array length ({2})

A to-bean mapping utility can't get the length of a contained array. The {2} string is replaced with something like prefix.propertyName.length or just propertyName.length.

[INVALID_ARRAY_LENGTH]={0} ({1}): Invalid array length ({2} -- {3})

A to-bean mapping utility got an invalid length for a contained array. The {2} string is replaced with something like prefix.propertyName.length or just propertyName.length. The {3} string is replaced with the invalid length.

[MISSING_FORM_ELEMENT]={0} ({1}): Missing form element ({2})

A property of a bean object cannot be mapped to any form element. The {2} string is replaced with something like prefix.propertyName or just propertyName, which is the name of the expected form element. You have to edit the HTML form and make sure that there is a form element with the expected name so that the property can be mapped to it. You don't have to restart the application since the HTML forms are reloaded automatically.

A.1.3. User Errors

By default, the user errors are shown and they aren't logged. No exception is thrown.

[SETTER_ILLEGAL_ARGUMENT]=Must have a valid value

A set method of the bean object threw an IllegalArgumentException that is treaded as a user error.

[NUMBER_FORMAT_ERROR]=Must be a number

The user provided an invalid number.

[MISSING_DATA]=Missing data

The user didn't provide the data for a property of the bean object.

[MISSING_TEXT_DATA]=Must be filled

The user didn't fill a non-optional input field of the HTML form.

[MISSING_CHECKBOX_DATA]=Must have at least a checked button

The user didn't check any of the checkbox buttons of a group. If this should be allowed, include the associated property within the list of optional properties or map each checkbox to a boolean property.

[MISSING_RADIO_DATA]=Must have a checked button

The user let a group of radio buttons without selection. If this should be allowed, include the associated property within the list of optional properties.

[MISSING_SELECT_DATA]=Must have a selection

The user let a list without selection. If this should be allowed, include the associated property within the list of optional properties.

[MISSING_UPLOADED_FILE]=Must contain a file path

The user didn't select any file. If this should be allowed, include the associated property within the list of optional properties.

[MISSING_UPLOADED_FILES]=Must contain file paths

The user let a list of file controls empty. If this should be allowed, include the associated property within the list of optional properties.

A.2. Other Resources

[LOGGED_USER_ERROR]={0} ({1})\: User error ({2} -- {3})

This message is used to log the user errors during the usability testing of the Web applications that use the framework. The {0} string is replaced with the name of the mapping utility. The {1} string is replaced with the name of the bean whose instance participates to the mapping process. The {2} string is replaced with the property's name. The {3} string is replaced with a message describing the user error.

When one or more messages are inserted in an HTML form, the framework uses the following separators:

[HTML_MESSAGE_START]=<FONT COLOR\="\#FF0000"> [HTML_MESSAGE_SEPARATOR]=<BR>\r\n [HTML_MESSAGE_END]=</FONT><BR>\r\n

The following resource is used to indent the XML documents:

[XML_INDENTATION_STRING]=\t

You may change these default values by editing the resources.properties file as it is described in the next section.

You may also define these four resources within the resource bundle associated to a data bean.

Any of these framework resources can be obtained using HandlerUtils.getResource().

A.3. Localization

You can build internationalized applications without localizing the framework's resources. You'll just have to provide a resource bundle for each data bean. The resource bundle should contain error messages for each bean property / form element. Other resources such as default values may be contained too. Then, you'll have to translate the bean resources to all users' languages. The Internat example does this. Everything the user normally sees is in his/her language. However, the application error messages will be logged in English.

Currently, all default error messages are available only in English, but you may localize them. This way, you won't have to provide an error message for each bean property / form element as long as the localized default messages are suitable. You have to translate the resources.properties file from framework_home/com/devsphere/mapping/resources.

The application errors and the fatal errors will be shown/logged using the default locale (the one returned by java.util.Locale.getDefault()). The user errors will be shown using the user's locale that is passed to the mapping utilities. Therefore the fatal error messages and the application error messages can be translated only for the default locale. Only the few user error messages must be translated to all languages that your application must support.

Some of the error messages contain one or more parameters (such as {0}, {1}, {2}, ...). These messages will be formatted using java.text.MessageFormat.format(). Therefore, a single quote (') must be encoded as two single quotes (' ' without any space between them). A curly brace ({ or }) that must appear in the message must be wrapped by single quotes ('{' or '}').

In the framework's messages that don't contain parameters, the single quote and the curly brace must not be encoded since they aren't processed with java.text.MessageFormat.format().

If all these resources are stored in .properties files some additional encoding rules must be applied for all error messages:

the =, :, #, !, \ characters must be encoded as \=, \:, \#, \!, \\
the TAB, CR, LF must be encoded as \t, \r, \n
any SPACE that must be included at the beginning of the message must be preceded by a backslash
any character whose code is less than 32 or greater that 127 must be encoded as \uXXXX.

Contents | Previous Chapter | Next Chapter