/*

 * Copyright (c) 2003, 2013, 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;

/**

 * <p>

 * The DatatypeConverterInterface is for JAXB provider use only. A

 * JAXB provider must supply a class that implements this interface.

 * JAXB Providers are required to call the

 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)

 * DatatypeConverter.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.  Calling this api repeatedly will have no effect - the

 * DatatypeConverter instance passed into the first invocation is the one that

 * will be used from then on.

 * </p>

 *

 * <p>

 * This interface defines the parse and print methods. There is one

 * parse and print method for each XML schema datatype specified in the

 * the default binding Table 5-1 in the JAXB specification.

 * </p>

 *

 * <p>

 * The parse and print methods defined here are invoked by the static parse

 * and print methods defined in the {@link DatatypeConverter DatatypeConverter}

 * class.

 * </p>

 *

 * <p>

 * A parse method for a XML schema datatype must be capable of converting any

 * lexical representation of the XML schema datatype ( specified by the

 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes

 * specification</a> into a value in the value space of 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>

 *

 * <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>

 *

 * The prefix xsd: is used to refer to XML schema datatypes

 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes

 * specification.</a>

 *

 * <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 DatatypeConverter

 * @see ParseConversionEvent

 * @see PrintConversionEvent

 * @since 1.6, JAXB 1.0

 */

public interface DatatypeConverterInterface {

    /**

     * <p>

     * Convert the string argument into a string.

     * @param lexicalXSDString

     *     A lexical representation of the XML Schema datatype xsd:string

     * @return

     *     A string that is the same as the input string.

     */

    public String parseString( String 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 java.math.BigInteger parseInteger( String lexicalXSDInteger );

    /**

     * <p>

     * Convert the string argument into an int value.

     * @param lexicalXSDInt

     *     A string containing a lexical representation of

     *     xsd:int.

     * @return

     *     An int value represented byte the string argument.

     * @throws NumberFormatException <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value.

     */

    public int parseInt( String 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 long parseLong( String 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 short parseShort( String 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 java.math.BigDecimal parseDecimal( String 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 float parseFloat( String 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 double parseDouble( String 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 boolean parseBoolean( String 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 NumberFormatException <code>lexicalXSDByte</code> does not contain a parseable byte.

     * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.

     */

    public byte parseByte( String lexicalXSDByte );

    /**

     * <p>

     * Converts the string argument into a QName 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 javax.xml.namespace.QName parseQName( String lexicalXSDQName,

                                             javax.xml.namespace.NamespaceContext 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 java.util.Calendar parseDateTime( String 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 byte[] parseBase64Binary( String 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 byte[] parseHexBinary( String 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 <tt>long</tt> value.

     */

    public long parseUnsignedInt( String 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 <tt>int</tt> value.

     */

    public int parseUnsignedShort( String 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 java.util.Calendar parseTime( String 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 java.util.Calendar parseDate( String 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 String parseAnySimpleType( String lexicalXSDAnySimpleType );

    /**

     * <p>

     * Converts the string argument into a string.

     * @param val

     *     A string value.

     * @return

     *     A string containing a lexical representation of xsd:string

     */

    public String printString( String 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 <tt>val</tt> is null.

     */

    public String printInteger( java.math.BigInteger 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 String printInt( int 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 String printLong( long 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 String printShort( short 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 <tt>val</tt> is null.

     */

    public String printDecimal( java.math.BigDecimal 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 String printFloat( float 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 String printDouble( double 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 String printBoolean( boolean 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 String printByte( byte 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 <tt>val</tt> is null or

     * if <tt>nsc</tt> is non-null or <tt>nsc.getPrefix(nsprefixFromVal)</tt> is null.

     */

    public String printQName( javax.xml.namespace.QName val,

                              javax.xml.namespace.NamespaceContext 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 String printDateTime( java.util.Calendar 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 <tt>val</tt> is null.

     */

    public String printBase64Binary( byte[] 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 <tt>val</tt> is null.

     */

    public String printHexBinary( byte[] 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 String printUnsignedInt( long 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 String printUnsignedShort( int 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 <tt>val</tt> is null.

     */

    public String printTime( java.util.Calendar 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 <tt>val</tt> is null.

     */

    public String printDate( java.util.Calendar 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 String printAnySimpleType( String val );

}