Top Description Fields Constructors Methods
jakarta.xml.bind

public final Class DatatypeConverter

extends Object
Class Inheritance
Imports
javax.xml.namespace.NamespaceContext

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.

Author
Since
1.6, JAXB 1.0
See Also
DatatypeConverterInterface, ParseConversionEvent, PrintConversionEvent

Field Summary

Modifier and TypeField and Description
private static final JAXBPermission
SET_DATATYPE_CONVERTER_PERMISSION

private static volatile DatatypeConverterInterface
theConverter

Constructor Summary

AccessConstructor and Description
private
DatatypeConverter()

Method Summary

Modifier and TypeMethod and Description
private static synchronized void
initConverter()

public static String

Returns:

A string containing the lexical representation of the simple type.
parseAnySimpleType(String
A string containing lexical representation of the simple type.
lexicalXSDAnySimpleType)

Return a string containing the lexical representation of the simple type.

public static byte[]

Returns:

An array of bytes represented by the string argument.
parseBase64Binary(String
A string containing lexical representation of xsd:base64Binary.
lexicalXSDBase64Binary)

Converts the string argument into an array of bytes.

public static boolean

Returns:

A boolean value represented by the string argument.
parseBoolean(String
A string containing lexical representation of xsd:boolean.
lexicalXSDBoolean)

Converts the string argument into a boolean value.

public static byte

Returns:

A byte value represented by the string argument.
parseByte(String
A string containing lexical representation of xsd:byte.
lexicalXSDByte)

Converts the string argument into a byte value.

public static Calendar

Returns:

A Calendar value represented by the string argument.
parseDate(String
A string containing lexical representation of xsd:Date.
lexicalXSDDate)

Converts the string argument into a Calendar value.

public static Calendar

Returns:

A Calendar object represented by the string argument.
parseDateTime(String
A string containing lexical representation of xsd:datetime.
lexicalXSDDateTime)

Converts the string argument into a Calendar value.

public static BigDecimal

Returns:

A BigDecimal value represented by the string argument.
parseDecimal(String
A string containing lexical representation of xsd:decimal.
lexicalXSDDecimal)

Converts the string argument into a BigDecimal value.

public static double

Returns:

A double value represented by the string argument.
parseDouble(String
A string containing lexical representation of xsd:double.
lexicalXSDDouble)

Converts the string argument into a double value.

public static float

Returns:

A float value represented by the string argument.
parseFloat(String
A string containing lexical representation of xsd:float.
lexicalXSDFloat)

Converts the string argument into a float value.

public static byte[]

Returns:

An array of bytes represented by the string argument.
parseHexBinary(String
A string containing lexical representation of xsd:hexBinary.
lexicalXSDHexBinary)

Converts the string argument into an array of bytes.

public static int

Returns:

A int value represented by the string argument.
parseInt(String
A string containing a lexical representation of xsd:int.
lexicalXSDInt)

Convert the string argument into an int value.

public static BigInteger

Returns:

A BigInteger value represented by the string argument.
parseInteger(String
A string containing a lexical representation of xsd:integer.
lexicalXSDInteger)

Convert the string argument into a BigInteger value.

public static long

Returns:

A long value represented by the string argument.
parseLong(String
A string containing lexical representation of xsd:long.
lexicalXSDLong)

Converts the string argument into a long value.

public static QName

Returns:

A QName value represented by the string argument.
parseQName(String
A string containing lexical representation of xsd:QName.
lexicalXSDQName, NamespaceContext
A namespace context for interpreting a prefix within a QName.
nsc)

Converts the string argument into a byte value.

public static short

Returns:

A short value represented by the string argument.
parseShort(String
A string containing lexical representation of xsd:short.
lexicalXSDShort)

Converts the string argument into a short value.

public static String

Returns:

A String value represented by the string argument.
parseString(String
A string containing a lexical representation of xsd:string.
lexicalXSDString)

Convert the lexical XSD string argument into a String value.

public static Calendar

Returns:

A Calendar value represented by the string argument.
parseTime(String
A string containing lexical representation of xsd:time.
lexicalXSDTime)

Converts the string argument into a Calendar value.

public static long

Returns:

A long value represented by the string argument.
parseUnsignedInt(String
A string containing lexical representation of xsd:unsignedInt.
lexicalXSDUnsignedInt)

Converts the string argument into a long value.

public static int

Returns:

An int value represented by the string argument.
parseUnsignedShort(String
A string containing lexical representation of xsd:unsignedShort.
lexicalXSDUnsignedShort)

Converts the string argument into an int value.

