Open Source Repository

Home /jaxb/jaxb-api-2.2.4 | Repository Home



javax/xml/bind/DatatypeConverter.java
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2003-2011 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://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/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 packager/legal/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 JAXB1.0
 */

final public class DatatypeConverter {

    // delegate to this instance of DatatypeConverter
    private static 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 setDatatypeConverterDatatypeConverterInterface converter ) {
        ifconverter == null ) {
            throw new IllegalArgumentException
                Messages.formatMessages.CONVERTER_MUST_NOT_BE_NULL ) );
        else iftheConverter == 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 parseStringString lexicalXSDString ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseStringlexicalXSDString );
    }

    /**
     <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 parseIntegerString lexicalXSDInteger ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseIntegerlexicalXSDInteger );
    }

    /**
     <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 parseIntString lexicalXSDInt ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseIntlexicalXSDInt );
    }

    /**
     <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 parseLongString lexicalXSDLong ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseLonglexicalXSDLong );
    }

    /**
     <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 parseShortString lexicalXSDShort ) { 
        if (theConverter == nullinitConverter();
        return theConverter.parseShortlexicalXSDShort );
    }

    /**
     <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 parseDecimalString lexicalXSDDecimal ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseDecimallexicalXSDDecimal );
    }

    /**
     <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 parseFloatString lexicalXSDFloat ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseFloatlexicalXSDFloat );
    }

    /**
     <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 parseDoubleString lexicalXSDDouble ) { 
        if (theConverter == nullinitConverter();
        return theConverter.parseDoublelexicalXSDDouble );
    }

    /**
     <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 parseBooleanString lexicalXSDBoolean ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseBooleanlexicalXSDBoolean );
    }

    /**
     <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 parseByteString lexicalXSDByte ) { 
        if (theConverter == nullinitConverter();
        return theConverter.parseBytelexicalXSDByte );
    }

    /**
     <p>
     * Converts the string argument into a byte value.
     *
     <p>
     * String parameter <tt>lexicalXSDQname</tt> 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 <tt>lexicalXSDQname</tt> is not bound to a URI in NamespaceContext <tt>nsc</tt>.
     */ 
    public static javax.xml.namespace.QName parseQNameString lexicalXSDQName,
                                NamespaceContext nsc) {
        if (theConverter == nullinitConverter();
        return theConverter.parseQNamelexicalXSDQName, 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 parseDateTimeString lexicalXSDDateTime ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseDateTimelexicalXSDDateTime );
    }

    /**
     <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[] parseBase64BinaryString lexicalXSDBase64Binary ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseBase64BinarylexicalXSDBase64Binary );
    }

    /**
     <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[] parseHexBinaryString lexicalXSDHexBinary ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseHexBinarylexicalXSDHexBinary );
    }

    /**
     <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 <tt>long</tt> value.
     */ 
    public static long parseUnsignedIntString lexicalXSDUnsignedInt ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseUnsignedIntlexicalXSDUnsignedInt );
    }

    /**
     <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 <tt>int</tt> value.
     */ 
    public static int  parseUnsignedShortString lexicalXSDUnsignedShort ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseUnsignedShortlexicalXSDUnsignedShort );
    }

    /**
     <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 parseTimeString lexicalXSDTime ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseTimelexicalXSDTime )
    }
    /**
     <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 parseDateString lexicalXSDDate ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseDatelexicalXSDDate );
    }

    /**
     <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 parseAnySimpleTypeString lexicalXSDAnySimpleType ) {
        if (theConverter == nullinitConverter();
        return theConverter.parseAnySimpleTypelexicalXSDAnySimpleType );
    }
    /**
     <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 printStringString val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printStringval );
    }

    /**
     <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 <tt>val</tt> is null.
     */ 
    public static String printIntegerjava.math.BigInteger val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printIntegerval );
    }

    /**
     <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 printIntint val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printIntval );
    }

    /**
     <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 printLonglong val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printLongval );
    }

    /**
     <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 printShortshort val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printShortval );
    }

    /**
     <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 <tt>val</tt> is null.
     */ 
    public static String printDecimaljava.math.BigDecimal val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printDecimalval );
    }

    /**
     <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 printFloatfloat val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printFloatval );
    }

    /**
     <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 printDoubledouble val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printDoubleval );
    }

    /**
     <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 printBooleanboolean val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printBooleanval );
    }

    /**
     <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 printBytebyte val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printByteval );
    }

    /**
     <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 <tt>val</tt> is null or 
     * if <tt>nsc</tt> is non-null or <tt>nsc.getPrefix(nsprefixFromVal)</tt> is null.
     */ 
    public static String printQNamejavax.xml.namespace.QName val,
                                     NamespaceContext nsc ) {
        if (theConverter == nullinitConverter();
        return theConverter.printQNameval, 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 <tt>val</tt> is null.
     */ 
    public static String printDateTimejava.util.Calendar val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printDateTimeval );
    }

    /**
     <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 <tt>val</tt> is null.
     */ 
    public static String printBase64Binarybyte[] val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printBase64Binaryval );
    }

    /**
     <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 <tt>val</tt> is null.
     */ 
    public static String printHexBinarybyte[] val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printHexBinaryval );
    }

    /**
     <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 printUnsignedIntlong val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printUnsignedIntval );
    }

    /**
     <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 printUnsignedShortint val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printUnsignedShortval );
    }

    /**
     <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 <tt>val</tt> is null.
     */ 
    public static String printTimejava.util.Calendar val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printTimeval );
    }

    /**
     <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 <tt>val</tt> is null.
     */ 
    public static String printDatejava.util.Calendar val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printDateval );
    }

    /**
     <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 printAnySimpleTypeString val ) {
        if (theConverter == nullinitConverter();
        return theConverter.printAnySimpleTypeval );
    }
}