The are a number of operations that are carried out on data values by the client infrastructure. Some are controlled by the domain definition options that were set in the UML model and are performed automatically, others are controlled by domain-specific plug-ins that can be overridden and customized; these plug-ins will be described later. First, the operations that are performed on the data values need to be understood:
- format
- When data is retrieved from the application server, it is represented by a Java object appropriate to the root domain of the data. For example, a value in the SVR_INT64 domain is represented as a java.lang.Long object. The format operation is responsible for converting these objects to their string representation, as it is the string representation that must be embedded in the XHTML stream returned to the web browser.
A format operation is only required to return a non-null string; there are no other limitations. However, each domain-specific formatter will usually return a string representation of the Java object according to the usual conventions. For example, a money value may have a currency symbol added during formatting and be limited to two significant digits after the decimal point. For most data values, the formatter should generate a string representation that can later be converted back into the original data value.
- pre-parse
- When a user enters values in a form on an application page and submits the form to the client application, the web browser submits all of these values in string format. These string values need to be parsed to create the appropriate Java object representations, but first a pre-parse operation is performed to prepare the string for parsing.
The UML model supports several domain definition options that are recognized by the pre-parse operation (see the Cúram Modeling Reference Guide for more information on domain definition options). The domain definition options may indicate that leading and trailing whitespace characters should be trimmed from the string, that all sequences of whitespace characters should be compressed to single space characters, and that the string should be converted to upper-case. The pre-parse operation applies these options automatically to the string values and the modified string values are then ready to be parsed. The pre-parse operation is controlled and customized by setting these domain definition options in the UML model.
- parse
- After the pre-parse operation has completed, the parse operation must convert the resulting string value into its Java object representation before it can be submitted to the application server. In general, the parse operation is the reverse of the format operation. If the format operation formatted a money value to a string and added a currency symbol and grouping separator (e.g., thousands separator) characters, the parse operation must be able to remove these additions and create a Java object representation of the actual money value.
All that is required of the parse operation is to produce a Java object, it does not validate that value. However, while not explicitly a validation operation, the parse operation usually needs to perform some validation to ensure that the value can be parsed correctly. For example, a date may later be determined to be invalid if it is out of range, but the parse operation must first determine what the date value is and may fail if the string does not represent a date in any recognized format.
- pre-validate
- Like the pre-parse operation, the pre-validate operation is performed to apply domain definition options defined in the UML model. However, unlike the pre-parse operation, different domain definition options are applied to data values depending on the domain. The data is not modified. String and BLOB values are tested to ensure that they do not exceed their maximum or minimum defined sizes (or lengths), while numeric values are tested to ensure that they do not exceed their maximum or minimum values. Any failures will be reported as errors. See Converter Plug-ins for a detailed description of the actual validations performed.
- validate
- The pre-validate operation is convenient and is applied automatically, but there are situations where it may not be able to validate data sufficiently. The validate operation is a catch-all that allows any kind of validation to be performed that is not possible using UML domain definition options alone. For example, ID values may be tested to see if their check-digit is valid. Errors can be reported if any value does not meet such specific conditions. Data is not modified by this operation.
- compare
- When a list of data is returned from the server, the sort order of the values in the list is determined using the compare operation. This sort order is used to support the sorting of lists on application pages when users click on the column headers. The compare operation is passed two data values (in their Java object representations, not in their formatted string representations) and must return a positive or negative number to indicate which comes first in the sort order. Like the format operation, the compare operation is not restricted in what calculations it performs, but it will typically sort values alphabetically or numerically.
Each data conversion operation has access to information about the active user's locale and to information about the domain being processed. It is also possible for one operation to access and execute any of the operations should that be necessary. For example, a format operation might format values differently for each locale and a compare operation might invoke the format operation before making a comparison.