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 }