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 1.6, JAXB 1.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 }