/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2003-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.xml.bind;
import javax.xml.namespace.
NamespaceContext;
/**
* <p>
* 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 (
* <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
* specification </a>) and hence may be difficult to write.
* </p>
* <p>
* 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:
* <blockquote>
* <pre>
* // 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;
* }
* </pre>
* </blockquote>
* <p>
* There is a static parse and print method corresponding to each parse and
* print method respectively in the {@link DatatypeConverterInterface
* DatatypeConverterInterface}.
* <p>
* The static methods defined in the class can also be used to specify
* a parse or a print method in a javaType binding declaration.
* </p>
* <p>
* 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.
* </p>
*
* <p>
* 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.
* </p>
*
* @author <ul><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker,Sun Microsystems Inc.</li></ul>
* @see DatatypeConverterInterface
* @see ParseConversionEvent
* @see PrintConversionEvent
* @since 1.6, JAXB 1.0
*/
final public class
DatatypeConverter {
// delegate to this instance of DatatypeConverter
private static volatile
DatatypeConverterInterface theConverter = null;
private final static
JAXBPermission SET_DATATYPE_CONVERTER_PERMISSION =
new
JAXBPermission("setDatatypeConverter");
private
DatatypeConverter() {
// private constructor
}
/**
* This method is for JAXB provider use only.
* <p>
* 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.
*
* <p>
* 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();
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 <code>lexicalXSDInteger</code> 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 );
}
/**
* <p>
* 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 <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value.
*/
public static int
parseInt(
String lexicalXSDInt ) {
if (
theConverter == null)
initConverter();
return
theConverter.
parseInt(
lexicalXSDInt );
}
/**
* <p>
* 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 <code>lexicalXSDLong</code> is not a valid string representation of a <code>long</code> value.
*/
public static long
parseLong(
String lexicalXSDLong ) {
if (
theConverter == null)
initConverter();
return
theConverter.
parseLong(
lexicalXSDLong );
}
/**
* <p>
* 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 <code>lexicalXSDShort</code> is not a valid string representation of a <code>short</code> value.
*/
public static short
parseShort(
String lexicalXSDShort ) {
if (
theConverter == null)
initConverter();
return
theConverter.
parseShort(
lexicalXSDShort );
}
/**
* <p>
* 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 <code>lexicalXSDDecimal</code> 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 );
}
/**
* <p>
* 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 <code>lexicalXSDFloat</code> is not a valid string representation of a <code>float</code> value.
*/
public static float
parseFloat(
String lexicalXSDFloat ) {
if (
theConverter == null)
initConverter();
return
theConverter.
parseFloat(
lexicalXSDFloat );
}
/**
* <p>
* 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 <code>lexicalXSDDouble</code> is not a valid string representation of a <code>double</code> value.
*/
public static double
parseDouble(
String lexicalXSDDouble ) {
if (
theConverter == null)
initConverter();
return
theConverter.
parseDouble(
lexicalXSDDouble );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* Converts the string argument into a byte value.
*
* <p>
* String parameter {@code lexicalXSDQname} must conform to lexical value space specifed at
* <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part 2:Datatypes specification:QNames</a>
*
* @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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
/**
* <p>
* 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 );
}
}