DatatypeConverter


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