+ * 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 {@link DatatypeConverterInterface + * 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 + * {@link #setDatatypeConverter(DatatypeConverterInterface) + * 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+ * 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. + * + * @param converter an instance of a class that implements the + * DatatypeConverterInterface class - this parameter must not be null. + * @throws IllegalArgumentException if the parameter is null + * @throws SecurityException + * If the {@link SecurityManager} in charge denies the access to + * set the datatype converter. + * @see JAXBPermission + */ + public static void setDatatypeConverter( DatatypeConverterInterface converter ) { + if( converter == null ) { + throw new IllegalArgumentException( + Messages.format( Messages.CONVERTER_MUST_NOT_BE_NULL ) ); + } else if( theConverter == null ) { + SecurityManager sm = System.getSecurityManager(); + if (sm != null) + sm.checkPermission(SET_DATATYPE_CONVERTER_PERMISSION); + theConverter = converter; + } + } + + private static synchronized void initConverter() { + theConverter = new DatatypeConverterImpl(); + } + + /** + *
+ * Convert the lexical XSD string argument into a String value. + * @param lexicalXSDString + * A string containing a lexical representation of + * xsd:string. + * @return + * A String value represented by the string argument. + */ + public static String parseString( String lexicalXSDString ) { + if (theConverter == null) initConverter(); + return theConverter.parseString( lexicalXSDString ); + } + + /** + *
+ * Convert the string argument into a BigInteger value.
+ * @param lexicalXSDInteger
+ * A string containing a lexical representation of
+ * xsd:integer.
+ * @return
+ * A BigInteger value represented by the string argument.
+ * @throws NumberFormatException lexicalXSDInteger is not a valid string representation of a {@link java.math.BigInteger} value.
+ */
+ public static java.math.BigInteger parseInteger( String lexicalXSDInteger ) {
+ if (theConverter == null) initConverter();
+ return theConverter.parseInteger( lexicalXSDInteger );
+ }
+
+ /**
+ *
+ * Convert the string argument into an int value.
+ * @param lexicalXSDInt
+ * A string containing a lexical representation of
+ * xsd:int.
+ * @return
+ * A int value represented by the string argument.
+ * @throws NumberFormatException lexicalXSDInt is not a valid string representation of an int value.
+ */
+ public static int parseInt( String lexicalXSDInt ) {
+ if (theConverter == null) initConverter();
+ return theConverter.parseInt( lexicalXSDInt );
+ }
+
+ /**
+ *
+ * Converts the string argument into a long value.
+ * @param lexicalXSDLong
+ * A string containing lexical representation of
+ * xsd:long.
+ * @return
+ * A long value represented by the string argument.
+ * @throws NumberFormatException lexicalXSDLong is not a valid string representation of a long value.
+ */
+ public static long parseLong( String lexicalXSDLong ) {
+ if (theConverter == null) initConverter();
+ return theConverter.parseLong( lexicalXSDLong );
+ }
+
+ /**
+ *
+ * Converts the string argument into a short value.
+ * @param lexicalXSDShort
+ * A string containing lexical representation of
+ * xsd:short.
+ * @return
+ * A short value represented by the string argument.
+ * @throws NumberFormatException lexicalXSDShort is not a valid string representation of a short value.
+ */
+ public static short parseShort( String lexicalXSDShort ) {
+ if (theConverter == null) initConverter();
+ return theConverter.parseShort( lexicalXSDShort );
+ }
+
+ /**
+ *
+ * Converts the string argument into a BigDecimal value.
+ * @param lexicalXSDDecimal
+ * A string containing lexical representation of
+ * xsd:decimal.
+ * @return
+ * A BigDecimal value represented by the string argument.
+ * @throws NumberFormatException lexicalXSDDecimal is not a valid string representation of {@link java.math.BigDecimal}.
+ */
+ public static java.math.BigDecimal parseDecimal( String lexicalXSDDecimal ) {
+ if (theConverter == null) initConverter();
+ return theConverter.parseDecimal( lexicalXSDDecimal );
+ }
+
+ /**
+ *
+ * Converts the string argument into a float value.
+ * @param lexicalXSDFloat
+ * A string containing lexical representation of
+ * xsd:float.
+ * @return
+ * A float value represented by the string argument.
+ * @throws NumberFormatException lexicalXSDFloat is not a valid string representation of a float value.
+ */
+ public static float parseFloat( String lexicalXSDFloat ) {
+ if (theConverter == null) initConverter();
+ return theConverter.parseFloat( lexicalXSDFloat );
+ }
+
+ /**
+ *
+ * Converts the string argument into a double value.
+ * @param lexicalXSDDouble
+ * A string containing lexical representation of
+ * xsd:double.
+ * @return
+ * A double value represented by the string argument.
+ * @throws NumberFormatException lexicalXSDDouble is not a valid string representation of a double value.
+ */
+ public static double parseDouble( String lexicalXSDDouble ) {
+ if (theConverter == null) initConverter();
+ return theConverter.parseDouble( lexicalXSDDouble );
+ }
+
+ /**
+ *
+ * Converts the string argument into a boolean value. + * @param lexicalXSDBoolean + * A string containing lexical representation of + * xsd:boolean. + * @return + * 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. + */ + public static boolean parseBoolean( String lexicalXSDBoolean ) { + if (theConverter == null) initConverter(); + return theConverter.parseBoolean( lexicalXSDBoolean ); + } + + /** + *
+ * Converts the string argument into a byte value. + * @param lexicalXSDByte + * A string containing lexical representation of + * xsd:byte. + * @return + * 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. + */ + public static byte parseByte( String lexicalXSDByte ) { + if (theConverter == null) initConverter(); + return theConverter.parseByte( lexicalXSDByte ); + } + + /** + *
+ * 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 + * + * @param lexicalXSDQName + * A string containing lexical representation of xsd:QName. + * @param nsc + * A namespace context for interpreting a prefix within a QName. + * @return + * 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. + */ + public static javax.xml.namespace.QName parseQName( String lexicalXSDQName, + NamespaceContext nsc) { + if (theConverter == null) initConverter(); + return theConverter.parseQName( lexicalXSDQName, nsc ); + } + + /** + *
+ * Converts the string argument into a Calendar value. + * @param lexicalXSDDateTime + * A string containing lexical representation of + * xsd:datetime. + * @return + * 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. + */ + public static java.util.Calendar parseDateTime( String lexicalXSDDateTime ) { + if (theConverter == null) initConverter(); + return theConverter.parseDateTime( lexicalXSDDateTime ); + } + + /** + *
+ * Converts the string argument into an array of bytes. + * @param lexicalXSDBase64Binary + * A string containing lexical representation + * of xsd:base64Binary. + * @return + * 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 + */ + public static byte[] parseBase64Binary( String lexicalXSDBase64Binary ) { + if (theConverter == null) initConverter(); + return theConverter.parseBase64Binary( lexicalXSDBase64Binary ); + } + + /** + *
+ * Converts the string argument into an array of bytes. + * @param lexicalXSDHexBinary + * A string containing lexical representation of + * xsd:hexBinary. + * @return + * 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. + */ + public static byte[] parseHexBinary( String lexicalXSDHexBinary ) { + if (theConverter == null) initConverter(); + return theConverter.parseHexBinary( lexicalXSDHexBinary ); + } + + /** + *
+ * Converts the string argument into a long value. + * @param lexicalXSDUnsignedInt + * A string containing lexical representation + * of xsd:unsignedInt. + * @return + * A long value represented by the string argument. + * @throws NumberFormatException if string parameter can not be parsed into a long value. + */ + public static long parseUnsignedInt( String lexicalXSDUnsignedInt ) { + if (theConverter == null) initConverter(); + return theConverter.parseUnsignedInt( lexicalXSDUnsignedInt ); + } + + /** + *
+ * Converts the string argument into an int value. + * @param lexicalXSDUnsignedShort + * A string containing lexical + * representation of xsd:unsignedShort. + * @return + * An int value represented by the string argument. + * @throws NumberFormatException if string parameter can not be parsed into an int value. + */ + public static int parseUnsignedShort( String lexicalXSDUnsignedShort ) { + if (theConverter == null) initConverter(); + return theConverter.parseUnsignedShort( lexicalXSDUnsignedShort ); + } + + /** + *
+ * Converts the string argument into a Calendar value. + * @param lexicalXSDTime + * A string containing lexical representation of + * xsd:time. + * @return + * 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. + */ + public static java.util.Calendar parseTime( String lexicalXSDTime ) { + if (theConverter == null) initConverter(); + return theConverter.parseTime( lexicalXSDTime ); + } + /** + *
+ * Converts the string argument into a Calendar value. + * @param lexicalXSDDate + * A string containing lexical representation of + * xsd:Date. + * @return + * 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. + */ + public static java.util.Calendar parseDate( String lexicalXSDDate ) { + if (theConverter == null) initConverter(); + return theConverter.parseDate( lexicalXSDDate ); + } + + /** + *
+ * Return a string containing the lexical representation of the + * simple type. + * @param lexicalXSDAnySimpleType + * A string containing lexical + * representation of the simple type. + * @return + * A string containing the lexical representation of the + * simple type. + */ + public static String parseAnySimpleType( String lexicalXSDAnySimpleType ) { + if (theConverter == null) initConverter(); + return theConverter.parseAnySimpleType( lexicalXSDAnySimpleType ); + } + /** + *
+ * Converts the string argument into a string. + * @param val + * A string value. + * @return + * A string containing a lexical representation of xsd:string. + */ + // also indicate the print methods produce a lexical + // representation for given Java datatypes. + + public static String printString( String val ) { + if (theConverter == null) initConverter(); + return theConverter.printString( val ); + } + + /** + *
+ * Converts a BigInteger value into a string. + * @param val + * A BigInteger value + * @return + * A string containing a lexical representation of xsd:integer + * @throws IllegalArgumentException val is null. + */ + public static String printInteger( java.math.BigInteger val ) { + if (theConverter == null) initConverter(); + return theConverter.printInteger( val ); + } + + /** + *
+ * Converts an int value into a string. + * @param val + * An int value + * @return + * A string containing a lexical representation of xsd:int + */ + public static String printInt( int val ) { + if (theConverter == null) initConverter(); + return theConverter.printInt( val ); + } + + /** + *
+ * Converts A long value into a string. + * @param val + * A long value + * @return + * A string containing a lexical representation of xsd:long + */ + public static String printLong( long val ) { + if (theConverter == null) initConverter(); + return theConverter.printLong( val ); + } + + /** + *
+ * Converts a short value into a string. + * @param val + * A short value + * @return + * A string containing a lexical representation of xsd:short + */ + public static String printShort( short val ) { + if (theConverter == null) initConverter(); + return theConverter.printShort( val ); + } + + /** + *
+ * Converts a BigDecimal value into a string. + * @param val + * A BigDecimal value + * @return + * A string containing a lexical representation of xsd:decimal + * @throws IllegalArgumentException val is null. + */ + public static String printDecimal( java.math.BigDecimal val ) { + if (theConverter == null) initConverter(); + return theConverter.printDecimal( val ); + } + + /** + *
+ * Converts a float value into a string. + * @param val + * A float value + * @return + * A string containing a lexical representation of xsd:float + */ + public static String printFloat( float val ) { + if (theConverter == null) initConverter(); + return theConverter.printFloat( val ); + } + + /** + *
+ * Converts a double value into a string. + * @param val + * A double value + * @return + * A string containing a lexical representation of xsd:double + */ + public static String printDouble( double val ) { + if (theConverter == null) initConverter(); + return theConverter.printDouble( val ); + } + + /** + *
+ * Converts a boolean value into a string. + * @param val + * A boolean value + * @return + * A string containing a lexical representation of xsd:boolean + */ + public static String printBoolean( boolean val ) { + if (theConverter == null) initConverter(); + return theConverter.printBoolean( val ); + } + + /** + *
+ * Converts a byte value into a string. + * @param val + * A byte value + * @return + * A string containing a lexical representation of xsd:byte + */ + public static String printByte( byte val ) { + if (theConverter == null) initConverter(); + return theConverter.printByte( val ); + } + + /** + *
+ * Converts a QName instance into a string. + * @param val + * A QName value + * @param nsc + * A namespace context for interpreting a prefix within a QName. + * @return + * 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. + */ + public static String printQName( javax.xml.namespace.QName val, + NamespaceContext nsc ) { + if (theConverter == null) initConverter(); + return theConverter.printQName( val, nsc ); + } + + /** + *
+ * Converts a Calendar value into a string. + * @param val + * A Calendar value + * @return + * A string containing a lexical representation of xsd:dateTime + * @throws IllegalArgumentException if val is null. + */ + public static String printDateTime( java.util.Calendar val ) { + if (theConverter == null) initConverter(); + return theConverter.printDateTime( val ); + } + + /** + *
+ * Converts an array of bytes into a string. + * @param val + * An array of bytes + * @return + * A string containing a lexical representation of xsd:base64Binary + * @throws IllegalArgumentException if val is null. + */ + public static String printBase64Binary( byte[] val ) { + if (theConverter == null) initConverter(); + return theConverter.printBase64Binary( val ); + } + + /** + *
+ * Converts an array of bytes into a string. + * @param val + * An array of bytes + * @return + * A string containing a lexical representation of xsd:hexBinary + * @throws IllegalArgumentException if val is null. + */ + public static String printHexBinary( byte[] val ) { + if (theConverter == null) initConverter(); + return theConverter.printHexBinary( val ); + } + + /** + *
+ * Converts a long value into a string. + * @param val + * A long value + * @return + * A string containing a lexical representation of xsd:unsignedInt + */ + public static String printUnsignedInt( long val ) { + if (theConverter == null) initConverter(); + return theConverter.printUnsignedInt( val ); + } + + /** + *
+ * Converts an int value into a string. + * @param val + * An int value + * @return + * A string containing a lexical representation of xsd:unsignedShort + */ + public static String printUnsignedShort( int val ) { + if (theConverter == null) initConverter(); + return theConverter.printUnsignedShort( val ); + } + + /** + *
+ * Converts a Calendar value into a string. + * @param val + * A Calendar value + * @return + * A string containing a lexical representation of xsd:time + * @throws IllegalArgumentException if val is null. + */ + public static String printTime( java.util.Calendar val ) { + if (theConverter == null) initConverter(); + return theConverter.printTime( val ); + } + + /** + *
+ * Converts a Calendar value into a string. + * @param val + * A Calendar value + * @return + * A string containing a lexical representation of xsd:date + * @throws IllegalArgumentException if val is null. + */ + public static String printDate( java.util.Calendar val ) { + if (theConverter == null) initConverter(); + return theConverter.printDate( val ); + } + + /** + *
+ * Converts a string value into a string. + * @param val + * A string value + * @return + * A string containing a lexical representation of xsd:AnySimpleType + */ + public static String printAnySimpleType( String val ) { + if (theConverter == null) initConverter(); + return theConverter.printAnySimpleType( val ); + } +}