Automatic Data Conversion

The SimpleXPathMarshal class is useful when simple string values from XML documents are extracted.

However, much of the time, the values are merely the string representation of other data types, such as dates, numbers, and code-table items. The SimpleXPathADCMarshal extends the capabilities of the SimpleXPathMarshal by enabling automatic data conversion (ADC) using the domain converter plug-ins. The same XPath location paths that are supported by the SimpleXPathMarshal are supported by this ADC class.

This SimpleXPathADCMarshal plug-in performs automatic data conversion (ADC) on the values in the XML content. This requires that the XML content represents values in a particular form: the value must be the body content of an element and the element must have a domain attribute identifying the name of the domain definition to apply to the value. The values must use the generic string form of the data, to be compatible with the parseGeneric method of the domain converter plug-in associated with the identified domain. In general, the generic string value is the same as the result of calling Java's toString method on the corresponding Java object, except for date and data-time values, where the ISO 8601 basic format is used. ADC cannot be applied to the values of attributes or the results of XPath function calls, only to the body text of elements; however, attributes can still be used for values if ADC is not required.

Generic String Values: The generic string value of a server interface property is used to represent numbers, dates, date-times, and other values unambiguously in string form when it is not possible to represent them using a more suitable Java object representation. The generic string value in some of the domain definition options in the application UML model and when data in XML documents is transported. The format avoids problems that can arise if values were formatted according to the rules or conventions of different locales, as these would add unnecessary complication and need to be communicated.

For numbers, the generic string representation must omit grouping separator characters (such as thousands separators), use only a period character (Unicode FULL STOP U+002E) as a decimal separator and, if the number is negative, place the minus sign character (Unicode HYPHEN-MINUS U+002D) on the left. The CDEJ is lenient when parsing numeric values that use a comma as a thousands separator, but these are best avoided. Using the toString method of class used for the Java object representation of numeric domain definitions produce the wanted result. The classes that are used for the Java object representations for all of the base domain definitions are listed in the Cúram Web Client Reference Manual.

Date and date-time values must be formatted by using ISO 8601 basic format. ISO 8601 basic format represents date and date-time values as fixed-length character strings. The format for date values is YYYYMMDD , two-digit years are not allowed. The format for date-time values is YYYYMMDD T hhmmss , the T is a literal character that denotes the start of the time value and the time uses the 24-hour clock. The parseGeneric method assumes the date-time values are in the UTC time zone. The active user's time zone is applied when formatting the value for display.

Without ADC, the formatted values and raw values that are returned by the getter methods are both the literal string values that are retrieved from the XML document (with only a difference in the handling of null values). With ADC, the formatted values are the values that are formatted according to the locale of the active user and the raw values are the Java object representations of those values appropriate for the indicated domain.

For example, regarding the document in Simple XPath Expressions, if the path /values/value[1] is passed to the get method, then the result will be the string string 1,234 if the user's locale is, say, en, where a comma is used as a thousands separator. Similarly, if the path is /values/value[2], then the result will be 31-Jan-2008 if the user's locale is en and if that particular date format is set. For raw values, the effect is similar, but the corresponding Java object is returned instead of a formatted string. For example, it will be a java.lang.Integer for the SVR_INT32 domain, or a curam.util.type.Date for the SVR_DATE domain. Date and date-time values are in the UTC time zone. They are converted to the user's time zone when formatted.