/* * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.xml.bind; import 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 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 {@code 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 {@code lexicalXSDQname} is not bound to a URI in NamespaceContext {@code 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 {@code 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 {@code 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 {@code 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 {@code 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 {@code val} is null or * if {@code nsc} is non-null or {@code 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 {@code 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 {@code 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 {@code 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 {@code 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 {@code 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 ); } }