JiBX: Value Conversions

# JiBX: Value Conversions |

JiBX Basics Overview Flexibility Performance Clean code News and Status User Comments Sponsors Support and Training Bugs Getting Started Binding Tutorial A basic binding Binding extras Structure mapping Collections and arrays Using mappings Advanced binding Method hooks Custom code Binding Compiler Binding on Load Runtime JiBX Extras Building JiBX Schema Compatibility Mailing Lists FAQ Contributing License Binding Definition Definition details Definition contexts Conversions XML summary <binding> element <include> element <format> element <namespace> element <mapping> element <value> element <structure> element <collection> element Attribute groups Usage API Runtime JavaDocs Subprojects Eclipse Plug-in Introduction Install Usage Generator Tools Axis2 Usage JibxSoap Xsd2Jibx | ### Value Conversions JiBX defines a default set of formats used for converting property values to and from text strings. These format definitions are effectively defined in a context outside the root binding element of the binding definition. Most of the conversions are based on the W3C XML Schema datatype definitions, as described in the following table. #### Default Formats
Type | Format Label | Conversion
--- | --- | ---
`byte` | byte.default | Converts primitive `byte` values to and from the schema byte representation (integer values in the range of -128 to +127).
`char` | char.default | Converts primitive `char` values to and from the schema unsigned short representation (integer values in the range of 0 to 65535). Although this is the default for `char` primitives, JiBX also supports an alternate conversion as single-character text values using the named format char.string (allowing the conversion to be applied on a specific value) and a pair of conversion methods. To make the single-character text conversion the default in your binding, just specify the format as a child of the root binding element as follows:
    <format type="char"
      serializer="org.jibx.runtime.Utility.serializeCharString"
      deserializer="org.jibx.runtime.Utility.deserializeCharString"/>
`double` | double.default | Converts primitive `double` values to and from the schema double representation (IEEE double-precision floating point).
`float` | float.default | Converts primitive `float` values to and from the schema float representation (IEEE single-precision floating point).
`int` | int.default | Converts primitive `int` values to and from the schema int representation (integer values in normal 32-bit signed value range).
`long` | long.default | Converts primitive `long` values to and from the schema long representation (integer values in normal 64-bit signed value range).
`short` | short.default | Converts primitive `short` values to and from the schema short representation (integer values in normal 16-bit signed value range).
`boolean` | boolean.default | Converts primitive `boolean` values to and from the schema boolean representation ("true" or "false", or equivalently "1" or "0" - the former values are always used when converting to text).
`byte[]` | byte-array.default | Converts byte arrays to and from the schema base64 representation to allow arbitrary binary data.
`java.util.Date` | Date.default | Converts instances of `java.util.Date` to and from the schema dateTime representation (a text representation like "2000-03-21T01:33:00", with optional trailing fractional seconds, and difference from UTC). Since schema doesn't have any concept equivalent to Java time zones, this conversion always serializes times as UTC values (identified by a trailing "Z"). When deserializing times which do not include a "Z" or offset from UTC it treats the values as UTC.
`java.sql.Date` | SqlDate.default | Converts instances of `java.sql.Date` to and from the schema date representation (a text representation like "2000-03-21").
`java.sql.Time` | SqlTime.default | Converts instances of `java.sql.Time` to and from the schema time representation (a text representation like "01:33:00" with optional trailing fractional seconds).
`java.sql.Timestamp` | Timestamp.default | Converts instances of `java.sql.Timestamp` to and from the schema dateTime representation, just as the Date:default conversion does for `java.util.Date` instances. The only difference is that using the timestamp value permits greater precision in the time value represented, down to the nanosecond level.
`java.lang.String` | String.default | Identity converter for `java.lang.String` instances.
`java.lang.Object` | Object.default | Converts any object to a string representation by using the `toString()` method, and converts a string to any object by using a constructor that takes a single argument of type `java.lang.String`. If an optional value is not present when unmarshalling a `null` value is stored to the object reference. This is the default format conversion used for any object type without a more specific conversion defined.
These are the conversions you'll get unless you specify otherwise. If you use a format element to override one of these defaults you'll still be able to access the default by using the defined label for that format. Defining your own custom serialization formats is easy, basically requiring only a pair of static methods to convert to and from `String` representations. See the format element description for details of defining your own conversions. The `org.jibx.runtime.Utility` class defines a variety of conversion methods, including those used to implement the standard conversions listed in the above table as well as some alternate date-related conversion methods. The methods `serializeDate` and `deserializeDate` may be of special interest for developers working with xs:date values, since they support conversion of xs:date format to and from `java.util.Date` instances (the equivalent to the default conversion used for `java.sql.Date` instances). The default conversions listed above don't always match conversions used by other frameworks for working with XML in Java. In particular, many other frameworks convert the various schema date-related types to and from `java.util.Calendar` instances. This is an incorrect interpretation of the schema types, which do not support the associated time zone which is a necessary part of `Calendar` instances. JiBX by default takes the approach of converting to and from Java objects which are the nearest possible equivalents to the schema types. You can always change these defaults for your own purposes using the techniques described above. In addition to the conversions listed in the table, JiBX 1.1 and later support automatic conversion of Java 5 enum values to and from strings.