Java > Open Source Codes > javax > xml > bind > DatatypeConverterInterface


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 /**
9  * <p>
10  * The DatatypeConverterInterface is for JAXB provider use only. A
11  * JAXB provider must supply a class that implements this interface.
12  * JAXB Providers are required to call the
13  * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
14  * DatatypeConverter.setDatatypeConverter} api at
15  * some point before the first marshal or unmarshal operation (perhaps during
16  * the call to JAXBContext.newInstance). This step is necessary to configure
17  * the converter that should be used to perform the print and parse
18  * functionality. Calling this api repeatedly will have no effect - the
19  * DatatypeConverter instance passed into the first invocation is the one that
20  * will be used from then on.
21  * </p>
22  *
23  * <p>
24  * This interface defines the parse and print methods. There is one
25  * parse and print method for each XML schema datatype specified in the
26  * the default binding Table 5-1 in the JAXB specification.
27  * </p>
28  *
29  * <p>
30  * The parse and print methods defined here are invoked by the static parse
31  * and print methods defined in the {@link DatatypeConverter DatatypeConverter}
32  * class.
33  * </p>
34  *
35  * <p>
36  * A parse method for a XML schema datatype must be capable of converting any
37  * lexical representation of the XML schema datatype ( specified by the
38  * <a HREF="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
39  * specification</a> into a value in the value space of the XML schema datatype.
40  * If an error is encountered during conversion, then an IllegalArgumentException
41  * or a subclass of IllegalArgumentException must be thrown by the method.
42  *
43  * </p>
44  *
45  * <p>
46  * A print method for a XML schema datatype can output any lexical
47  * representation that is valid with respect to the XML schema datatype.
48  * If an error is encountered during conversion, then an IllegalArgumentException,
49  * or a subclass of IllegalArgumentException must be thrown by the method.
50  * </p>
51  *
52  * The prefix xsd: is used to refer to XML schema datatypes
53  * <a HREF="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
54  * specification.</a>
55  *
56  * <p>
57  * @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>
58  * @version $Revision: 1.4 $
59  * @see DatatypeConverter
60  * @see ParseConversionEvent
61  * @see PrintConversionEvent
62  * @since JAXB1.0
63  */
64
65 public interface DatatypeConverterInterface {
66     /**
67      * <p>
68      * Convert the string argument into a string.
69      * @param lexicalXSDString
70      * A lexical representation of the XML Schema datatype xsd:string
71      * @return
72      * A string that is the same as the input string.
73      */
74     public String parseString( String lexicalXSDString );
75
76     /**
77      * <p>
78      * Convert the string argument into a BigInteger value.
79      * @param lexicalXSDInteger
80      * A string containing a lexical representation of
81      * xsd:integer.
82      * @return
83      * A BigInteger value represented by the string argument.
84      * @throws NumberFormatException <code>lexicalXSDInteger</code> is not a valid string representation of a {@link java.math.BigInteger} value.
85      */
86     public java.math.BigInteger parseInteger( String lexicalXSDInteger );
87
88     /**
89      * <p>
90      * Convert the string argument into an int value.
91      * @param lexicalXSDInt
92      * A string containing a lexical representation of
93      * xsd:int.
94      * @return
95      * An int value represented byte the string argument.
96      * @throws NumberFormatException <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value.
97      */
98     public int parseInt( String lexicalXSDInt );
99
100     /**
101      * <p>
102      * Converts the string argument into a long value.
103      * @param lexicalXSDLong
104      * A string containing lexical representation of
105      * xsd:long.
106      * @return
107      * A long value represented by the string argument.
108      * @throws NumberFormatException <code>lexicalXSDLong</code> is not a valid string representation of a <code>long</code> value.
109      */
110     public long parseLong( String lexicalXSDLong );
111
112     /**
113      * <p>
114      * Converts the string argument into a short value.
115      * @param lexicalXSDShort
116      * A string containing lexical representation of
117      * xsd:short.
118      * @return
119      * A short value represented by the string argument.
120      * @throws NumberFormatException <code>lexicalXSDShort</code> is not a valid string representation of a <code>short</code> value.
121      */
122     public short parseShort( String lexicalXSDShort );
123
124     /**
125      * <p>
126      * Converts the string argument into a BigDecimal value.
127      * @param lexicalXSDDecimal
128      * A string containing lexical representation of
129      * xsd:decimal.
130      * @return
131      * A BigDecimal value represented by the string argument.
132      * @throws NumberFormatException <code>lexicalXSDDecimal</code> is not a valid string representation of {@link java.math.BigDecimal}.
133      */
134     public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal );
135
136     /**
137      * <p>
138      * Converts the string argument into a float value.
139      * @param lexicalXSDFloat
140      * A string containing lexical representation of
141      * xsd:float.
142      * @return
143      * A float value represented by the string argument.
144      * @throws NumberFormatException <code>lexicalXSDFloat</code> is not a valid string representation of a <code>float</code> value.
145      */
146     public float parseFloat( String lexicalXSDFloat );
147
148     /**
149      * <p>
150      * Converts the string argument into a double value.
151      * @param lexicalXSDDouble
152      * A string containing lexical representation of
153      * xsd:double.
154      * @return
155      * A double value represented by the string argument.
156      * @throws NumberFormatException <code>lexicalXSDDouble</code> is not a valid string representation of a <code>double</code> value.
157      */
158     public double parseDouble( String lexicalXSDDouble );
159
160     /**
161      * <p>
162      * Converts the string argument into a boolean value.
163      * @param lexicalXSDBoolean
164      * A string containing lexical representation of
165      * xsd:boolean.
166      * @return
167      * A boolean value represented by the string argument.
168      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.
169      */
170     public boolean parseBoolean( String lexicalXSDBoolean );
171
172     /**
173      * <p>
174      * Converts the string argument into a byte value.
175      * @param lexicalXSDByte
176      * A string containing lexical representation of
177      * xsd:byte.
178      * @return
179      * A byte value represented by the string argument.
180      * @throws NumberFormatException <code>lexicalXSDByte</code> does not contain a parseable byte.
181      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.
182      */
183     public byte parseByte( String lexicalXSDByte );
184     
185     /**
186      * <p>
187      * Converts the string argument into a QName value.
188      *
189      * <p>
190      * String parameter <tt>lexicalXSDQname</tt> must conform to lexical value space specifed at
191      * <a HREF="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part 2:Datatypes specification:QNames</a>
192      *
193      * @param lexicalXSDQName
194      * A string containing lexical representation of xsd:QName.
195      * @param nsc
196      * A namespace context for interpreting a prefix within a QName.
197      * @return
198      * A QName value represented by the string argument.
199      * @throws IllegalArgumentException if string parameter does not conform to XML Schema Part 2 specification or
200      * if namespace prefix of <tt>lexicalXSDQname</tt> is not bound to a URI in NamespaceContext <tt>nsc</tt>.
201      */
202     public javax.xml.namespace.QName parseQName( String lexicalXSDQName,
203                                  javax.xml.namespace.NamespaceContext nsc);
204
205     /**
206      * <p>
207      * Converts the string argument into a Calendar value.
208      * @param lexicalXSDDateTime
209      * A string containing lexical representation of
210      * xsd:datetime.
211      * @return
212      * A Calendar object represented by the string argument.
213      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.
214      */
215     public java.util.Calendar parseDateTime( String lexicalXSDDateTime );
216
217     /**
218      * <p>
219      * Converts the string argument into an array of bytes.
220      * @param lexicalXSDBase64Binary
221      * A string containing lexical representation
222      * of xsd:base64Binary.
223      * @return
224      * An array of bytes represented by the string argument.
225      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary
226      */
227     public byte[] parseBase64Binary( String lexicalXSDBase64Binary );
228
229     /**
230      * <p>
231      * Converts the string argument into an array of bytes.
232      * @param lexicalXSDHexBinary
233      * A string containing lexical representation of
234      * xsd:hexBinary.
235      * @return
236      * An array of bytes represented by the string argument.
237      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.
238      */
239     public byte[] parseHexBinary( String lexicalXSDHexBinary );
240
241     /**
242      * <p>
243      * Converts the string argument into a long value.
244      * @param lexicalXSDUnsignedInt
245      * A string containing lexical representation
246      * of xsd:unsignedInt.
247      * @return
248      * A long value represented by the string argument.
249      * @throws NumberFormatException if string parameter can not be parsed into a <tt>long</tt> value.
250      */
251     public long parseUnsignedInt( String lexicalXSDUnsignedInt );
252
253     /**
254      * <p>
255      * Converts the string argument into an int value.
256      * @param lexicalXSDUnsignedShort
257      * A string containing lexical
258      * representation of xsd:unsignedShort.
259      * @return
260      * An int value represented by the string argument.
261      * @throws NumberFormatException if string parameter can not be parsed into an <tt>int</tt> value.
262      */
263     public int parseUnsignedShort( String lexicalXSDUnsignedShort );
264
265     /**
266      * <p>
267      * Converts the string argument into a Calendar value.
268      * @param lexicalXSDTime
269      * A string containing lexical representation of
270      * xsd:Time.
271      * @return
272      * A Calendar value represented by the string argument.
273      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.
274      */
275     public java.util.Calendar parseTime( String lexicalXSDTime );
276     
277     /**
278      * <p>
279      * Converts the string argument into a Calendar value.
280      * @param lexicalXSDDate
281      * A string containing lexical representation of
282      * xsd:Date.
283      * @return
284      * A Calendar value represented by the string argument.
285      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.
286      */
287     public java.util.Calendar parseDate( String lexicalXSDDate );
288
289     /**
290      * <p>
291      * Return a string containing the lexical representation of the
292      * simple type.
293      * @param lexicalXSDAnySimpleType
294      * A string containing lexical
295      * representation of the simple type.
296      * @return
297      * A string containing the lexical representation of the
298      * simple type.
299      */
300     public String parseAnySimpleType( String lexicalXSDAnySimpleType );
301     
302     /**
303      * <p>
304      * Converts the string argument into a string.
305      * @param val
306      * A string value.
307      * @return
308      * A string containing a lexical representation of xsd:string
309      */
310     public String printString( String val );
311
312     /**
313      * <p>
314      * Converts a BigInteger value into a string.
315      * @param val
316      * A BigInteger value
317      * @return
318      * A string containing a lexical representation of xsd:integer
319      * @throws IllegalArgumentException <tt>val</tt> is null.
320      */
321     public String printInteger( java.math.BigInteger val );
322
323     /**
324      * <p>
325      * Converts an int value into a string.
326      * @param val
327      * An int value
328      * @return
329      * A string containing a lexical representation of xsd:int
330      */
331     public String printInt( int val );
332
333
334     /**
335      * <p>
336      * Converts a long value into a string.
337      * @param val
338      * A long value
339      * @return
340      * A string containing a lexical representation of xsd:long
341      */
342     public String printLong( long val );
343
344     /**
345      * <p>
346      * Converts a short value into a string.
347      * @param val
348      * A short value
349      * @return
350      * A string containing a lexical representation of xsd:short
351      */
352     public String printShort( short val );
353
354     /**
355      * <p>
356      * Converts a BigDecimal value into a string.
357      * @param val
358      * A BigDecimal value
359      * @return
360      * A string containing a lexical representation of xsd:decimal
361      * @throws IllegalArgumentException <tt>val</tt> is null.
362      */
363     public String printDecimal( java.math.BigDecimal val );
364
365     /**
366      * <p>
367      * Converts a float value into a string.
368      * @param val
369      * A float value
370      * @return
371      * A string containing a lexical representation of xsd:float
372      */
373     public String printFloat( float val );
374
375     /**
376      * <p>
377      * Converts a double value into a string.
378      * @param val
379      * A double value
380      * @return
381      * A string containing a lexical representation of xsd:double
382      */
383     public String printDouble( double val );
384
385     /**
386      * <p>
387      * Converts a boolean value into a string.
388      * @param val
389      * A boolean value
390      * @return
391      * A string containing a lexical representation of xsd:boolean
392      */
393     public String printBoolean( boolean val );
394
395     /**
396      * <p>
397      * Converts a byte value into a string.
398      * @param val
399      * A byte value
400      * @return
401      * A string containing a lexical representation of xsd:byte
402      */
403     public String printByte( byte val );
404
405     /**
406      * <p>
407      * Converts a QName instance into a string.
408      * @param val
409      * A QName value
410      * @param nsc
411      * A namespace context for interpreting a prefix within a QName.
412      * @return
413      * A string containing a lexical representation of QName
414      * @throws IllegalArgumentException if <tt>val</tt> is null or
415      * if <tt>nsc</tt> is non-null or <tt>nsc.getPrefix(nsprefixFromVal)</tt> is null.
416      */
417     public String printQName( javax.xml.namespace.QName val,
418                               javax.xml.namespace.NamespaceContext nsc );
419
420     /**
421      * <p>
422      * Converts a Calendar value into a string.
423      * @param val
424      * A Calendar value
425      * @return
426      * A string containing a lexical representation of xsd:dateTime
427      * @throws IllegalArgumentException if <tt>val</tt> is null.
428      */
429     public String printDateTime( java.util.Calendar val );
430
431     /**
432      * <p>
433      * Converts an array of bytes into a string.
434      * @param val
435      * an array of bytes
436      * @return
437      * A string containing a lexical representation of xsd:base64Binary
438      * @throws IllegalArgumentException if <tt>val</tt> is null.
439      */
440     public String printBase64Binary( byte[] val );
441
442     /**
443      * <p>
444      * Converts an array of bytes into a string.
445      * @param val
446      * an array of bytes
447      * @return
448      * A string containing a lexical representation of xsd:hexBinary
449      * @throws IllegalArgumentException if <tt>val</tt> is null.
450      */
451     public String printHexBinary( byte[] val );
452
453     /**
454      * <p>
455      * Converts a long value into a string.
456      * @param val
457      * A long value
458      * @return
459      * A string containing a lexical representation of xsd:unsignedInt
460      */
461     public String printUnsignedInt( long val );
462
463     /**
464      * <p>
465      * Converts an int value into a string.
466      * @param val
467      * An int value
468      * @return
469      * A string containing a lexical representation of xsd:unsignedShort
470      */
471     public String printUnsignedShort( int val );
472
473     /**
474      * <p>
475      * Converts a Calendar value into a string.
476      * @param val
477      * A Calendar value
478      * @return
479      * A string containing a lexical representation of xsd:time
480      * @throws IllegalArgumentException if <tt>val</tt> is null.
481      */
482     public String printTime( java.util.Calendar val );
483
484     /**
485      * <p>
486      * Converts a Calendar value into a string.
487      * @param val
488      * A Calendar value
489      * @return
490      * A string containing a lexical representation of xsd:date
491      * @throws IllegalArgumentException if <tt>val</tt> is null.
492      */
493     public String printDate( java.util.Calendar val );
494
495     /**
496      * <p>
497      * Converts a string value into a string.
498      * @param val
499      * A string value
500      * @return
501      * A string containing a lexical representation of xsd:AnySimpleType
502      */
503     public String printAnySimpleType( String val );
504 }
505

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags