Automatic Data Conversion

The SimpleXPathMarshal class is useful when extracting simple string values from XML documents. 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 supported by the SimpleXPathMarshal are supported by this ADC class.

This SimpleXPathADCMarshal plug-in will perform 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, with the exception of 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 transporting data in XML documents. The format avoids problems that may 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 will produce the desired result. The classes 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 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 denoting 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 will be 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 formatted according the 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, with reference to 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 will be 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 should be in the UTC time zone, they will be converted to the user's time zone when formatted.