001 /* 002 * $Id: DatatypeConverterInterface.java,v 1.1 2002/12/04 17:04:30 ryans 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 /** 014 * <p> 015 * The DatatypeConverterInterface is for JAXB provider use only. A 016 * JAXB provider must supply a class that implements this interface. 017 * JAXB Providers are required to call the 018 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) 019 * DatatypeConverter.setDatatypeConverter} api at 020 * some point before the first marshal or unmarshal operation (perhaps during 021 * the call to JAXBContext.newInstance). This step is necessary to configure 022 * the converter that should be used to perform the print and parse 023 * functionality. Calling this api repeatedly will have no effect - the 024 * DatatypeConverter instance passed into the first invocation is the one that 025 * will be used from then on. 026 * </p> 027 * 028 * <p> 029 * This interface defines the parse and print methods. There is one 030 * parse and print method for each XML schema datatype specified in the 031 * the default binding Table 5-1 in the JAXB specification. 032 * </p> 033 * 034 * <p> 035 * The parse and print methods defined here are invoked by the static parse 036 * and print methods defined in the {@link DatatypeConverter DatatypeConverter} 037 * class. 038 * </p> 039 * 040 * <p> 041 * A parse method for a XML schema datatype must be capable of converting any 042 * lexical representation of the XML schema datatype ( specified by the 043 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes 044 * specification</a> into a value in the value space of the XML schema datatype. 045 * If an error is encountered during conversion, then a ParseConversionEvent 046 * must be generated. 047 * </p> 048 * 049 * <p> 050 * A print method for a XML schema datatype can output any lexical 051 * representation that is valid with respect to the XML schema datatype. 052 * If an error is encountered during conversion, then a PrintConversionEvent 053 * must be generated. 054 * </p> 055 * 056 * The prefix xsd: is used to refer to XML schema datatypes 057 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes 058 * specification.</a> 059 * 060 * <p> 061 * @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> 062 * @version $Revision: 1.1 $ 063 * @see DatatypeConverter 064 * @see ParseConversionEvent 065 * @see PrintConversionEvent 066 * @since JAXB1.0 067 */ 068 069 public interface DatatypeConverterInterface { 070 /** 071 * <p> 072 * Convert the string argument into a string. 073 * @param lexicalXSDString 074 * A lexical representation of the XML Schema datatype xsd:string 075 * @return 076 * A string that is the same as the input string. 077 */ 078 public String parseString( String lexicalXSDString ); 079 080 /** 081 * <p> 082 * Convert the string argument into a BigInteger value. 083 * @param 084 * lexicalXSDInteger A string containing a lexical representation of 085 * xsd:integer. 086 * @return 087 * A BigInteger value represented by the string argument. 088 */ 089 public java.math.BigInteger parseInteger( String lexicalXSDInteger ); 090 091 /** 092 * <p> 093 * Convert the string argument into an int value. 094 * @param 095 * lexicalXSDInt A string containing a lexical representation of 096 * xsd:int. 097 * @return 098 * An int value represented byte the string argument. 099 */ 100 public int parseInt( String lexicalXSDInt ); 101 102 /** 103 * <p> 104 * Converts the string argument into a long value. 105 * @param 106 * lexicalXSDLong A string containing lexical representation of 107 * xsd:long. 108 * @return 109 * A long value represented by the string argument. 110 */ 111 public long parseLong( String lexicalXSLong ); 112 113 /** 114 * <p> 115 * Converts the string argument into a short value. 116 * @param 117 * lexicalXSDShort A string containing lexical representation of 118 * xsd:short. 119 * @return 120 * A short value represented by the string argument. 121 */ 122 public short parseShort( String lexicalXSDShort ); 123 124 /** 125 * <p> 126 * Converts the string argument into a BigDecimal value. 127 * @param 128 * lexicalXSDDecimal A string containing lexical representation of 129 * xsd:decimal. 130 * @return 131 * A BigDecimal value represented by the string argument. 132 */ 133 public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal ); 134 135 /** 136 * <p> 137 * Converts the string argument into a float value. 138 * @param 139 * lexicalXSDFloat A string containing lexical representation of 140 * xsd:float. 141 * @return 142 * A float value represented by the string argument. 143 */ 144 public float parseFloat( String lexicalXSDFloat ); 145 146 /** 147 * <p> 148 * Converts the string argument into a double value. 149 * @param 150 * lexicalXSDDouble A string containing lexical representation of 151 * xsd:double. 152 * @return 153 * A double value represented by the string argument. 154 */ 155 public double parseDouble( String lexicalXSDDouble ); 156 157 /** 158 * <p> 159 * Converts the string argument into a boolean value. 160 * @param 161 * lexicalXSDBoolean A string containing lexical representation of 162 * xsd:boolean. 163 * @return 164 * A boolean value represented by the string argument. 165 */ 166 public boolean parseBoolean( String lexicalXSDBoolean ); 167 168 /** 169 * <p> 170 * Converts the string argument into a byte value. 171 * @param 172 * lexicalXSDByte A string containing lexical representation of 173 * xsd:byte. 174 * @return 175 * A byte value represented by the string argument. 176 */ 177 public byte parseByte( String lexicalXSDByte ); 178 179 /** 180 * <p> 181 * Converts the string argument into a QName value. 182 * @param lexicalXSDQName 183 * A string containing lexical representation of xsd:QName. 184 * @param nsc 185 * A namespace context for interpreting a prefix within a QName. 186 * @return 187 * A QName value represented by the string argument. 188 */ 189 public javax.xml.namespace.QName parseQName( String lexicalXSDQName, 190 javax.xml.namespace.NamespaceContext nsc); 191 192 /** 193 * <p> 194 * Converts the string argument into a Calendar value. 195 * @param 196 * lexicalXSDDateTime A string containing lexical representation of 197 * xsd:datetime. 198 * @return 199 * A Calendar object represented by the string argument. 200 */ 201 public java.util.Calendar parseDateTime( String lexicalXSDDateTime ); 202 203 /** 204 * <p> 205 * Converts the string argument into an array of bytes. 206 * @param 207 * lexicalXSDBase64Binary A string containing lexical representation 208 * of xsd:base64Binary. 209 * @return 210 * An array of bytes represented by the string argument. 211 */ 212 public byte[] parseBase64Binary( String lexicalXSDBase64Binary ); 213 214 /** 215 * <p> 216 * Converts the string argument into an array of bytes. 217 * @param 218 * lexicalXSDHexBinary A string containing lexical representation of 219 * xsd:hexBinary. 220 * @return 221 * An array of bytes represented by the string argument. 222 */ 223 public byte[] parseHexBinary( String lexicalXSDHexBinary ); 224 225 /** 226 * <p> 227 * Converts the string argument into a long value. 228 * @param 229 * lexicalXSDUnsignedInt A string containing lexical representation 230 * of xsd:unsignedInt. 231 * @return 232 * A long value represented by the string argument. 233 */ 234 public long parseUnsignedInt( String lexicalXSDUnsignedInt ); 235 236 /** 237 * <p> 238 * Converts the string argument into an int value. 239 * @param 240 * lexicalXSDUnsignedShort -A string containing lexical 241 * representation of xsd:unsignedShort. 242 * @return 243 * An int value represented by the string argument. 244 */ 245 public int parseUnsignedShort( String lexicalXSDUnsignedShort ); 246 247 /** 248 * <p> 249 * Converts the string argument into a Calendar value. 250 * @param 251 * lexicalXSDTime A string containing lexical representation of 252 * xsd:time. 253 * @return 254 * A Calendar value represented by the string argument. 255 */ 256 public java.util.Calendar parseTime( String lexicalXSDTime ); 257 258 /** 259 * <p> 260 * Converts the string argument into a Calendar value. 261 * @param 262 * lexicalXSDDate A string containing lexical representation of 263 * xsd:Date. 264 * @return 265 * A Calendar value represented by the string argument. 266 */ 267 public java.util.Calendar parseDate( String lexicalXSDDate ); 268 269 /** 270 * <p> 271 * Return a string containing the lexical representation of the 272 * simple type. 273 * @param 274 * lexicalXSDAnySimpleType A string containing lexical 275 * representation of the simple type. 276 * @return 277 * A string containing the lexical representation of the 278 * simple type. 279 */ 280 public String parseAnySimpleType( String lexicalXSDAnySimpleType ); 281 282 /** 283 * <p> 284 * Converts the string argument into a string. 285 * @param val 286 * A string value. 287 * @return 288 * A string containing a lexical representation of xsd:string 289 */ 290 public String printString( String val ); 291 292 /** 293 * <p> 294 * Converts a BigInteger value into a string. 295 * @param val 296 * A BigInteger value 297 * @return 298 * A string containing a lexical representation of xsd:integer 299 */ 300 public String printInteger( java.math.BigInteger val ); 301 302 /** 303 * <p> 304 * Converts an int value into a string. 305 * @param val 306 * An int value 307 * @return 308 * A string containing a lexical representation of xsd:int 309 */ 310 public String printInt( int val ); 311 312 313 /** 314 * <p> 315 * Converts a long value into a string. 316 * @param val 317 * A long value 318 * @return 319 * A string containing a lexical representation of xsd:long 320 */ 321 public String printLong( long val ); 322 323 /** 324 * <p> 325 * Converts a short value into a string. 326 * @param val 327 * A short value 328 * @return 329 * A string containing a lexical representation of xsd:short 330 */ 331 public String printShort( short val ); 332 333 /** 334 * <p> 335 * Converts a BigDecimal value into a string. 336 * @param val 337 * A BigDecimal value 338 * @return 339 * A string containing a lexical representation of xsd:decimal 340 */ 341 public String printDecimal( java.math.BigDecimal val ); 342 343 /** 344 * <p> 345 * Converts a float value into a string. 346 * @param val 347 * A float value 348 * @return 349 * A string containing a lexical representation of xsd:float 350 */ 351 public String printFloat( float val ); 352 353 /** 354 * <p> 355 * Converts a double value into a string. 356 * @param val 357 * A double value 358 * @return 359 * A string containing a lexical representation of xsd:double 360 */ 361 public String printDouble( double val ); 362 363 /** 364 * <p> 365 * Converts a boolean value into a string. 366 * @param val 367 * A boolean value 368 * @return 369 * A string containing a lexical representation of xsd:boolean 370 */ 371 public String printBoolean( boolean val ); 372 373 /** 374 * <p> 375 * Converts a byte value into a string. 376 * @param val 377 * A byte value 378 * @return 379 * A string containing a lexical representation of xsd:byte 380 */ 381 public String printByte( byte val ); 382 383 /** 384 * <p> 385 * Converts a QName instance into a string. 386 * @param val 387 * A QName value 388 * @param nsc 389 * A namespace context for interpreting a prefix within a QName. 390 * @return 391 * A string containing a lexical representation of QName 392 */ 393 public String printQName( javax.xml.namespace.QName val, 394 javax.xml.namespace.NamespaceContext nsc ); 395 396 /** 397 * <p> 398 * Converts a Calendar value into a string. 399 * @param val 400 * A Calendar value 401 * @return 402 * A string containing a lexical representation of xsd:dateTime 403 */ 404 public String printDateTime( java.util.Calendar val ); 405 406 /** 407 * <p> 408 * Converts an array of bytes into a string. 409 * @param val 410 * an array of bytes 411 * @return 412 * A string containing a lexical representation of xsd:base64Binary 413 */ 414 public String printBase64Binary( byte[] val ); 415 416 /** 417 * <p> 418 * Converts an array of bytes into a string. 419 * @param val 420 * an array of bytes 421 * @return 422 * A string containing a lexical representation of xsd:hexBinary 423 */ 424 public String printHexBinary( byte[] val ); 425 426 /** 427 * <p> 428 * Converts a long value into a string. 429 * @param val 430 * A long value 431 * @return 432 * A string containing a lexical representation of xsd:unsignedInt 433 */ 434 public String printUnsignedInt( long val ); 435 436 /** 437 * <p> 438 * Converts an int value into a string. 439 * @param val 440 * An int value 441 * @return 442 * A string containing a lexical representation of xsd:unsignedShort 443 */ 444 public String printUnsignedShort( int val ); 445 446 /** 447 * <p> 448 * Converts a Calendar value into a string. 449 * @param val 450 * A Calendar value 451 * @return 452 * A string containing a lexical representation of xsd:time 453 */ 454 public String printTime( java.util.Calendar val ); 455 456 /** 457 * <p> 458 * Converts a Calendar value into a string. 459 * @param val 460 * A Calendar value 461 * @return 462 * A string containing a lexical representation of xsd:date 463 */ 464 public String printDate( java.util.Calendar val ); 465 466 /** 467 * <p> 468 * Converts a string value into a string. 469 * @param val 470 * A string value 471 * @return 472 * A string containing a lexical representation of xsd:AnySimpleType 473 */ 474 public String printAnySimpleType( String val ); 475 }