W3C XML Schema defines 9 different datatypes for various forms of time-related values. Most of these are not very useful for data exchange between applications. Consider gMonthDay, for instance, which represents a particular month and day of the month without regard to a year - although this could be useful for some specialized applications, most applications need full date specifications including a year. Three of the schema time-related datatypes are widely used for data exchange: dateTime, date, and time. The dateTime datatype is effectively the "core" type, with date and time types just trimmed versions of the dateTime representation.
Unfortunately, the dateTime/date/time datatypes all suffer from one severe limitation when it comes to their use for data exchange: Schema allows the values to be specified either in UTC time (or with a fixed offset from UTC, equivalent to UTC) or without reference to any time zone. The latter case is what usually causes problems for data exchange. Applications always want to work either with fully-specified date/time values, representing a particular instant of time which can be converted at will into any time zone, or with date/time values without reference to time zone (such as a birthday). Very few applications are written to work interchangably with both types of values.
In Java the standard date/time representation uses either a java.util.Date
value or a java.util.Calendar
value. The former corresponds to a
fully-specified dateTime value in schema terms, since it is a specific millisecond in
UTC. The latter has no schema equivalent,
since it includes actual time zone information (rather than just an offset from GMT for
a particular instant of time, as allowed by the schema representation). Various methods
are used by different data binding tools to convert these two Java types to and from
XML representations, but no method can correct the inherent differences.
Because of these issues of date/time representations in schema, and the problems in matching the schema datatypes to Java types, JiBX supports working with both standard Java classes and Joda date/time classes. The Joda library provides a much richer set of representations for date/time values than standard Java, and the richer representations allow more ways of handling the conversions. This still doesn't correct for the fundamental flaws in the schema representation of date/times, but it at least allows you to easily control how the conversions are handled for your code.
The following table gives the full range of date/time formats built into the JiBX handling, including both default formats (as indicated) and formats you can specify by name for use in your bindings:
Type | Format Label | Conversion |
---|---|---|
java.util.Date |
Date.default | Converts instances of |
java.sql.Date |
SqlDate.default | Converts instances of |
java.sql.Time |
SqlTime.default | Converts instances of |
java.sql.Timestamp |
Timestamp.default | Converts instances of |
org.joda.time.LocalDate |
LocalDate.default | Converts instances of |
org.joda.time.DateMidnight |
DateMidnight.zoned | Converts instances of |
org.joda.time.DateMidnight |
DateMidnight.local | Converts instances of |
org.joda.time.DateMidnight |
DateMidnight.UTC | Converts instances of |
org.joda.time.LocalTime |
LocalTime.local | Converts instances of |
org.joda.time.LocalTime |
LocalTime.UTC | Converts instances of |
org.joda.time.DateTime |
DateTime.zoned | Converts instances of |
org.joda.time.DateTime |
DateTime.UTC | Converts instances of |
org.joda.time.DateTime |
DateTime.local | Converts instances of |
org.joda.time.DateTime |
DateTime.strict-local | Like the DateTime.local conversion, above, but requires time zone information in schema dateTime values being deserialized (throwing an exception if no time zone information is present). |
org.joda.time.DateTime |
DateTime.strict-UTC | Like the DateTime.UTC conversion, above, but requires time zone information in schema dateTime values being deserialized (throwing an exception if no time zone information is present). |
The actual implementations of the conversions for standard Java date/time classes
are in the org.jibx.runtime.Utility
class, while those for the Joda
date/time classes are in the org.jibx.runtime.JodaConvert
class. You can
use the methods in these classes to construct your own custom combinations of
serialization and deserialization handling.