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.