1 /*
   2  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.bind;
  27 
  28 /**
  29  * <p>
  30  * The DatatypeConverterInterface is for JAXB provider use only. A
  31  * JAXB provider must supply a class that implements this interface.
  32  * JAXB Providers are required to call the
  33  * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
  34  * DatatypeConverter.setDatatypeConverter} api at
  35  * some point before the first marshal or unmarshal operation (perhaps during
  36  * the call to JAXBContext.newInstance).  This step is necessary to configure
  37  * the converter that should be used to perform the print and parse
  38  * functionality.  Calling this api repeatedly will have no effect - the
  39  * DatatypeConverter instance passed into the first invocation is the one that
  40  * will be used from then on.
  41  *
  42  * <p>
  43  * This interface defines the parse and print methods. There is one
  44  * parse and print method for each XML schema datatype specified in the
  45  * the default binding Table 5-1 in the JAXB specification.
  46  *
  47  * <p>
  48  * The parse and print methods defined here are invoked by the static parse
  49  * and print methods defined in the {@link DatatypeConverter DatatypeConverter}
  50  * class.
  51  *
  52  * <p>
  53  * A parse method for a XML schema datatype must be capable of converting any
  54  * lexical representation of the XML schema datatype ( specified by the
  55  * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
  56  * specification</a> into a value in the value space of the XML schema datatype.
  57  * If an error is encountered during conversion, then an IllegalArgumentException
  58  * or a subclass of IllegalArgumentException must be thrown by the method.
  59  *
  60  * <p>
  61  * A print method for a XML schema datatype can output any lexical
  62  * representation that is valid with respect to the XML schema datatype.
  63  * If an error is encountered during conversion, then an IllegalArgumentException,
  64  * or a subclass of IllegalArgumentException must be thrown by the method.
  65  *
  66  * <p>
  67  * The prefix xsd: is used to refer to XML schema datatypes
  68  * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
  69  * specification.</a>
  70  *
  71  * @author <ul>
  72  *         <li>Sekhar Vajjhala, Sun Microsystems, Inc.</li>
  73  *         <li>Joe Fialli, Sun Microsystems Inc.</li>
  74  *         <li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li>
  75  *         <li>Ryan Shoemaker,Sun Microsystems Inc.</li>
  76  *         </ul>
  77  * @see DatatypeConverter
  78  * @see ParseConversionEvent
  79  * @see PrintConversionEvent
  80  * @since 1.6, JAXB 1.0
  81  */
  82 
  83 public interface DatatypeConverterInterface {
  84     /**
  85      * Convert the string argument into a string.
  86      * @param lexicalXSDString
  87      *     A lexical representation of the XML Schema datatype xsd:string
  88      * @return
  89      *     A string that is the same as the input string.
  90      */
  91     public String parseString( String lexicalXSDString );
  92 
  93     /**
  94      * Convert the string argument into a BigInteger value.
  95      * @param lexicalXSDInteger
  96      *     A string containing a lexical representation of
  97      *     xsd:integer.
  98      * @return
  99      *     A BigInteger value represented by the string argument.
 100      * @throws NumberFormatException {@code lexicalXSDInteger} is not a valid string representation of a {@link java.math.BigInteger} value.
 101      */
 102     public java.math.BigInteger parseInteger( String lexicalXSDInteger );
 103 
 104     /**
 105      * Convert the string argument into an int value.
 106      * @param lexicalXSDInt
 107      *     A string containing a lexical representation of
 108      *     xsd:int.
 109      * @return
 110      *     An int value represented byte the string argument.
 111      * @throws NumberFormatException {@code lexicalXSDInt} is not a valid string representation of an {@code int} value.
 112      */
 113     public int parseInt( String lexicalXSDInt );
 114 
 115     /**
 116      * Converts the string argument into a long value.
 117      * @param lexicalXSDLong
 118      *     A string containing lexical representation of
 119      *     xsd:long.
 120      * @return
 121      *     A long value represented by the string argument.
 122      * @throws NumberFormatException {@code lexicalXSDLong} is not a valid string representation of a {@code long} value.
 123      */
 124     public long parseLong( String lexicalXSDLong );
 125 
 126     /**
 127      * Converts the string argument into a short value.
 128      * @param lexicalXSDShort
 129      *     A string containing lexical representation of
 130      *     xsd:short.
 131      * @return
 132      *     A short value represented by the string argument.
 133      * @throws NumberFormatException {@code lexicalXSDShort} is not a valid string representation of a {@code short} value.
 134      */
 135     public short parseShort( String lexicalXSDShort );
 136 
 137     /**
 138      * Converts the string argument into a BigDecimal value.
 139      * @param lexicalXSDDecimal
 140      *     A string containing lexical representation of
 141      *     xsd:decimal.
 142      * @return
 143      *     A BigDecimal value represented by the string argument.
 144      * @throws NumberFormatException {@code lexicalXSDDecimal} is not a valid string representation of {@link java.math.BigDecimal}.
 145      */
 146     public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal );
 147 
 148     /**
 149      * Converts the string argument into a float value.
 150      * @param lexicalXSDFloat
 151      *     A string containing lexical representation of
 152      *     xsd:float.
 153      * @return
 154      *     A float value represented by the string argument.
 155      * @throws NumberFormatException {@code lexicalXSDFloat} is not a valid string representation of a {@code float} value.
 156      */
 157     public float parseFloat( String lexicalXSDFloat );
 158 
 159     /**
 160      * Converts the string argument into a double value.
 161      * @param lexicalXSDDouble
 162      *     A string containing lexical representation of
 163      *     xsd:double.
 164      * @return
 165      *     A double value represented by the string argument.
 166      * @throws NumberFormatException {@code lexicalXSDDouble} is not a valid string representation of a {@code double} value.
 167      */
 168     public double parseDouble( String lexicalXSDDouble );
 169 
 170     /**
 171      * Converts the string argument into a boolean value.
 172      * @param lexicalXSDBoolean
 173      *     A string containing lexical representation of
 174      *     xsd:boolean.
 175      * @return
 176      *     A boolean value represented by the string argument.
 177      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.
 178      */
 179     public boolean parseBoolean( String lexicalXSDBoolean );
 180 
 181     /**
 182      * Converts the string argument into a byte value.
 183      * @param lexicalXSDByte
 184      *     A string containing lexical representation of
 185      *     xsd:byte.
 186      * @return
 187      *     A byte value represented by the string argument.
 188      * @throws NumberFormatException {@code lexicalXSDByte} does not contain a parseable byte.
 189      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.
 190      */
 191     public byte parseByte( String lexicalXSDByte );
 192 
 193     /**
 194      * Converts the string argument into a QName value.
 195      *
 196      * <p>
 197      * String parameter <tt>lexicalXSDQname</tt> must conform to lexical value space specifed at
 198      * <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part 2:Datatypes specification:QNames</a>
 199      *
 200      * @param lexicalXSDQName
 201      *     A string containing lexical representation of xsd:QName.
 202      * @param nsc
 203      *     A namespace context for interpreting a prefix within a QName.
 204      * @return
 205      *     A QName value represented by the string argument.
 206      * @throws IllegalArgumentException  if string parameter does not conform to XML Schema Part 2 specification or
 207      *      if namespace prefix of <tt>lexicalXSDQname</tt> is not bound to a URI in NamespaceContext <tt>nsc</tt>.
 208      */
 209     public javax.xml.namespace.QName parseQName( String lexicalXSDQName,
 210                                              javax.xml.namespace.NamespaceContext nsc);
 211 
 212     /**
 213      * Converts the string argument into a Calendar value.
 214      * @param lexicalXSDDateTime
 215      *     A string containing lexical representation of
 216      *     xsd:datetime.
 217      * @return
 218      *     A Calendar object represented by the string argument.
 219      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.
 220      */
 221     public java.util.Calendar parseDateTime( String lexicalXSDDateTime );
 222 
 223     /**
 224      * Converts the string argument into an array of bytes.
 225      * @param lexicalXSDBase64Binary
 226      *     A string containing lexical representation
 227      *     of xsd:base64Binary.
 228      * @return
 229      *     An array of bytes represented by the string argument.
 230      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary
 231      */
 232     public byte[] parseBase64Binary( String lexicalXSDBase64Binary );
 233 
 234     /**
 235      * Converts the string argument into an array of bytes.
 236      * @param lexicalXSDHexBinary
 237      *     A string containing lexical representation of
 238      *     xsd:hexBinary.
 239      * @return
 240      *     An array of bytes represented by the string argument.
 241      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.
 242      */
 243     public byte[] parseHexBinary( String lexicalXSDHexBinary );
 244 
 245     /**
 246      * Converts the string argument into a long value.
 247      * @param lexicalXSDUnsignedInt
 248      *     A string containing lexical representation
 249      *     of xsd:unsignedInt.
 250      * @return
 251      *     A long value represented by the string argument.
 252      * @throws NumberFormatException if string parameter can not be parsed into a <tt>long</tt> value.
 253      */
 254     public long parseUnsignedInt( String lexicalXSDUnsignedInt );
 255 
 256     /**
 257      * Converts the string argument into an int value.
 258      * @param lexicalXSDUnsignedShort
 259      *     A string containing lexical
 260      *     representation of xsd:unsignedShort.
 261      * @return
 262      *     An int value represented by the string argument.
 263      * @throws NumberFormatException if string parameter can not be parsed into an <tt>int</tt> value.
 264      */
 265     public int parseUnsignedShort( String lexicalXSDUnsignedShort );
 266 
 267     /**
 268      * Converts the string argument into a Calendar value.
 269      * @param lexicalXSDTime
 270      *     A string containing lexical representation of
 271      *     xsd:Time.
 272      * @return
 273      *     A Calendar value represented by the string argument.
 274      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.
 275      */
 276     public java.util.Calendar parseTime( String lexicalXSDTime );
 277 
 278     /**
 279      * Converts the string argument into a Calendar value.
 280      * @param lexicalXSDDate
 281      *     A string containing lexical representation of
 282      *     xsd:Date.
 283      * @return
 284      *     A Calendar value represented by the string argument.
 285      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.
 286      */
 287     public java.util.Calendar parseDate( String lexicalXSDDate );
 288 
 289     /**
 290      * Return a string containing the lexical representation of the
 291      * simple type.
 292      * @param lexicalXSDAnySimpleType
 293      *     A string containing lexical
 294      *     representation of the simple type.
 295      * @return
 296      *     A string containing the lexical representation of the
 297      *     simple type.
 298      */
 299     public String parseAnySimpleType( String lexicalXSDAnySimpleType );
 300 
 301     /**
 302      * Converts the string argument into a string.
 303      * @param val
 304      *     A string value.
 305      * @return
 306      *     A string containing a lexical representation of xsd:string
 307      */
 308     public String printString( String val );
 309 
 310     /**
 311      * Converts a BigInteger value into a string.
 312      * @param val
 313      *     A BigInteger value
 314      * @return
 315      *     A string containing a lexical representation of xsd:integer
 316      * @throws IllegalArgumentException <tt>val</tt> is null.
 317      */
 318     public String printInteger( java.math.BigInteger val );
 319 
 320     /**
 321      * Converts an int value into a string.
 322      * @param val
 323      *     An int value
 324      * @return
 325      *     A string containing a lexical representation of xsd:int
 326      */
 327     public String printInt( int val );
 328 
 329 
 330     /**
 331      * Converts a long value into a string.
 332      * @param val
 333      *     A long value
 334      * @return
 335      *     A string containing a lexical representation of xsd:long
 336      */
 337     public String printLong( long val );
 338 
 339     /**
 340      * Converts a short value into a string.
 341      * @param val
 342      *     A short value
 343      * @return
 344      *     A string containing a lexical representation of xsd:short
 345      */
 346     public String printShort( short val );
 347 
 348     /**
 349      * Converts a BigDecimal value into a string.
 350      * @param val
 351      *     A BigDecimal value
 352      * @return
 353      *     A string containing a lexical representation of xsd:decimal
 354      * @throws IllegalArgumentException <tt>val</tt> is null.
 355      */
 356     public String printDecimal( java.math.BigDecimal val );
 357 
 358     /**
 359      * Converts a float value into a string.
 360      * @param val
 361      *     A float value
 362      * @return
 363      *     A string containing a lexical representation of xsd:float
 364      */
 365     public String printFloat( float val );
 366 
 367     /**
 368      * Converts a double value into a string.
 369      * @param val
 370      *     A double value
 371      * @return
 372      *     A string containing a lexical representation of xsd:double
 373      */
 374     public String printDouble( double val );
 375 
 376     /**
 377      * Converts a boolean value into a string.
 378      * @param val
 379      *     A boolean value
 380      * @return
 381      *     A string containing a lexical representation of xsd:boolean
 382      */
 383     public String printBoolean( boolean val );
 384 
 385     /**
 386      * Converts a byte value into a string.
 387      * @param val
 388      *     A byte value
 389      * @return
 390      *     A string containing a lexical representation of xsd:byte
 391      */
 392     public String printByte( byte val );
 393 
 394     /**
 395      * Converts a QName instance into a string.
 396      * @param val
 397      *     A QName value
 398      * @param nsc
 399      *     A namespace context for interpreting a prefix within a QName.
 400      * @return
 401      *     A string containing a lexical representation of QName
 402      * @throws IllegalArgumentException if <tt>val</tt> is null or
 403      * if <tt>nsc</tt> is non-null or <tt>nsc.getPrefix(nsprefixFromVal)</tt> is null.
 404      */
 405     public String printQName( javax.xml.namespace.QName val,
 406                               javax.xml.namespace.NamespaceContext nsc );
 407 
 408     /**
 409      * Converts a Calendar value into a string.
 410      * @param val
 411      *     A Calendar value
 412      * @return
 413      *     A string containing a lexical representation of xsd:dateTime
 414      * @throws IllegalArgumentException if <tt>val</tt> is null.
 415      */
 416     public String printDateTime( java.util.Calendar val );
 417 
 418     /**
 419      * Converts an array of bytes into a string.
 420      * @param val
 421      *     an array of bytes
 422      * @return
 423      *     A string containing a lexical representation of xsd:base64Binary
 424      * @throws IllegalArgumentException if <tt>val</tt> is null.
 425      */
 426     public String printBase64Binary( byte[] val );
 427 
 428     /**
 429      * Converts an array of bytes into a string.
 430      * @param val
 431      *     an array of bytes
 432      * @return
 433      *     A string containing a lexical representation of xsd:hexBinary
 434      * @throws IllegalArgumentException if <tt>val</tt> is null.
 435      */
 436     public String printHexBinary( byte[] val );
 437 
 438     /**
 439      * Converts a long value into a string.
 440      * @param val
 441      *     A long value
 442      * @return
 443      *     A string containing a lexical representation of xsd:unsignedInt
 444      */
 445     public String printUnsignedInt( long val );
 446 
 447     /**
 448      * Converts an int value into a string.
 449      * @param val
 450      *     An int value
 451      * @return
 452      *     A string containing a lexical representation of xsd:unsignedShort
 453      */
 454     public String printUnsignedShort( int val );
 455 
 456     /**
 457      * Converts a Calendar value into a string.
 458      * @param val
 459      *     A Calendar value
 460      * @return
 461      *     A string containing a lexical representation of xsd:time
 462      * @throws IllegalArgumentException if <tt>val</tt> is null.
 463      */
 464     public String printTime( java.util.Calendar val );
 465 
 466     /**
 467      * Converts a Calendar value into a string.
 468      * @param val
 469      *     A Calendar value
 470      * @return
 471      *     A string containing a lexical representation of xsd:date
 472      * @throws IllegalArgumentException if <tt>val</tt> is null.
 473      */
 474     public String printDate( java.util.Calendar val );
 475 
 476     /**
 477      * Converts a string value into a string.
 478      * @param val
 479      *     A string value
 480      * @return
 481      *     A string containing a lexical representation of xsd:AnySimpleType
 482      */
 483     public String printAnySimpleType( String val );
 484 }