The javaType binding declaration can be used to customize the binding of
an XML schema datatype to a Java datatype. Customizations can involve
writing a parse and print method for parsing and printing lexical
representations of a XML schema datatype respectively. However, writing
parse and print methods requires knowledge of the lexical representations (
XML Schema Part2: Datatypes
specification ) and hence may be difficult to write.
This class makes it easier to write parse and print methods. It defines
static parse and print methods that provide access to a JAXB provider's
implementation of parse and print methods. These methods are invoked by
custom parse and print methods. For example, the binding of xsd:dateTime
to a long can be customized using parse and print methods as follows:
// Customized parse method
public long myParseCal( String dateTimeString ) {
java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString);
long longval = convert_calendar_to_long(cal); //application specific
return longval;
}
// Customized print method
public String myPrintCal( Long longval ) {
java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific
String dateTimeString = DatatypeConverter.printDateTime(cal);
return dateTimeString;
}
There is a static parse and print method corresponding to each parse and
print method respectively in the DatatypeConverterInterface
.
The static methods defined in the class can also be used to specify
a parse or a print method in a javaType binding declaration.
JAXB Providers are required to call the
setDatatypeConverter
api at some point before the first marshal or unmarshal
operation (perhaps during the call to JAXBContext.newInstance). This step is
necessary to configure the converter that should be used to perform the
print and parse functionality.
A print method for a XML schema datatype can output any lexical
representation that is valid with respect to the XML schema datatype.
If an error is encountered during conversion, then an IllegalArgumentException,
or a subclass of IllegalArgumentException must be thrown by the method.