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 }