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