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