Class DatatypeConverter
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 Jakarta XML Binding 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.
Jakarta XML Binding 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.
- Since:
- 1.6, JAXB 1.0
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionstatic String
parseAnySimpleType
(String lexicalXSDAnySimpleType) Return a string containing the lexical representation of the simple type.static byte[]
parseBase64Binary
(String lexicalXSDBase64Binary) Converts the string argument into an array of bytes.static boolean
parseBoolean
(String lexicalXSDBoolean) Converts the string argument into a boolean value.static byte
Converts the string argument into a byte value.static Calendar
Converts the string argument into a Calendar value.static Calendar
parseDateTime
(String lexicalXSDDateTime) Converts the string argument into a Calendar value.static BigDecimal
parseDecimal
(String lexicalXSDDecimal) Converts the string argument into a BigDecimal value.static double
parseDouble
(String lexicalXSDDouble) Converts the string argument into a double value.static float
parseFloat
(String lexicalXSDFloat) Converts the string argument into a float value.static byte[]
parseHexBinary
(String lexicalXSDHexBinary) Converts the string argument into an array of bytes.static int
Convert the string argument into an int value.static BigInteger
parseInteger
(String lexicalXSDInteger) Convert the string argument into a BigInteger value.static long
Converts the string argument into a long value.static QName
parseQName
(String lexicalXSDQName, NamespaceContext nsc) Converts the string argument into a byte value.static short
parseShort
(String lexicalXSDShort) Converts the string argument into a short value.static String
parseString
(String lexicalXSDString) Convert the lexical XSD string argument into a String value.static Calendar
Converts the string argument into a Calendar value.static long
parseUnsignedInt
(String lexicalXSDUnsignedInt) Converts the string argument into a long value.static int
parseUnsignedShort
(String lexicalXSDUnsignedShort) Converts the string argument into an int value.static String
printAnySimpleType
(String val) Converts a string value into a string.static String
printBase64Binary
(byte[] val) Converts an array of bytes into a string.static String
printBoolean
(boolean val) Converts a boolean value into a string.static String
printByte
(byte val) Converts a byte value into a string.static String
Converts a Calendar value into a string.static String
printDateTime
(Calendar val) Converts a Calendar value into a string.static String
printDecimal
(BigDecimal val) Converts a BigDecimal value into a string.static String
printDouble
(double val) Converts a double value into a string.static String
printFloat
(float val) Converts a float value into a string.static String
printHexBinary
(byte[] val) Converts an array of bytes into a string.static String
printInt
(int val) Converts an int value into a string.static String
printInteger
(BigInteger val) Converts a BigInteger value into a string.static String
printLong
(long val) Converts A long value into a string.static String
printQName
(QName val, NamespaceContext nsc) Converts a QName instance into a string.static String
printShort
(short val) Converts a short value into a string.static String
printString
(String val) Converts the string argument into a string.static String
Converts a Calendar value into a string.static String
printUnsignedInt
(long val) Converts a long value into a string.static String
printUnsignedShort
(int val) Converts an int value into a string.static void
setDatatypeConverter
(DatatypeConverterInterface converter) This method is for Jakarta XML Binding provider use only.
-
Method Details
-
setDatatypeConverter
This method is for Jakarta XML Binding provider use only.Jakarta XML Binding Providers are required to call this method at some point before allowing any of the Jakarta XML Binding client marshal or unmarshal operations to occur. This is necessary to configure the datatype converter that should be used to perform the print and parse conversions.
Calling this api repeatedly will have no effect - the DatatypeConverterInterface instance passed into the first invocation is the one that will be used from then on.
- Parameters:
converter
- an instance of a class that implements the DatatypeConverterInterface class - this parameter must not be null.- Throws:
IllegalArgumentException
- if the parameter is nullSecurityException
- If theSecurityManager
in charge denies the access to set the datatype converter.- See Also:
-
parseString
Convert the lexical XSD string argument into a String value.
- Parameters:
lexicalXSDString
- A string containing a lexical representation of xsd:string.- Returns:
- A String value represented by the string argument.
-
parseInteger
Convert the string argument into a BigInteger value.
- Parameters:
lexicalXSDInteger
- A string containing a lexical representation of xsd:integer.- Returns:
- A BigInteger value represented by the string argument.
- Throws:
NumberFormatException
-lexicalXSDInteger
is not a valid string representation of aBigInteger
value.
-
parseInt
Convert the string argument into an int value.
- Parameters:
lexicalXSDInt
- A string containing a lexical representation of xsd:int.- Returns:
- A int value represented by the string argument.
- Throws:
NumberFormatException
-lexicalXSDInt
is not a valid string representation of anint
value.
-
parseLong
Converts the string argument into a long value.
- Parameters:
lexicalXSDLong
- A string containing lexical representation of xsd:long.- Returns:
- A long value represented by the string argument.
- Throws:
NumberFormatException
-lexicalXSDLong
is not a valid string representation of along
value.
-
parseShort
Converts the string argument into a short value.
- Parameters:
lexicalXSDShort
- A string containing lexical representation of xsd:short.- Returns:
- A short value represented by the string argument.
- Throws:
NumberFormatException
-lexicalXSDShort
is not a valid string representation of ashort
value.
-
parseDecimal
Converts the string argument into a BigDecimal value.
- Parameters:
lexicalXSDDecimal
- A string containing lexical representation of xsd:decimal.- Returns:
- A BigDecimal value represented by the string argument.
- Throws:
NumberFormatException
-lexicalXSDDecimal
is not a valid string representation ofBigDecimal
.
-
parseFloat
Converts the string argument into a float value.
- Parameters:
lexicalXSDFloat
- A string containing lexical representation of xsd:float.- Returns:
- A float value represented by the string argument.
- Throws:
NumberFormatException
-lexicalXSDFloat
is not a valid string representation of afloat
value.
-
parseDouble
Converts the string argument into a double value.
- Parameters:
lexicalXSDDouble
- A string containing lexical representation of xsd:double.- Returns:
- A double value represented by the string argument.
- Throws:
NumberFormatException
-lexicalXSDDouble
is not a valid string representation of adouble
value.
-
parseBoolean
Converts the string argument into a boolean value.
- Parameters:
lexicalXSDBoolean
- A string containing lexical representation of xsd:boolean.- Returns:
- A boolean value represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.
-
parseByte
Converts the string argument into a byte value.
- Parameters:
lexicalXSDByte
- A string containing lexical representation of xsd:byte.- Returns:
- A byte value represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.
-
parseQName
Converts the string argument into a byte value.
String parameter
lexicalXSDQname
must conform to lexical value space specifed at XML Schema Part 2:Datatypes specification:QNames- Parameters:
lexicalXSDQName
- A string containing lexical representation of xsd:QName.nsc
- A namespace context for interpreting a prefix within a QName.- Returns:
- A QName value represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to XML Schema Part 2 specification or if namespace prefix oflexicalXSDQname
is not bound to a URI in NamespaceContextnsc
.
-
parseDateTime
Converts the string argument into a Calendar value.
- Parameters:
lexicalXSDDateTime
- A string containing lexical representation of xsd:datetime.- Returns:
- A Calendar object represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.
-
parseBase64Binary
Converts the string argument into an array of bytes.
- Parameters:
lexicalXSDBase64Binary
- A string containing lexical representation of xsd:base64Binary.- Returns:
- An array of bytes represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary
-
parseHexBinary
Converts the string argument into an array of bytes.
- Parameters:
lexicalXSDHexBinary
- A string containing lexical representation of xsd:hexBinary.- Returns:
- An array of bytes represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.
-
parseUnsignedInt
Converts the string argument into a long value.
- Parameters:
lexicalXSDUnsignedInt
- A string containing lexical representation of xsd:unsignedInt.- Returns:
- A long value represented by the string argument.
- Throws:
NumberFormatException
- if string parameter can not be parsed into along
value.
-
parseUnsignedShort
Converts the string argument into an int value.
- Parameters:
lexicalXSDUnsignedShort
- A string containing lexical representation of xsd:unsignedShort.- Returns:
- An int value represented by the string argument.
- Throws:
NumberFormatException
- if string parameter can not be parsed into anint
value.
-
parseTime
Converts the string argument into a Calendar value.
- Parameters:
lexicalXSDTime
- A string containing lexical representation of xsd:time.- Returns:
- A Calendar value represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.
-
parseDate
Converts the string argument into a Calendar value.
- Parameters:
lexicalXSDDate
- A string containing lexical representation of xsd:Date.- Returns:
- A Calendar value represented by the string argument.
- Throws:
IllegalArgumentException
- if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.
-
parseAnySimpleType
Return a string containing the lexical representation of the simple type.
- Parameters:
lexicalXSDAnySimpleType
- A string containing lexical representation of the simple type.- Returns:
- A string containing the lexical representation of the simple type.
-
printString
Converts the string argument into a string.
- Parameters:
val
- A string value.- Returns:
- A string containing a lexical representation of xsd:string.
-
printInteger
Converts a BigInteger value into a string.
- Parameters:
val
- A BigInteger value- Returns:
- A string containing a lexical representation of xsd:integer
- Throws:
IllegalArgumentException
-val
is null.
-
printInt
Converts an int value into a string.
- Parameters:
val
- An int value- Returns:
- A string containing a lexical representation of xsd:int
-
printLong
Converts A long value into a string.
- Parameters:
val
- A long value- Returns:
- A string containing a lexical representation of xsd:long
-
printShort
Converts a short value into a string.
- Parameters:
val
- A short value- Returns:
- A string containing a lexical representation of xsd:short
-
printDecimal
Converts a BigDecimal value into a string.
- Parameters:
val
- A BigDecimal value- Returns:
- A string containing a lexical representation of xsd:decimal
- Throws:
IllegalArgumentException
-val
is null.
-
printFloat
Converts a float value into a string.
- Parameters:
val
- A float value- Returns:
- A string containing a lexical representation of xsd:float
-
printDouble
Converts a double value into a string.
- Parameters:
val
- A double value- Returns:
- A string containing a lexical representation of xsd:double
-
printBoolean
Converts a boolean value into a string.
- Parameters:
val
- A boolean value- Returns:
- A string containing a lexical representation of xsd:boolean
-
printByte
Converts a byte value into a string.
- Parameters:
val
- A byte value- Returns:
- A string containing a lexical representation of xsd:byte
-
printQName
Converts a QName instance into a string.
- Parameters:
val
- A QName valuensc
- A namespace context for interpreting a prefix within a QName.- Returns:
- A string containing a lexical representation of QName
- Throws:
IllegalArgumentException
- ifval
is null or ifnsc
is non-null ornsc.getPrefix(nsprefixFromVal)
is null.
-
printDateTime
Converts a Calendar value into a string.
- Parameters:
val
- A Calendar value- Returns:
- A string containing a lexical representation of xsd:dateTime
- Throws:
IllegalArgumentException
- ifval
is null.
-
printBase64Binary
Converts an array of bytes into a string.
- Parameters:
val
- An array of bytes- Returns:
- A string containing a lexical representation of xsd:base64Binary
- Throws:
IllegalArgumentException
- ifval
is null.
-
printHexBinary
Converts an array of bytes into a string.
- Parameters:
val
- An array of bytes- Returns:
- A string containing a lexical representation of xsd:hexBinary
- Throws:
IllegalArgumentException
- ifval
is null.
-
printUnsignedInt
Converts a long value into a string.
- Parameters:
val
- A long value- Returns:
- A string containing a lexical representation of xsd:unsignedInt
-
printUnsignedShort
Converts an int value into a string.
- Parameters:
val
- An int value- Returns:
- A string containing a lexical representation of xsd:unsignedShort
-
printTime
Converts a Calendar value into a string.
- Parameters:
val
- A Calendar value- Returns:
- A string containing a lexical representation of xsd:time
- Throws:
IllegalArgumentException
- ifval
is null.
-
printDate
Converts a Calendar value into a string.
- Parameters:
val
- A Calendar value- Returns:
- A string containing a lexical representation of xsd:date
- Throws:
IllegalArgumentException
- ifval
is null.
-
printAnySimpleType
Converts a string value into a string.
- Parameters:
val
- A string value- Returns:
- A string containing a lexical representation of xsd:AnySimpleType
-