public static String

Returns:

A string containing a lexical representation of xsd:AnySimpleType
printAnySimpleType(String
A string value
val)

Converts a string value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:base64Binary
printBase64Binary(byte[]
An array of bytes
val)

Converts an array of bytes into a string.

public static String

Returns:

A string containing a lexical representation of xsd:boolean
printBoolean(boolean
A boolean value
val)

Converts a boolean value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:byte
printByte(byte
A byte value
val)

Converts a byte value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:date
printDate(Calendar
A Calendar value
val)

Converts a Calendar value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:dateTime
printDateTime(Calendar
A Calendar value
val)

Converts a Calendar value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:decimal
printDecimal(BigDecimal
A BigDecimal value
val)

Converts a BigDecimal value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:double
printDouble(double
A double value
val)

Converts a double value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:float
printFloat(float
A float value
val)

Converts a float value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:hexBinary
printHexBinary(byte[]
An array of bytes
val)

Converts an array of bytes into a string.

public static String

Returns:

A string containing a lexical representation of xsd:int
printInt(int
An int value
val)

Converts an int value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:integer
printInteger(BigInteger
A BigInteger value
val)

Converts a BigInteger value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:long
printLong(long
A long value
val)

Converts A long value into a string.

public static String

Returns:

A string containing a lexical representation of QName
printQName(QName
A QName value
val, NamespaceContext
A namespace context for interpreting a prefix within a QName.
nsc)

Converts a QName instance into a string.

public static String

Returns:

A string containing a lexical representation of xsd:short
printShort(short
A short value
val)

Converts a short value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:string.
printString(String
A string value.
val)

Converts the string argument into a string.

public static String

Returns:

A string containing a lexical representation of xsd:time
printTime(Calendar
A Calendar value
val)

Converts a Calendar value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:unsignedInt
printUnsignedInt(long
A long value
val)

Converts a long value into a string.

public static String

Returns:

A string containing a lexical representation of xsd:unsignedShort
printUnsignedShort(int
An int value
val)

Converts an int value into a string.

public static void
setDatatypeConverter(DatatypeConverterInterface
an instance of a class that implements the DatatypeConverterInterface class - this parameter must not be null.
converter)

This method is for Jakarta XML Binding provider use only.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

SET_DATATYPE_CONVERTER_PERMISSIONback to summary
private static final JAXBPermission SET_DATATYPE_CONVERTER_PERMISSION
theConverterback to summary
private static volatile DatatypeConverterInterface theConverter

Constructor Detail

DatatypeConverterback to summary
private DatatypeConverter()

Method Detail

initConverterback to summary
private static synchronized void initConverter()
parseAnySimpleTypeback to summary
public static String parseAnySimpleType(String lexicalXSDAnySimpleType)

Return a string containing the lexical representation of the simple type.

Parameters
lexicalXSDAnySimpleType:String

A string containing lexical representation of the simple type.

Returns:String

A string containing the lexical representation of the simple type.

parseBase64Binaryback to summary
public static byte[] parseBase64Binary(String lexicalXSDBase64Binary)

Converts the string argument into an array of bytes.

Parameters
lexicalXSDBase64Binary:String

A string containing lexical representation of xsd:base64Binary.

Returns:byte[]

An array of bytes represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary
parseBooleanback to summary
public static boolean parseBoolean(String lexicalXSDBoolean)

Converts the string argument into a boolean value.

Parameters
lexicalXSDBoolean:String

A string containing lexical representation of xsd:boolean.

Returns:boolean

A boolean value represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.
parseByteback to summary
public static byte parseByte(String lexicalXSDByte)

Converts the string argument into a byte value.

Parameters
lexicalXSDByte:String

A string containing lexical representation of xsd:byte.

Returns:byte

A byte value represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.
parseDateback to summary
public static Calendar parseDate(String lexicalXSDDate)

Converts the string argument into a Calendar value.

Parameters
lexicalXSDDate:String

A string containing lexical representation of xsd:Date.

Returns:Calendar

A Calendar value represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.
parseDateTimeback to summary
public static Calendar parseDateTime(String lexicalXSDDateTime)

Converts the string argument into a Calendar value.

Parameters
lexicalXSDDateTime:String

A string containing lexical representation of xsd:datetime.

Returns:Calendar

A Calendar object represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.
parseDecimalback to summary
public static BigDecimal parseDecimal(String lexicalXSDDecimal)

Converts the string argument into a BigDecimal value.

Parameters
lexicalXSDDecimal:String

A string containing lexical representation of xsd:decimal.

