001    /*
002     * $Id: DatatypeConverterInterface.java,v 1.1 2002/12/04 17:04:30 ryans 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    /**
014     * <p>
015     * The DatatypeConverterInterface is for JAXB provider use only. A 
016     * JAXB provider must supply a class that implements this interface. 
017     * JAXB Providers are required to call the 
018     * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) 
019     * DatatypeConverter.setDatatypeConverter} api at 
020     * some point before the first marshal or unmarshal operation (perhaps during
021     * the call to JAXBContext.newInstance).  This step is necessary to configure 
022     * the converter that should be used to perform the print and parse 
023     * functionality.  Calling this api repeatedly will have no effect - the 
024     * DatatypeConverter instance passed into the first invocation is the one that 
025     * will be used from then on.
026     * </p>
027     *
028     * <p>
029     * This interface defines the parse and print methods. There is one
030     * parse and print method for each XML schema datatype specified in the
031     * the default binding Table 5-1 in the JAXB specification. 
032     * </p>
033     *
034     * <p>
035     * The parse and print methods defined here are invoked by the static parse
036     * and print methods defined in the {@link DatatypeConverter DatatypeConverter} 
037     * class.
038     * </p>
039     *
040     * <p>
041     * A parse method for a XML schema datatype must be capable of converting any
042     * lexical representation of the XML schema datatype ( specified by the
043     * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes 
044     * specification</a> into a value in the value space of the XML schema datatype. 
045     * If an error is encountered during conversion, then a ParseConversionEvent 
046     * must be generated.
047     * </p>
048     *
049     * <p>
050     * A print method for a XML schema datatype can output any lexical 
051     * representation that is valid with respect to the XML schema datatype.
052     * If an error is encountered during conversion, then a PrintConversionEvent
053     * must be generated.
054     * </p>
055     *
056     * The prefix xsd: is used to refer to XML schema datatypes
057     * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes 
058     * specification.</a>
059     *  
060     * <p>
061     * @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>
062     * @version $Revision: 1.1 $
063     * @see DatatypeConverter
064     * @see ParseConversionEvent
065     * @see PrintConversionEvent
066     * @since JAXB1.0
067     */
068    
069    public interface DatatypeConverterInterface {
070        /**  
071         * <p>
072         * Convert the string argument into a string. 
073         * @param lexicalXSDString
074         *     A lexical representation of the XML Schema datatype xsd:string
075         * @return
076         *     A string that is the same as the input string.
077         */ 
078        public String parseString( String lexicalXSDString );
079    
080        /**
081         * <p>
082         * Convert the string argument into a BigInteger value.
083         * @param
084         *     lexicalXSDInteger A string containing a lexical representation of 
085         *     xsd:integer.
086         * @return
087         *     A BigInteger value represented by the string argument.
088         */ 
089        public java.math.BigInteger parseInteger( String lexicalXSDInteger );
090    
091        /**
092         * <p>
093         * Convert the string argument into an int value.
094         * @param
095         *     lexicalXSDInt A string containing a lexical representation of 
096         *     xsd:int.
097         * @return
098         *     An int value represented byte the string argument.
099         */ 
100        public int parseInt( String lexicalXSDInt );
101    
102        /**
103         * <p>
104         * Converts the string argument into a long value.
105         * @param
106         *     lexicalXSDLong A string containing lexical representation of 
107         *     xsd:long.
108         * @return
109         *     A long value represented by the string argument.
110         */ 
111        public long parseLong( String lexicalXSLong );
112    
113        /**
114         * <p>
115         * Converts the string argument into a short value.
116         * @param
117         *     lexicalXSDShort A string containing lexical representation of 
118         *     xsd:short.
119         * @return
120         *     A short value represented by the string argument.
121         */ 
122        public short parseShort( String lexicalXSDShort );
123    
124        /**
125         * <p>
126         * Converts the string argument into a BigDecimal value.
127         * @param
128         *     lexicalXSDDecimal A string containing lexical representation of 
129         *     xsd:decimal.
130         * @return
131         *     A BigDecimal value represented by the string argument.
132         */ 
133        public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal );
134    
135        /**
136         * <p>
137         * Converts the string argument into a float value.
138         * @param
139         *     lexicalXSDFloat A string containing lexical representation of 
140         *     xsd:float.
141         * @return
142         *     A float value represented by the string argument.
143         */ 
144        public float parseFloat( String lexicalXSDFloat );
145    
146        /**
147         * <p>
148         * Converts the string argument into a double value.
149         * @param
150         *     lexicalXSDDouble A string containing lexical representation of 
151         *     xsd:double.
152         * @return
153         *     A double value represented by the string argument.
154         */ 
155        public double parseDouble( String lexicalXSDDouble );
156    
157        /**
158         * <p>
159         * Converts the string argument into a boolean value.
160         * @param
161         *     lexicalXSDBoolean A string containing lexical representation of 
162         *     xsd:boolean.
163         * @return
164         *     A boolean value represented by the string argument.
165         */ 
166        public boolean parseBoolean( String lexicalXSDBoolean );
167    
168        /**
169         * <p>
170         * Converts the string argument into a byte value.
171         * @param
172         *     lexicalXSDByte A string containing lexical representation of 
173         *     xsd:byte.
174         * @return
175         *     A byte value represented by the string argument.
176         */ 
177        public byte parseByte( String lexicalXSDByte );
178        
179        /**
180         * <p>
181         * Converts the string argument into a QName value.
182         * @param lexicalXSDQName
183         *     A string containing lexical representation of xsd:QName.
184         * @param nsc
185         *     A namespace context for interpreting a prefix within a QName.
186         * @return
187         *     A QName value represented by the string argument.
188         */ 
189        public javax.xml.namespace.QName parseQName( String lexicalXSDQName,
190                                                 javax.xml.namespace.NamespaceContext nsc);
191    
192        /**
193         * <p>
194         * Converts the string argument into a Calendar value.
195         * @param
196         *     lexicalXSDDateTime A string containing lexical representation of 
197         *     xsd:datetime.
198         * @return
199         *     A Calendar object represented by the string argument.
200         */ 
201        public java.util.Calendar parseDateTime( String lexicalXSDDateTime );
202    
203        /**
204         * <p>
205         * Converts the string argument into an array of bytes.
206         * @param
207         *     lexicalXSDBase64Binary A string containing lexical representation
208         *     of xsd:base64Binary.
209         * @return
210         *     An array of bytes represented by the string argument.
211         */ 
212        public byte[] parseBase64Binary( String lexicalXSDBase64Binary );
213    
214        /**
215         * <p>
216         * Converts the string argument into an array of bytes.
217         * @param
218         *     lexicalXSDHexBinary A string containing lexical representation of
219         *     xsd:hexBinary.
220         * @return
221         *     An array of bytes represented by the string argument.
222         */ 
223        public byte[] parseHexBinary( String lexicalXSDHexBinary );
224    
225        /**
226         * <p>
227         * Converts the string argument into a long value.
228         * @param
229         *     lexicalXSDUnsignedInt A string containing lexical representation 
230         *     of xsd:unsignedInt.
231         * @return
232         *     A long value represented by the string argument.
233         */ 
234        public long parseUnsignedInt( String lexicalXSDUnsignedInt );
235    
236        /**
237         * <p>
238         * Converts the string argument into an int value.
239         * @param
240         *     lexicalXSDUnsignedShort -A string containing lexical 
241         *     representation of xsd:unsignedShort.
242         * @return
243         *     An int value represented by the string argument.
244         */ 
245        public int parseUnsignedShort( String lexicalXSDUnsignedShort );
246    
247        /**
248         * <p>
249         * Converts the string argument into a Calendar value.
250         * @param
251         *     lexicalXSDTime A string containing lexical representation of 
252         *     xsd:time.
253         * @return
254         *     A Calendar value represented by the string argument.
255         */ 
256        public java.util.Calendar parseTime( String lexicalXSDTime );
257        
258        /**
259         * <p>
260         * Converts the string argument into a Calendar value.
261         * @param
262         *     lexicalXSDDate A string containing lexical representation of 
263         *     xsd:Date.
264         * @return
265         *     A Calendar value represented by the string argument.
266         */ 
267        public java.util.Calendar parseDate( String lexicalXSDDate );
268    
269        /**
270         * <p>
271         * Return a string containing the lexical representation of the 
272         * simple type.
273         * @param
274         *     lexicalXSDAnySimpleType A string containing lexical 
275         *     representation of the simple type.
276         * @return
277         *     A string containing the lexical representation of the 
278         *     simple type.
279         */ 
280        public String parseAnySimpleType( String lexicalXSDAnySimpleType );
281        
282        /**
283         * <p>
284         * Converts the string argument into a string.
285         * @param val
286         *     A string value.
287         * @return
288         *     A string containing a lexical representation of xsd:string
289         */ 
290        public String printString( String val );
291    
292        /**
293         * <p>
294         * Converts a BigInteger value into a string.
295         * @param val
296         *     A BigInteger value
297         * @return
298         *     A string containing a lexical representation of xsd:integer
299         */ 
300        public String printInteger( java.math.BigInteger val );
301    
302        /**
303         * <p>
304         * Converts an int value into a string.
305         * @param val
306         *     An int value
307         * @return
308         *     A string containing a lexical representation of xsd:int
309         */ 
310        public String printInt( int val );
311    
312    
313        /**
314         * <p>
315         * Converts a long value into a string.
316         * @param val
317         *     A long value
318         * @return
319         *     A string containing a lexical representation of xsd:long
320         */ 
321        public String printLong( long val );
322    
323        /**
324         * <p>
325         * Converts a short value into a string.
326         * @param val
327         *     A short value
328         * @return
329         *     A string containing a lexical representation of xsd:short
330         */ 
331        public String printShort( short val );
332    
333        /**
334         * <p>
335         * Converts a BigDecimal value into a string.
336         * @param val
337         *     A BigDecimal value
338         * @return
339         *     A string containing a lexical representation of xsd:decimal
340         */ 
341        public String printDecimal( java.math.BigDecimal val );
342    
343        /**
344         * <p>
345         * Converts a float value into a string.
346         * @param val
347         *     A float value
348         * @return
349         *     A string containing a lexical representation of xsd:float
350         */ 
351        public String printFloat( float val );
352    
353        /**
354         * <p>
355         * Converts a double value into a string.
356         * @param val
357         *     A double value
358         * @return
359         *     A string containing a lexical representation of xsd:double
360         */ 
361        public String printDouble( double val );
362    
363        /**
364         * <p>
365         * Converts a boolean value into a string.
366         * @param val
367         *     A boolean value
368         * @return
369         *     A string containing a lexical representation of xsd:boolean
370         */ 
371        public String printBoolean( boolean val );
372    
373        /**
374         * <p>
375         * Converts a byte value into a string.
376         * @param val
377         *     A byte value
378         * @return
379         *     A string containing a lexical representation of xsd:byte
380         */ 
381        public String printByte( byte val );
382    
383        /**
384         * <p>
385         * Converts a QName instance into a string.
386         * @param val
387         *     A QName value
388         * @param nsc
389         *     A namespace context for interpreting a prefix within a QName.
390         * @return
391         *     A string containing a lexical representation of QName
392         */ 
393        public String printQName( javax.xml.namespace.QName val,
394                                  javax.xml.namespace.NamespaceContext nsc );
395    
396        /**
397         * <p>
398         * Converts a Calendar value into a string.
399         * @param val
400         *     A Calendar value
401         * @return
402         *     A string containing a lexical representation of xsd:dateTime
403         */ 
404        public String printDateTime( java.util.Calendar val );
405    
406        /**
407         * <p>
408         * Converts an array of bytes into a string.
409         * @param val
410         *     an array of bytes
411         * @return
412         *     A string containing a lexical representation of xsd:base64Binary
413         */ 
414        public String printBase64Binary( byte[] val );
415    
416        /**
417         * <p>
418         * Converts an array of bytes into a string.
419         * @param val
420         *     an array of bytes
421         * @return
422         *     A string containing a lexical representation of xsd:hexBinary
423         */ 
424        public String printHexBinary( byte[] val );
425    
426        /**
427         * <p>
428         * Converts a long value into a string.
429         * @param val
430         *     A long value
431         * @return
432         *     A string containing a lexical representation of xsd:unsignedInt
433         */ 
434        public String printUnsignedInt( long val );
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:unsignedShort
443         */ 
444        public String printUnsignedShort( int val );
445    
446        /**
447         * <p>
448         * Converts a Calendar value into a string.
449         * @param val
450         *     A Calendar value
451         * @return
452         *     A string containing a lexical representation of xsd:time
453         */ 
454        public String printTime( java.util.Calendar val );
455    
456        /**
457         * <p>
458         * Converts a Calendar value into a string.
459         * @param val
460         *     A Calendar value
461         * @return
462         *     A string containing a lexical representation of xsd:date
463         */ 
464        public String printDate( java.util.Calendar val );
465    
466        /**
467         * <p>
468         * Converts a string value into a string.
469         * @param val
470         *     A string value
471         * @return
472         *     A string containing a lexical representation of xsd:AnySimpleType
473         */ 
474        public String printAnySimpleType( String val );
475    }