DatatypeConverterInterface.java revision 325
325N/A * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * The DatatypeConverterInterface is for JAXB provider use only. A 325N/A * JAXB provider must supply a class that implements this interface. 325N/A * JAXB Providers are required to call the 325N/A * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) 325N/A * DatatypeConverter.setDatatypeConverter} api at 325N/A * some point before the first marshal or unmarshal operation (perhaps during 325N/A * the call to JAXBContext.newInstance). This step is necessary to configure 325N/A * the converter that should be used to perform the print and parse 325N/A * functionality. Calling this api repeatedly will have no effect - the 325N/A * DatatypeConverter instance passed into the first invocation is the one that 325N/A * will be used from then on. 325N/A * This interface defines the parse and print methods. There is one 325N/A * parse and print method for each XML schema datatype specified in the 325N/A * the default binding Table 5-1 in the JAXB specification. 325N/A * The parse and print methods defined here are invoked by the static parse 325N/A * and print methods defined in the {@link DatatypeConverter DatatypeConverter} 325N/A * A parse method for a XML schema datatype must be capable of converting any 325N/A * lexical representation of the XML schema datatype ( specified by the 325N/A * specification</a> into a value in the value space of the XML schema datatype. 325N/A * If an error is encountered during conversion, then an IllegalArgumentException 325N/A * or a subclass of IllegalArgumentException must be thrown by the method. 325N/A * A print method for a XML schema datatype can output any lexical 325N/A * representation that is valid with respect to the XML schema datatype. 325N/A * If an error is encountered during conversion, then an IllegalArgumentException, 325N/A * or a subclass of IllegalArgumentException must be thrown by the method. 325N/A * The prefix xsd: is used to refer to XML schema datatypes 325N/A * @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> 325N/A * @see DatatypeConverter 325N/A * @see ParseConversionEvent 325N/A * @see PrintConversionEvent 325N/A * Convert the string argument into a string. 325N/A * @param lexicalXSDString 325N/A * A lexical representation of the XML Schema datatype xsd:string 325N/A * A string that is the same as the input string. 325N/A * Convert the string argument into a BigInteger value. 325N/A * @param lexicalXSDInteger 325N/A * A string containing a lexical representation of 325N/A * A BigInteger value represented by the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDInteger</code> is not a valid string representation of a {@link java.math.BigInteger} value. 325N/A * Convert the string argument into an int value. 325N/A * A string containing a lexical representation of 325N/A * An int value represented byte the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value. 325N/A * Converts the string argument into a long value. 325N/A * @param lexicalXSDLong 325N/A * A string containing lexical representation of 325N/A * A long value represented by the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDLong</code> is not a valid string representation of a <code>long</code> value. 325N/A * Converts the string argument into a short value. 325N/A * @param lexicalXSDShort 325N/A * A string containing lexical representation of 325N/A * A short value represented by the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDShort</code> is not a valid string representation of a <code>short</code> value. 325N/A * Converts the string argument into a BigDecimal value. 325N/A * @param lexicalXSDDecimal 325N/A * A string containing lexical representation of 325N/A * A BigDecimal value represented by the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDDecimal</code> is not a valid string representation of {@link java.math.BigDecimal}. 325N/A * Converts the string argument into a float value. 325N/A * @param lexicalXSDFloat 325N/A * A string containing lexical representation of 325N/A * A float value represented by the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDFloat</code> is not a valid string representation of a <code>float</code> value. 325N/A * Converts the string argument into a double value. 325N/A * @param lexicalXSDDouble 325N/A * A string containing lexical representation of 325N/A * A double value represented by the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDDouble</code> is not a valid string representation of a <code>double</code> value. 325N/A * Converts the string argument into a boolean value. 325N/A * @param lexicalXSDBoolean 325N/A * A string containing lexical representation of 325N/A * A boolean value represented by the string argument. 325N/A * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean. 325N/A * Converts the string argument into a byte value. 325N/A * @param lexicalXSDByte 325N/A * A string containing lexical representation of 325N/A * A byte value represented by the string argument. 325N/A * @throws NumberFormatException <code>lexicalXSDByte</code> does not contain a parseable byte. 325N/A * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte. 325N/A * Converts the string argument into a QName value. 325N/A * String parameter <tt>lexicalXSDQname</tt> must conform to lexical value space specifed at 325N/A * @param lexicalXSDQName 325N/A * A string containing lexical representation of xsd:QName. 325N/A * A namespace context for interpreting a prefix within a QName. 325N/A * A QName value represented by the string argument. 325N/A * @throws IllegalArgumentException if string parameter does not conform to XML Schema Part 2 specification or 325N/A * if namespace prefix of <tt>lexicalXSDQname</tt> is not bound to a URI in NamespaceContext <tt>nsc</tt>. 325N/A * Converts the string argument into a Calendar value. 325N/A * @param lexicalXSDDateTime 325N/A * A string containing lexical representation of 325N/A * A Calendar object represented by the string argument. 325N/A * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime. 325N/A * Converts the string argument into an array of bytes. 325N/A * @param lexicalXSDBase64Binary 325N/A * A string containing lexical representation 325N/A * An array of bytes represented by the string argument. 325N/A * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary 325N/A * Converts the string argument into an array of bytes. 325N/A * @param lexicalXSDHexBinary 325N/A * A string containing lexical representation of 325N/A * An array of bytes represented by the string argument. 325N/A * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary. 325N/A * Converts the string argument into a long value. 325N/A * @param lexicalXSDUnsignedInt 325N/A * A string containing lexical representation 325N/A * A long value represented by the string argument. 325N/A * @throws NumberFormatException if string parameter can not be parsed into a <tt>long</tt> value. 325N/A * Converts the string argument into an int value. 325N/A * @param lexicalXSDUnsignedShort 325N/A * A string containing lexical 325N/A * representation of xsd:unsignedShort. 325N/A * An int value represented by the string argument. 325N/A * @throws NumberFormatException if string parameter can not be parsed into an <tt>int</tt> value. 325N/A * Converts the string argument into a Calendar value. 325N/A * @param lexicalXSDTime 325N/A * A string containing lexical representation of 325N/A * A Calendar value represented by the string argument. 325N/A * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time. 325N/A * Converts the string argument into a Calendar value. 325N/A * @param lexicalXSDDate 325N/A * A string containing lexical representation of 325N/A * A Calendar value represented by the string argument. 325N/A * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date. 325N/A * Return a string containing the lexical representation of the 325N/A * @param lexicalXSDAnySimpleType 325N/A * A string containing lexical 325N/A * representation of the simple type. 325N/A * A string containing the lexical representation of the 325N/A * Converts the string argument into a string. 325N/A * A string containing a lexical representation of xsd:string 325N/A * Converts a BigInteger value into a string. 325N/A * A string containing a lexical representation of xsd:integer 325N/A * @throws IllegalArgumentException <tt>val</tt> is null. 325N/A * Converts an int value into a string. 325N/A * A string containing a lexical representation of xsd:int 325N/A * Converts a long value into a string. 325N/A * A string containing a lexical representation of xsd:long 325N/A * Converts a short value into a string. 325N/A * A string containing a lexical representation of xsd:short 325N/A * Converts a BigDecimal value into a string. 325N/A * A string containing a lexical representation of xsd:decimal 325N/A * @throws IllegalArgumentException <tt>val</tt> is null. 325N/A * Converts a float value into a string. 325N/A * A string containing a lexical representation of xsd:float 325N/A * Converts a double value into a string. 325N/A * A string containing a lexical representation of xsd:double 325N/A * Converts a boolean value into a string. 325N/A * A string containing a lexical representation of xsd:boolean 325N/A * Converts a byte value into a string. 325N/A * A string containing a lexical representation of xsd:byte 325N/A * Converts a QName instance into a string. 325N/A * A namespace context for interpreting a prefix within a QName. 325N/A * A string containing a lexical representation of QName 325N/A * @throws IllegalArgumentException if <tt>val</tt> is null or 325N/A * if <tt>nsc</tt> is non-null or <tt>nsc.getPrefix(nsprefixFromVal)</tt> is null. 325N/A * Converts a Calendar value into a string. 325N/A * A string containing a lexical representation of xsd:dateTime 325N/A * @throws IllegalArgumentException if <tt>val</tt> is null. 325N/A * Converts an array of bytes into a string. 325N/A * A string containing a lexical representation of xsd:base64Binary 325N/A * @throws IllegalArgumentException if <tt>val</tt> is null. 325N/A * Converts an array of bytes into a string. 325N/A * A string containing a lexical representation of xsd:hexBinary 325N/A * @throws IllegalArgumentException if <tt>val</tt> is null. 325N/A * Converts a long value into a string. 325N/A * A string containing a lexical representation of xsd:unsignedInt 325N/A * Converts an int value into a string. 325N/A * A string containing a lexical representation of xsd:unsignedShort 325N/A * Converts a Calendar value into a string. 325N/A * A string containing a lexical representation of xsd:time 325N/A * @throws IllegalArgumentException if <tt>val</tt> is null. 325N/A * Converts a Calendar value into a string. 325N/A * A string containing a lexical representation of xsd:date 325N/A * @throws IllegalArgumentException if <tt>val</tt> is null. 325N/A * Converts a string value into a string. 325N/A * A string containing a lexical representation of xsd:AnySimpleType