001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind;
027
028 /**
029 * <p>
030 * The DatatypeConverterInterface is for JAXB provider use only. A
031 * JAXB provider must supply a class that implements this interface.
032 * JAXB Providers are required to call the
033 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
034 * DatatypeConverter.setDatatypeConverter} api at
035 * some point before the first marshal or unmarshal operation (perhaps during
036 * the call to JAXBContext.newInstance). This step is necessary to configure
037 * the converter that should be used to perform the print and parse
038 * functionality. Calling this api repeatedly will have no effect - the
039 * DatatypeConverter instance passed into the first invocation is the one that
040 * will be used from then on.
041 * </p>
042 *
043 * <p>
044 * This interface defines the parse and print methods. There is one
045 * parse and print method for each XML schema datatype specified in the
046 * the default binding Table 5-1 in the JAXB specification.
047 * </p>
048 *
049 * <p>
050 * The parse and print methods defined here are invoked by the static parse
051 * and print methods defined in the {@link DatatypeConverter DatatypeConverter}
052 * class.
053 * </p>
054 *
055 * <p>
056 * A parse method for a XML schema datatype must be capable of converting any
057 * lexical representation of the XML schema datatype ( specified by the
058 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
059 * specification</a> into a value in the value space of the XML schema datatype.
060 * If an error is encountered during conversion, then an IllegalArgumentException
061 * or a subclass of IllegalArgumentException must be thrown by the method.
062 *
063 * </p>
064 *
065 * <p>
066 * A print method for a XML schema datatype can output any lexical
067 * representation that is valid with respect to the XML schema datatype.
068 * If an error is encountered during conversion, then an IllegalArgumentException,
069 * or a subclass of IllegalArgumentException must be thrown by the method.
070 * </p>
071 *
072 * The prefix xsd: is used to refer to XML schema datatypes
073 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
074 * specification.</a>
075 *
076 * <p>
077 * @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>
078 * @version $Revision: 1.4 $
079 * @see DatatypeConverter
080 * @see ParseConversionEvent
081 * @see PrintConversionEvent
082 * @since JAXB1.0
083 */
084
085 public interface DatatypeConverterInterface {
086 /**
087 * <p>
088 * Convert the string argument into a string.
089 * @param lexicalXSDString
090 * A lexical representation of the XML Schema datatype xsd:string
091 * @return
092 * A string that is the same as the input string.
093 */
094 public String parseString(String lexicalXSDString);
095
096 /**
097 * <p>
098 * Convert the string argument into a BigInteger value.
099 * @param lexicalXSDInteger
100 * A string containing a lexical representation of
101 * xsd:integer.
102 * @return
103 * A BigInteger value represented by the string argument.
104 * @throws NumberFormatException <code>lexicalXSDInteger</code> is not a valid string representation of a {@link java.math.BigInteger} value.
105 */
106 public java.math.BigInteger parseInteger(String lexicalXSDInteger);
107
108 /**
109 * <p>
110 * Convert the string argument into an int value.
111 * @param lexicalXSDInt
112 * A string containing a lexical representation of
113 * xsd:int.
114 * @return
115 * An int value represented byte the string argument.
116 * @throws NumberFormatException <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value.
117 */
118 public int parseInt(String lexicalXSDInt);
119
120 /**
121 * <p>
122 * Converts the string argument into a long value.
123 * @param lexicalXSDLong
124 * A string containing lexical representation of
125 * xsd:long.
126 * @return
127 * A long value represented by the string argument.
128 * @throws NumberFormatException <code>lexicalXSDLong</code> is not a valid string representation of a <code>long</code> value.
129 */
130 public long parseLong(String lexicalXSDLong);
131
132 /**
133 * <p>
134 * Converts the string argument into a short value.
135 * @param lexicalXSDShort
136 * A string containing lexical representation of
137 * xsd:short.
138 * @return
139 * A short value represented by the string argument.
140 * @throws NumberFormatException <code>lexicalXSDShort</code> is not a valid string representation of a <code>short</code> value.
141 */
142 public short parseShort(String lexicalXSDShort);
143
144 /**
145 * <p>
146 * Converts the string argument into a BigDecimal value.
147 * @param lexicalXSDDecimal
148 * A string containing lexical representation of
149 * xsd:decimal.
150 * @return
151 * A BigDecimal value represented by the string argument.
152 * @throws NumberFormatException <code>lexicalXSDDecimal</code> is not a valid string representation of {@link java.math.BigDecimal}.
153 */
154 public java.math.BigDecimal parseDecimal(String lexicalXSDDecimal);
155
156 /**
157 * <p>
158 * Converts the string argument into a float value.
159 * @param lexicalXSDFloat
160 * A string containing lexical representation of
161 * xsd:float.
162 * @return
163 * A float value represented by the string argument.
164 * @throws NumberFormatException <code>lexicalXSDFloat</code> is not a valid string representation of a <code>float</code> value.
165 */
166 public float parseFloat(String lexicalXSDFloat);
167
168 /**
169 * <p>
170 * Converts the string argument into a double value.
171 * @param lexicalXSDDouble
172 * A string containing lexical representation of
173 * xsd:double.
174 * @return
175 * A double value represented by the string argument.
176 * @throws NumberFormatException <code>lexicalXSDDouble</code> is not a valid string representation of a <code>double</code> value.
177 */
178 public double parseDouble(String lexicalXSDDouble);
179
180 /**
181 * <p>
182 * Converts the string argument into a boolean value.
183 * @param lexicalXSDBoolean
184 * A string containing lexical representation of
185 * xsd:boolean.
186 * @return
187 * A boolean value represented by the string argument.
188 * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.
189 */
190 public boolean parseBoolean(String lexicalXSDBoolean);
191
192 /**
193 * <p>
194 * Converts the string argument into a byte value.
195 * @param lexicalXSDByte
196 * A string containing lexical representation of
197 * xsd:byte.
198 * @return
199 * A byte value represented by the string argument.
200 * @throws NumberFormatException <code>lexicalXSDByte</code> does not contain a parseable byte.
201 * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.
202 */
203 public byte parseByte(String lexicalXSDByte);
204
205 /**
206 * <p>
207 * Converts the string argument into a QName value.
208 *
209 * <p>
210 * String parameter <tt>lexicalXSDQname</tt> must conform to lexical value space specifed at
211 * <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part 2:Datatypes specification:QNames</a>
212 *
213 * @param lexicalXSDQName
214 * A string containing lexical representation of xsd:QName.
215 * @param nsc
216 * A namespace context for interpreting a prefix within a QName.
217 * @return
218 * A QName value represented by the string argument.
219 * @throws IllegalArgumentException if string parameter does not conform to XML Schema Part 2 specification or
220 * if namespace prefix of <tt>lexicalXSDQname</tt> is not bound to a URI in NamespaceContext <tt>nsc</tt>.
221 */
222 public javax.xml.namespace.QName parseQName(String lexicalXSDQName,
223 javax.xml.namespace.NamespaceContext nsc);
224
225 /**
226 * <p>
227 * Converts the string argument into a Calendar value.
228 * @param lexicalXSDDateTime
229 * A string containing lexical representation of
230 * xsd:datetime.
231 * @return
232 * A Calendar object represented by the string argument.
233 * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.
234 */
235 public java.util.Calendar parseDateTime(String lexicalXSDDateTime);
236
237 /**
238 * <p>
239 * Converts the string argument into an array of bytes.
240 * @param lexicalXSDBase64Binary
241 * A string containing lexical representation
242 * of xsd:base64Binary.
243 * @return
244 * An array of bytes represented by the string argument.
245 * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary
246 */
247 public byte[] parseBase64Binary(String lexicalXSDBase64Binary);
248
249 /**
250 * <p>
251 * Converts the string argument into an array of bytes.
252 * @param lexicalXSDHexBinary
253 * A string containing lexical representation of
254 * xsd:hexBinary.
255 * @return
256 * An array of bytes represented by the string argument.
257 * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.
258 */
259 public byte[] parseHexBinary(String lexicalXSDHexBinary);
260
261 /**
262 * <p>
263 * Converts the string argument into a long value.
264 * @param lexicalXSDUnsignedInt
265 * A string containing lexical representation
266 * of xsd:unsignedInt.
267 * @return
268 * A long value represented by the string argument.
269 * @throws NumberFormatException if string parameter can not be parsed into a <tt>long</tt> value.
270 */
271 public long parseUnsignedInt(String lexicalXSDUnsignedInt);
272
273 /**
274 * <p>
275 * Converts the string argument into an int value.
276 * @param lexicalXSDUnsignedShort
277 * A string containing lexical
278 * representation of xsd:unsignedShort.
279 * @return
280 * An int value represented by the string argument.
281 * @throws NumberFormatException if string parameter can not be parsed into an <tt>int</tt> value.
282 */
283 public int parseUnsignedShort(String lexicalXSDUnsignedShort);
284
285 /**
286 * <p>
287 * Converts the string argument into a Calendar value.
288 * @param lexicalXSDTime
289 * A string containing lexical representation of
290 * xsd:Time.
291 * @return
292 * A Calendar value represented by the string argument.
293 * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.
294 */
295 public java.util.Calendar parseTime(String lexicalXSDTime);
296
297 /**
298 * <p>
299 * Converts the string argument into a Calendar value.
300 * @param lexicalXSDDate
301 * A string containing lexical representation of
302 * xsd:Date.
303 * @return
304 * A Calendar value represented by the string argument.
305 * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.
306 */
307 public java.util.Calendar parseDate(String lexicalXSDDate);
308
309 /**
310 * <p>
311 * Return a string containing the lexical representation of the
312 * simple type.
313 * @param lexicalXSDAnySimpleType
314 * A string containing lexical
315 * representation of the simple type.
316 * @return
317 * A string containing the lexical representation of the
318 * simple type.
319 */
320 public String parseAnySimpleType(String lexicalXSDAnySimpleType);
321
322 /**
323 * <p>
324 * Converts the string argument into a string.
325 * @param val
326 * A string value.
327 * @return
328 * A string containing a lexical representation of xsd:string
329 */
330 public String printString(String val);
331
332 /**
333 * <p>
334 * Converts a BigInteger value into a string.
335 * @param val
336 * A BigInteger value
337 * @return
338 * A string containing a lexical representation of xsd:integer
339 * @throws IllegalArgumentException <tt>val</tt> is null.
340 */
341 public String printInteger(java.math.BigInteger val);
342
343 /**
344 * <p>
345 * Converts an int value into a string.
346 * @param val
347 * An int value
348 * @return
349 * A string containing a lexical representation of xsd:int
350 */
351 public String printInt(int val);
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 }
|