DatatypeConverter (Java EE 5 SDK) - Java Platform, Enterprise Edition v5.0 API Specifications

Overview

Package

Class

Tree

Deprecated

Index

Help

Java EE 5 SDK

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class DatatypeConverter

java.lang.Object
  javax.xml.bind.DatatypeConverter

public final class DatatypeConverter
extends Object
extends Object

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.

Since:

JAXB1.0

Version:

$Revision: 1.3 $

Author:

Sekhar Vajjhala, Sun Microsystems, Inc.
Joe Fialli, Sun Microsystems Inc.
Kohsuke Kawaguchi, Sun Microsystems, Inc.
Ryan Shoemaker,Sun Microsystems Inc.

Method Summary

static 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 parseByte(String lexicalXSDByte)
           Converts the string argument into a byte value.

static Calendar parseDate(String lexicalXSDDate)
           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 parseInt(String lexicalXSDInt)
           Convert the string argument into an int value.

static BigInteger parseInteger(String lexicalXSDInteger)
           Convert the string argument into a BigInteger value.

static long parseLong(String lexicalXSDLong)
           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 parseTime(String lexicalXSDTime)
           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 printDate(Calendar val)
           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 printTime(Calendar val)
           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 JAXB provider use only.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Summary
`static 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`	`parseByte(String lexicalXSDByte)` Converts the string argument into a byte value.
`static Calendar`	`parseDate(String lexicalXSDDate)` 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`	`parseInt(String lexicalXSDInt)` Convert the string argument into an int value.
`static BigInteger`	`parseInteger(String lexicalXSDInteger)` Convert the string argument into a BigInteger value.
`static long`	`parseLong(String lexicalXSDLong)` 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`	`parseTime(String lexicalXSDTime)` 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`	`printDate(Calendar val)` 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`	`printTime(Calendar val)` 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 JAXB provider use only.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

setDatatypeConverter

public static void setDatatypeConverter(DatatypeConverterInterface converter)

This method is for JAXB provider use only.

JAXB Providers are required to call this method at some point before allowing any of the JAXB 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 null

parseString

public static String parseString(String lexicalXSDString)

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

public static BigInteger parseInteger(String lexicalXSDInteger)

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 a BigInteger value.

parseInt

public static int parseInt(String lexicalXSDInt)

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 an int value.

parseLong

public static long parseLong(String lexicalXSDLong)

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 a long value.

parseShort

public static short parseShort(String lexicalXSDShort)

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 a short value.

parseDecimal

public static BigDecimal parseDecimal(String lexicalXSDDecimal)

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 of BigDecimal.

parseFloat

public static float parseFloat(String lexicalXSDFloat)

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 a float value.

parseDouble

public static double parseDouble(String lexicalXSDDouble)

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 a double value.

parseBoolean

public static boolean parseBoolean(String lexicalXSDBoolean)

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

public static byte parseByte(String lexicalXSDByte)

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

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 - 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 of lexicalXSDQname is not bound to a URI in NamespaceContext nsc.

parseDateTime

public static Calendar parseDateTime(String lexicalXSDDateTime)

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

public static byte[] parseBase64Binary(String lexicalXSDBase64Binary)

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

public static byte[] parseHexBinary(String lexicalXSDHexBinary)

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

public static long parseUnsignedInt(String lexicalXSDUnsignedInt)

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 a long value.

parseUnsignedShort

public static int parseUnsignedShort(String lexicalXSDUnsignedShort)

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 an int value.

parseTime

public static Calendar parseTime(String lexicalXSDTime)

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

public static Calendar parseDate(String lexicalXSDDate)

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

public static String parseAnySimpleType(String lexicalXSDAnySimpleType)

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

public static String printString(String val)

Converts the string argument into a string.

Parameters:: val - A string value.
Returns:: A string containing a lexical representation of xsd:string.

printInteger

public static String printInteger(BigInteger val)

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

