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