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    }