Returns:BigDecimal

A BigDecimal value represented by the string argument.

Exceptions
NumberFormatException:
lexicalXSDDecimal is not a valid string representation of java.math.BigDecimal.
parseDoubleback to summary
public static double parseDouble(String lexicalXSDDouble)

Converts the string argument into a double value.

Parameters
lexicalXSDDouble:String

A string containing lexical representation of xsd:double.

Returns:double

A double value represented by the string argument.

Exceptions
NumberFormatException:
lexicalXSDDouble is not a valid string representation of a double value.
parseFloatback to summary
public static float parseFloat(String lexicalXSDFloat)

Converts the string argument into a float value.

Parameters
lexicalXSDFloat:String

A string containing lexical representation of xsd:float.

Returns:float

A float value represented by the string argument.

Exceptions
NumberFormatException:
lexicalXSDFloat is not a valid string representation of a float value.
parseHexBinaryback to summary
public static byte[] parseHexBinary(String lexicalXSDHexBinary)

Converts the string argument into an array of bytes.

Parameters
lexicalXSDHexBinary:String

A string containing lexical representation of xsd:hexBinary.

Returns:byte[]

An array of bytes represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.
parseIntback to summary
public static int parseInt(String lexicalXSDInt)

Convert the string argument into an int value.

Parameters
lexicalXSDInt:String

A string containing a lexical representation of xsd:int.

Returns:int

A int value represented by the string argument.

Exceptions
NumberFormatException:
lexicalXSDInt is not a valid string representation of an int value.
parseIntegerback to summary
public static BigInteger parseInteger(String lexicalXSDInteger)

Convert the string argument into a BigInteger value.

Parameters
lexicalXSDInteger:String

A string containing a lexical representation of xsd:integer.

Returns:BigInteger

A BigInteger value represented by the string argument.

Exceptions
NumberFormatException:
lexicalXSDInteger is not a valid string representation of a java.math.BigInteger value.
parseLongback to summary
public static long parseLong(String lexicalXSDLong)

Converts the string argument into a long value.

Parameters
lexicalXSDLong:String

A string containing lexical representation of xsd:long.

Returns:long

A long value represented by the string argument.

Exceptions
NumberFormatException:
lexicalXSDLong is not a valid string representation of a long value.
parseQNameback to summary
public static QName parseQName(String lexicalXSDQName, NamespaceContext nsc)

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:String

A string containing lexical representation of xsd:QName.

nsc:NamespaceContext

A namespace context for interpreting a prefix within a QName.

Returns:QName

A QName value represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to XML Schema Part 2 specification or if namespace prefix of lexicalXSDQname is not bound to a URI in NamespaceContext nsc.
parseShortback to summary
public static short parseShort(String lexicalXSDShort)

Converts the string argument into a short value.

Parameters
lexicalXSDShort:String

A string containing lexical representation of xsd:short.

Returns:short

A short value represented by the string argument.

Exceptions
NumberFormatException:
lexicalXSDShort is not a valid string representation of a short value.
parseStringback to summary
public static String parseString(String lexicalXSDString)

Convert the lexical XSD string argument into a String value.

Parameters
lexicalXSDString:String

A string containing a lexical representation of xsd:string.

Returns:String

A String value represented by the string argument.

parseTimeback to summary
public static Calendar parseTime(String lexicalXSDTime)

Converts the string argument into a Calendar value.

Parameters
lexicalXSDTime:String

A string containing lexical representation of xsd:time.

Returns:Calendar

A Calendar value represented by the string argument.

Exceptions
IllegalArgumentException:
if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.
parseUnsignedIntback to summary
public static long parseUnsignedInt(String lexicalXSDUnsignedInt)

Converts the string argument into a long value.

Parameters
lexicalXSDUnsignedInt:String

A string containing lexical representation of xsd:unsignedInt.

Returns:long

A long value represented by the string argument.

Exceptions
NumberFormatException:
if string parameter can not be parsed into a long value.
parseUnsignedShortback to summary
public static int parseUnsignedShort(String lexicalXSDUnsignedShort)

Converts the string argument into an int value.

Parameters
lexicalXSDUnsignedShort:String

A string containing lexical representation of xsd:unsignedShort.

Returns:int

An int value represented by the string argument.

Exceptions
NumberFormatException:
if string parameter can not be parsed into an int value.
printAnySimpleTypeback to summary
public static String printAnySimpleType(String val)

Converts a string value into a string.

Parameters
val:String

A string value

Returns:String

A string containing a lexical representation of xsd:AnySimpleType

