javax.xml.bind.DatatypeConverterInterface Maven / Gradle / Ivy
/*
* 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;
/**
*
* 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.
*
*
* 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.
*
*
* The parse and print methods defined here are invoked by the static parse
* and print methods defined in the {@link DatatypeConverter DatatypeConverter}
* class.
*
*
* A parse method for a XML schema datatype must be capable of converting any
* lexical representation of the XML schema datatype ( specified by the
* XML Schema Part2: Datatypes
* specification 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.
*
*
* 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.
*
*
* The prefix xsd: is used to refer to XML schema datatypes
* XML Schema Part2: Datatypes
* specification.
*
* @author
* - Sekhar Vajjhala, Sun Microsystems, Inc.
* - Joe Fialli, Sun Microsystems Inc.
* - Kohsuke Kawaguchi, Sun Microsystems, Inc.
* - Ryan Shoemaker,Sun Microsystems Inc.
*
* @see DatatypeConverter
* @see ParseConversionEvent
* @see PrintConversionEvent
* @since 1.6, JAXB 1.0
*/
public interface DatatypeConverterInterface {
/**
* 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 );
/**
* 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} is not a valid string representation of a {@link java.math.BigInteger} value.
*/
public java.math.BigInteger parseInteger( String lexicalXSDInteger );
/**
* 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} is not a valid string representation of an {@code int} value.
*/
public int parseInt( String 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 {@code lexicalXSDLong} is not a valid string representation of a {@code long} value.
*/
public long parseLong( String 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 {@code lexicalXSDShort} is not a valid string representation of a {@code short} value.
*/
public short parseShort( String 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 {@code lexicalXSDDecimal} is not a valid string representation of {@link java.math.BigDecimal}.
*/
public java.math.BigDecimal parseDecimal( String 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 {@code lexicalXSDFloat} is not a valid string representation of a {@code float} value.
*/
public float parseFloat( String 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 {@code lexicalXSDDouble} is not a valid string representation of a {@code double} value.
*/
public double parseDouble( String 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 boolean parseBoolean( String 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 NumberFormatException {@code lexicalXSDByte} 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 );
/**
* Converts the string argument into a QName 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 javax.xml.namespace.QName parseQName( String lexicalXSDQName,
javax.xml.namespace.NamespaceContext 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 java.util.Calendar parseDateTime( String 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 byte[] parseBase64Binary( String 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 byte[] parseHexBinary( String 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 long parseUnsignedInt( String 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 int parseUnsignedShort( String 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 java.util.Calendar parseTime( String 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 java.util.Calendar parseDate( String 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 String parseAnySimpleType( String lexicalXSDAnySimpleType );
/**
* 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 );
/**
* 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 String printInteger( java.math.BigInteger val );
/**
* 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 );
/**
* 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 );
/**
* 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 );
/**
* 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 String printDecimal( java.math.BigDecimal val );
/**
* 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 );
/**
* 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 );
/**
* 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 );
/**
* 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 );
/**
* 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 String printQName( javax.xml.namespace.QName val,
javax.xml.namespace.NamespaceContext 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 String printDateTime( java.util.Calendar 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 String printBase64Binary( byte[] 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 String printHexBinary( byte[] val );
/**
* 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 );
/**
* 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 );
/**
* 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 String printTime( java.util.Calendar 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 String printDate( java.util.Calendar val );
/**
* 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 );
}