001 /* 002 * $Id: DatatypeConverter.java,v 1.3 2002/12/19 19:23:32 kk122374 Exp $ 003 * 004 * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved. 005 * 006 * This software is the proprietary information of Sun Microsystems, Inc. 007 * Use is subject to license terms. 008 * 009 */ 010 011 package javax.xml.bind; 012 013 import javax.xml.namespace.NamespaceContext; 014 015 /** 016 * <p> 017 * The javaType binding declaration can be used to customize the binding of 018 * an XML schema datatype to a Java datatype. Customizations can involve 019 * writing a parse and print method for parsing and printing lexical 020 * representations of a XML schema datatype respectively. However, writing 021 * parse and print methods requires knowledge of the lexical representations ( 022 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes 023 * specification </a>) and hence may be difficult to write. 024 * </p> 025 * <p> 026 * This class makes it easier to write parse and print methods. It defines 027 * static parse and print methods that provide access to a JAXB provider's 028 * implementation of parse and print methods. These methods are invoked by 029 * custom parse and print methods. For example, the binding of xsd:dateTime 030 * to a long can be customized using parse and print methods as follows: 031 * <blockquote> 032 * <pre> 033 * // Customized parse method 034 * public long myParseCal( String dateTimeString ) { 035 * java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString); 036 * long longval = convert_calendar_to_long(cal); //application specific 037 * return longval; 038 * } 039 * 040 * // Customized print method 041 * public String myPrintCal( Long longval ) { 042 * java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific 043 * String dateTimeString = DatatypeConverter.printDateTime(cal); 044 * return dateTimeString; 045 * } 046 * </pre> 047 * </blockquote> 048 * <p> 049 * There is a static parse and print method corresponding to each parse and 050 * print method respectively in the {@link DatatypeConverterInterface 051 * DatatypeConverterInterface}. 052 * <p> 053 * The static methods defined in the class can also be used to specify 054 * a parse or a print method in a javaType binding declaration. 055 * </p> 056 * <p> 057 * JAXB Providers are required to call the 058 * {@link #setDatatypeConverter(DatatypeConverterInterface) 059 * setDatatypeConverter} api at some point before the first marshal or unmarshal 060 * operation (perhaps during the call to JAXBContext.newInstance). This step is 061 * necessary to configure the converter that should be used to perform the 062 * print and parse functionality. 063 * </p> 064 * 065 * @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> 066 * @version $Revision: 1.3 $ 067 * @see DatatypeConverterInterface 068 * @see ParseConversionEvent 069 * @see PrintConversionEvent 070 * @since JAXB1.0 071 */ 072 073 final public class DatatypeConverter { 074 075 // delegate to this instance of DatatypeConverter 076 private static DatatypeConverterInterface theConverter = null; 077 078 private DatatypeConverter() { 079 // private constructor 080 } 081 082 /** 083 * This method is for JAXB provider use only. 084 * <p> 085 * JAXB Providers are required to call this method at some point before 086 * allowing any of the JAXB client marshal or unmarshal operations to 087 * occur. This is necessary to configure the datatype converter that 088 * should be used to perform the print and parse conversions. 089 * 090 * <p> 091 * Calling this api repeatedly will have no effect - the 092 * DatatypeConverterInterface instance passed into the first invocation is 093 * the one that will be used from then on. 094 * 095 * @param converter an instance of a class that implements the 096 * DatatypeConverterInterface class - this parameter must not be null. 097 * @throws IllegalArgumentException if the parameter is null 098 */ 099 public static void setDatatypeConverter( DatatypeConverterInterface converter ) { 100 if( converter == null ) { 101 throw new IllegalArgumentException( 102 Messages.format( Messages.CONVERTER_MUST_NOT_BE_NULL ) ); 103 } else if( theConverter == null ) { 104 theConverter = converter; 105 } 106 } 107 108 /** 109 * <p> 110 * Convert the lexical XSD string argument into a String value. 111 * @param 112 * lexicalXSDString A string containing a lexical representation of 113 * xsd:string. 114 * @return 115 * A String value represented by the string argument. 116 */ 117 public static String parseString( String lexicalXSDString ) { 118 return theConverter.parseString( lexicalXSDString ); 119 } 120 121 /** 122 * <p> 123 * Convert the string argument into a BigInteger value. 124 * @param 125 * lexicalXSDInteger A string containing a lexical representation of 126 * xsd:integer. 127 * @return 128 * A BigInteger value represented by the string argument. 129 */ 130 public static java.math.BigInteger parseInteger( String lexicalXSDInteger ) { 131 return theConverter.parseInteger( lexicalXSDInteger ); 132 } 133 134 /** 135 * <p> 136 * Convert the string argument into an int value. 137 * @param 138 * lexicalXSDInt A string containing a lexical representation of 139 * xsd:int. 140 * @return 141 * A int value represented by the string argument. 142 */ 143 public static int parseInt( String lexicalXSDInt ) { 144 return theConverter.parseInt( lexicalXSDInt ); 145 } 146 147 /** 148 * <p> 149 * Converts the string argument into a long value. 150 * @param 151 * lexicalXSDLong A string containing lexical representation of 152 * xsd:long. 153 * @return 154 * A long value represented by the string argument. 155 */ 156 public static long parseLong( String lexicalXSLong ) { 157 return theConverter.parseLong( lexicalXSLong ); 158 } 159 160 /** 161 * <p> 162 * Converts the string argument into a short value. 163 * @param 164 * lexicalXSDShort A string containing lexical representation of 165 * xsd:short. 166 * @return 167 * A short value represented by the string argument. 168 */ 169 public static short parseShort( String lexicalXSShort ) { 170 return theConverter.parseShort( lexicalXSShort ); 171 } 172 173 /** 174 * <p> 175 * Converts the string argument into a BigDecimal value. 176 * @param 177 * lexicalXSDDecimal A string containing lexical representation of 178 * xsd:decimal. 179 * @return 180 * A BigDecimal value represented by the string argument. 181 */ 182 public static java.math.BigDecimal parseDecimal( String lexicalXSDDecimal ) { 183 return theConverter.parseDecimal( lexicalXSDDecimal ); 184 } 185 186 /** 187 * <p> 188 * Converts the string argument into a float value. 189 * @param 190 * lexicalXSDFloat A string containing lexical representation of 191 * xsd:float. 192 * @return 193 * A float value represented by the string argument. 194 */ 195 public static float parseFloat( String lexicalXSDFloat ) { 196 return theConverter.parseFloat( lexicalXSDFloat ); 197 } 198 199 /** 200 * <p> 201 * Converts the string argument into a double value. 202 * @param 203 * lexicalXSDDouble A string containing lexical representation of 204 * xsd:double. 205 * @return 206 * A double value represented by the string argument. 207 */ 208 public static double parseDouble( String lexicalXSDDouble ) { 209 return theConverter.parseDouble( lexicalXSDDouble ); 210 } 211 212 /** 213 * <p> 214 * Converts the string argument into a boolean value. 215 * @param 216 * lexicalXSDBoolean A string containing lexical representation of 217 * xsd:boolean. 218 * @return 219 * A boolean value represented by the string argument. 220 */ 221 public static boolean parseBoolean( String lexicalXSDBoolean ) { 222 return theConverter.parseBoolean( lexicalXSDBoolean ); 223 } 224 225 /** 226 * <p> 227 * Converts the string argument into a byte value. 228 * @param 229 * lexicalXSDByte A string containing lexical representation of 230 * xsd:byte. 231 * @return 232 * A byte value represented by the string argument. 233 */ 234 public static byte parseByte( String lexicalXSDByte ) { 235 return theConverter.parseByte( lexicalXSDByte ); 236 } 237 238 /** 239 * <p> 240 * Converts the string argument into a byte value. 241 * @param lexicalXSDQName 242 * A string containing lexical representation of xsd:QName. 243 * @param nsc 244 * A namespace context for interpreting a prefix within a QName. 245 * @return 246 * A QName value represented by the string argument. 247 */ 248 public static javax.xml.namespace.QName parseQName( String lexicalXSDQName, 249 NamespaceContext nsc) { 250 return theConverter.parseQName( lexicalXSDQName, nsc ); 251 } 252 253 /** 254 * <p> 255 * Converts the string argument into a Calendar value. 256 * @param 257 * lexicalXSDDateTime A string containing lexical representation of 258 * xsd:datetime. 259 * @return 260 * A Calendar object represented by the string argument. 261 */ 262 public static java.util.Calendar parseDateTime( String lexicalXSDDateTime ) { 263 return theConverter.parseDateTime( lexicalXSDDateTime ); 264 } 265 266 /** 267 * <p> 268 * Converts the string argument into an array of bytes. 269 * @param 270 * lexicalXSDBase64Binary A string containing lexical representation 271 * of xsd:base64Binary. 272 * @return 273 * An array of bytes represented by the string argument. 274 */ 275 public static byte[] parseBase64Binary( String lexicalXSDBase64Binary ) { 276 return theConverter.parseBase64Binary( lexicalXSDBase64Binary ); 277 } 278 279 /** 280 * <p> 281 * Converts the string argument into an array of bytes. 282 * @param 283 * lexicalXSDHexBinary A string containing lexical representation of 284 * xsd:hexBinary. 285 * @return 286 * An array of bytes represented by the string argument. 287 */ 288 public static byte[] parseHexBinary( String lexicalXSDHexBinary ) { 289 return theConverter.parseHexBinary( lexicalXSDHexBinary ); 290 } 291 292 /** 293 * <p> 294 * Converts the string argument into a long value. 295 * @param 296 * lexicalXSDUnsignedInt A string containing lexical representation 297 * of xsd:unsignedInt. 298 * @return 299 * A long value represented by the string argument. 300 */ 301 public static long parseUnsignedInt( String lexicalXSDUnsignedInt ) { 302 return theConverter.parseUnsignedInt( lexicalXSDUnsignedInt ); 303 } 304 305 /** 306 * <p> 307 * Converts the string argument into an int value. 308 * @param 309 * lexicalXSDUnsignedShort A string containing lexical 310 * representation of xsd:unsignedShort. 311 * @return 312 * An int value represented by the string argument. 313 */ 314 public static int parseUnsignedShort( String lexicalXSDUnsignedShort ) { 315 return theConverter.parseUnsignedShort( lexicalXSDUnsignedShort ); 316 } 317 318 /** 319 * <p> 320 * Converts the string argument into a Calendar value. 321 * @param 322 * lexicalXSDTime A string containing lexical representation of 323 * xsd:time. 324 * @return 325 * A Calendar value represented by the string argument. 326 */ 327 public static java.util.Calendar parseTime( String lexicalXSDTime ) { 328 return theConverter.parseTime( lexicalXSDTime ); 329 } 330 /** 331 * <p> 332 * Converts the string argument into a Calendar value. 333 * @param 334 * lexicalXSDDate A string containing lexical representation of 335 * xsd:Date. 336 * @return 337 * A Calendar value represented by the string argument. 338 */ 339 public static java.util.Calendar parseDate( String lexicalXSDDate ) { 340 return theConverter.parseDate( lexicalXSDDate ); 341 } 342 343 /** 344 * <p> 345 * Return a string containing the lexical representation of the 346 * simple type. 347 * @param 348 * lexicalXSDAnySimpleType A string containing lexical 349 * representation of the simple type. 350 * @return 351 * A string containing the lexical representation of the 352 * simple type. 353 */ 354 public static String parseAnySimpleType( String lexicalAnySimpleType ) { 355 return theConverter.parseAnySimpleType( lexicalAnySimpleType ); 356 } 357 /** 358 * <p> 359 * Converts the string argument into a string. 360 * @param val 361 * A string value. 362 * @return 363 * A string containing a lexical representation of xsd:string. 364 */ 365 // also indicate the print methods produce a lexical 366 // representation for given Java datatypes. 367 368 public static String printString( String val ) { 369 return theConverter.printString( val ); 370 } 371 372 /** 373 * <p> 374 * Converts a BigInteger value into a string. 375 * @param val 376 * A BigInteger value 377 * @return 378 * A string containing a lexical representation of xsd:integer 379 */ 380 public static String printInteger( java.math.BigInteger val ) { 381 return theConverter.printInteger( val ); 382 } 383 384 /** 385 * <p> 386 * Converts an int value into a string. 387 * @param val 388 * An int value 389 * @return 390 * A string containing a lexical representation of xsd:int 391 */ 392 public static String printInt( int val ) { 393 return theConverter.printInt( val ); 394 } 395 396 /** 397 * <p> 398 * Converts A long value into a string. 399 * @param val 400 * A long value 401 * @return 402 * A string containing a lexical representation of xsd:long 403 */ 404 public static String printLong( long val ) { 405 return theConverter.printLong( val ); 406 } 407 408 /** 409 * <p> 410 * Converts a short value into a string. 411 * @param val 412 * A short value 413 * @return 414 * A string containing a lexical representation of xsd:short 415 */ 416 public static String printShort( short val ) { 417 return theConverter.printShort( val ); 418 } 419 420 /** 421 * <p> 422 * Converts a BigDecimal value into a string. 423 * @param val 424 * A BigDecimal value 425 * @return 426 * A string containing a lexical representation of xsd:decimal 427 */ 428 public static String printDecimal( java.math.BigDecimal val ) { 429 return theConverter.printDecimal( val ); 430 } 431 432 /** 433 * <p> 434 * Converts a float value into a string. 435 * @param val 436 * A float value 437 * @return 438 * A string containing a lexical representation of xsd:float 439 */ 440 public static String printFloat( float val ) { 441 return theConverter.printFloat( val ); 442 } 443 444 /** 445 * <p> 446 * Converts a double value into a string. 447 * @param val 448 * A double value 449 * @return 450 * A string containing a lexical representation of xsd:double 451 */ 452 public static String printDouble( double val ) { 453 return theConverter.printDouble( val ); 454 } 455 456 /** 457 * <p> 458 * Converts a boolean value into a string. 459 * @param val 460 * A boolean value 461 * @return 462 * A string containing a lexical representation of xsd:boolean 463 */ 464 public static String printBoolean( boolean val ) { 465 return theConverter.printBoolean( val ); 466 } 467 468 /** 469 * <p> 470 * Converts a byte value into a string. 471 * @param val 472 * A byte value 473 * @return 474 * A string containing a lexical representation of xsd:byte 475 */ 476 public static String printByte( byte val ) { 477 return theConverter.printByte( val ); 478 } 479 480 /** 481 * <p> 482 * Converts a QName instance into a string. 483 * @param val 484 * A QName value 485 * @param nsc 486 * A namespace context for interpreting a prefix within a QName. 487 * @return 488 * A string containing a lexical representation of QName 489 */ 490 public static String printQName( javax.xml.namespace.QName val, 491 NamespaceContext nsc ) { 492 return theConverter.printQName( val, nsc ); 493 } 494 495 /** 496 * <p> 497 * Converts a Calendar value into a string. 498 * @param val 499 * A Calendar value 500 * @return 501 * A string containing a lexical representation of xsd:dateTime 502 */ 503 public static String printDateTime( java.util.Calendar val ) { 504 return theConverter.printDateTime( val ); 505 } 506 507 /** 508 * <p> 509 * Converts an array of bytes into a string. 510 * @param val 511 * An array of bytes 512 * @return 513 * A string containing a lexical representation of xsd:base64Binary 514 */ 515 public static String printBase64Binary( byte[] val ) { 516 return theConverter.printBase64Binary( val ); 517 } 518 519 /** 520 * <p> 521 * Converts an array of bytes into a string. 522 * @param val 523 * An array of bytes 524 * @return 525 * A string containing a lexical representation of xsd:hexBinary 526 */ 527 public static String printHexBinary( byte[] val ) { 528 return theConverter.printHexBinary( val ); 529 } 530 531 /** 532 * <p> 533 * Converts a long value into a string. 534 * @param val 535 * A long value 536 * @return 537 * A string containing a lexical representation of xsd:unsignedInt 538 */ 539 public static String printUnsignedInt( long val ) { 540 return theConverter.printUnsignedInt( val ); 541 } 542 543 /** 544 * <p> 545 * Converts an int value into a string. 546 * @param val 547 * An int value 548 * @return 549 * A string containing a lexical representation of xsd:unsignedShort 550 */ 551 public static String printUnsignedShort( int val ) { 552 return theConverter.printUnsignedShort( val ); 553 } 554 555 /** 556 * <p> 557 * Converts a Calendar value into a string. 558 * @param val 559 * A Calendar value 560 * @return 561 * A string containing a lexical representation of xsd:time 562 */ 563 public static String printTime( java.util.Calendar val ) { 564 return theConverter.printTime( val ); 565 } 566 567 /** 568 * <p> 569 * Converts a Calendar value into a string. 570 * @param val 571 * A Calendar value 572 * @return 573 * A string containing a lexical representation of xsd:date 574 */ 575 public static String printDate( java.util.Calendar val ) { 576 return theConverter.printDate( val ); 577 } 578 579 /** 580 * <p> 581 * Converts a string value into a string. 582 * @param val 583 * A string value 584 * @return 585 * A string containing a lexical representation of xsd:AnySimpleType 586 */ 587 public static String printAnySimpleType( String val ) { 588 return theConverter.printAnySimpleType( val ); 589 } 590 }