public static String printInt(int val)

Converts an int value into a string.

Parameters:: val - An int value
Returns:: A string containing a lexical representation of xsd:int

printLong

public static String printLong(long val)

Converts A long value into a string.

Parameters:: val - A long value
Returns:: A string containing a lexical representation of xsd:long

printShort

public static String printShort(short val)

Converts a short value into a string.

Parameters:: val - A short value
Returns:: A string containing a lexical representation of xsd:short

printDecimal

public static String printDecimal(BigDecimal val)

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

public static String printFloat(float val)

Converts a float value into a string.

Parameters:: val - A float value
Returns:: A string containing a lexical representation of xsd:float

printDouble

public static String printDouble(double val)

Converts a double value into a string.

Parameters:: val - A double value
Returns:: A string containing a lexical representation of xsd:double

printBoolean

public static String printBoolean(boolean val)

Converts a boolean value into a string.

Parameters:: val - A boolean value
Returns:: A string containing a lexical representation of xsd:boolean

printByte

public static String printByte(byte val)

Converts a byte value into a string.

Parameters:: val - A byte value
Returns:: A string containing a lexical representation of xsd:byte

printQName

public static String printQName(QName val,
                                NamespaceContext nsc)

Converts a QName instance into a string.

Parameters:: val - A QName value; nsc - A namespace context for interpreting a prefix within a QName.
Returns:: A string containing a lexical representation of QName
Throws:: IllegalArgumentException - if val is null or if nsc is non-null or nsc.getPrefix(nsprefixFromVal) is null.

printDateTime

public static String printDateTime(Calendar val)

Converts a Calendar value into a string.

Parameters:: val - A Calendar value
Returns:: A string containing a lexical representation of xsd:dateTime
Throws:: IllegalArgumentException - if val is null.

printBase64Binary

public static String printBase64Binary(byte[] val)

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 - if val is null.

printHexBinary

public static String printHexBinary(byte[] val)

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 - if val is null.

printUnsignedInt

public static String printUnsignedInt(long val)

Converts a long value into a string.

Parameters:: val - A long value
Returns:: A string containing a lexical representation of xsd:unsignedInt

printUnsignedShort

public static String printUnsignedShort(int val)

Converts an int value into a string.

Parameters:: val - An int value
Returns:: A string containing a lexical representation of xsd:unsignedShort

printTime

public static String printTime(Calendar val)

Converts a Calendar value into a string.

Parameters:: val - A Calendar value
Returns:: A string containing a lexical representation of xsd:time
Throws:: IllegalArgumentException - if val is null.

printDate

public static String printDate(Calendar val)

Converts a Calendar value into a string.

Parameters:: val - A Calendar value
Returns:: A string containing a lexical representation of xsd:date
Throws:: IllegalArgumentException - if val is null.

printAnySimpleType

public static String printAnySimpleType(String val)

Converts a string value into a string.

Parameters:: val - A string value
Returns:: A string containing a lexical representation of xsd:AnySimpleType

Overview

Package

Class

Tree

Deprecated

Index

Help

Java EE 5 SDK

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature

DatatypeConverter (Java EE 5 SDK) - Java Platform, Enterprise Edition v5.0 API Specifications

javax.xml.bind Class DatatypeConverter

setDatatypeConverter

parseString

parseInteger

parseInt

parseLong

parseShort

parseDecimal

parseFloat

parseDouble

parseBoolean

parseByte

parseQName

parseDateTime

parseBase64Binary

parseHexBinary

parseUnsignedInt

parseUnsignedShort

parseTime

parseDate

parseAnySimpleType

printString

printInteger

printInt

printLong

printShort

printDecimal

printFloat

printDouble

printBoolean

printByte

printQName

printDateTime

printBase64Binary

printHexBinary

printUnsignedInt

printUnsignedShort

printTime

printDate

printAnySimpleType

javax.xml.bind
Class DatatypeConverter