printBase64Binaryback to summary
public static String printBase64Binary(byte[] val)

Converts an array of bytes into a string.

Parameters
val:byte[]

An array of bytes

Returns:String

A string containing a lexical representation of xsd:base64Binary

Exceptions
IllegalArgumentException:
if val is null.
printBooleanback to summary
public static String printBoolean(boolean val)

Converts a boolean value into a string.

Parameters
val:boolean

A boolean value

Returns:String

A string containing a lexical representation of xsd:boolean

printByteback to summary
public static String printByte(byte val)

Converts a byte value into a string.

Parameters
val:byte

A byte value

Returns:String

A string containing a lexical representation of xsd:byte

printDateback to summary
public static String printDate(Calendar val)

Converts a Calendar value into a string.

Parameters
val:Calendar

A Calendar value

Returns:String

A string containing a lexical representation of xsd:date

Exceptions
IllegalArgumentException:
if val is null.
printDateTimeback to summary
public static String printDateTime(Calendar val)

Converts a Calendar value into a string.

Parameters
val:Calendar

A Calendar value

Returns:String

A string containing a lexical representation of xsd:dateTime

Exceptions
IllegalArgumentException:
if val is null.
printDecimalback to summary
public static String printDecimal(BigDecimal val)

Converts a BigDecimal value into a string.

Parameters
val:BigDecimal

A BigDecimal value

Returns:String

A string containing a lexical representation of xsd:decimal

Exceptions
IllegalArgumentException:
val is null.
printDoubleback to summary
public static String printDouble(double val)

Converts a double value into a string.

Parameters
val:double

A double value

Returns:String

A string containing a lexical representation of xsd:double

printFloatback to summary
public static String printFloat(float val)

Converts a float value into a string.

Parameters
val:float

A float value

Returns:String

A string containing a lexical representation of xsd:float

printHexBinaryback to summary
public static String printHexBinary(byte[] val)

Converts an array of bytes into a string.

Parameters
val:byte[]

An array of bytes

Returns:String

A string containing a lexical representation of xsd:hexBinary

Exceptions
IllegalArgumentException:
if val is null.
printIntback to summary
public static String printInt(int val)

Converts an int value into a string.

Parameters
val:int

An int value

Returns:String

A string containing a lexical representation of xsd:int

printIntegerback to summary
public static String printInteger(BigInteger val)

Converts a BigInteger value into a string.

Parameters
val:BigInteger

A BigInteger value

Returns:String

A string containing a lexical representation of xsd:integer

Exceptions
IllegalArgumentException:
val is null.
printLongback to summary
public static String printLong(long val)

Converts A long value into a string.

Parameters
val:long

A long value

Returns:String

A string containing a lexical representation of xsd:long

printQNameback to summary
public static String printQName(QName val, NamespaceContext nsc)

Converts a QName instance into a string.

Parameters
val:QName

A QName value

nsc:NamespaceContext

A namespace context for interpreting a prefix within a QName.

Returns:String

A string containing a lexical representation of QName

Exceptions
IllegalArgumentException:
if val is null or if nsc is non-null or nsc.getPrefix(nsprefixFromVal) is null.
printShortback to summary
public static String printShort(short val)

Converts a short value into a string.

Parameters
val:short

A short value

Returns:String

A string containing a lexical representation of xsd:short

printStringback to summary
public static String printString(String val)

Converts the string argument into a string.

Parameters
val:String

A string value.

Returns:String

A string containing a lexical representation of xsd:string.

printTimeback to summary
public static String printTime(Calendar val)

Converts a Calendar value into a string.

Parameters
val:Calendar

A Calendar value

Returns:String

A string containing a lexical representation of xsd:time

Exceptions
IllegalArgumentException:
if val is null.
printUnsignedIntback to summary
public static String printUnsignedInt(long val)

Converts a long value into a string.

Parameters
val:long

A long value

Returns:String

A string containing a lexical representation of xsd:unsignedInt

printUnsignedShortback to summary
public static String printUnsignedShort(int val)

Converts an int value into a string.

Parameters
val:int

An int value

Returns:String

A string containing a lexical representation of xsd:unsignedShort

setDatatypeConverterback to summary
public static void setDatatypeConverter(DatatypeConverterInterface converter)

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:DatatypeConverterInterface

an instance of a class that implements the DatatypeConverterInterface class - this parameter must not be null.

Exceptions
IllegalArgumentException:
if the parameter is null
SecurityException:
If the SecurityManager in charge denies the access to set the datatype converter.
See Also
JAXBPermission