001: /*
002: * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.bind;
007:
008: /**
009: * <p>
010: * The DatatypeConverterInterface is for JAXB provider use only. A
011: * JAXB provider must supply a class that implements this interface.
012: * JAXB Providers are required to call the
013: * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
014: * DatatypeConverter.setDatatypeConverter} api at
015: * some point before the first marshal or unmarshal operation (perhaps during
016: * the call to JAXBContext.newInstance). This step is necessary to configure
017: * the converter that should be used to perform the print and parse
018: * functionality. Calling this api repeatedly will have no effect - the
019: * DatatypeConverter instance passed into the first invocation is the one that
020: * will be used from then on.
021: * </p>
022: *
023: * <p>
024: * This interface defines the parse and print methods. There is one
025: * parse and print method for each XML schema datatype specified in the
026: * the default binding Table 5-1 in the JAXB specification.
027: * </p>
028: *
029: * <p>
030: * The parse and print methods defined here are invoked by the static parse
031: * and print methods defined in the {@link DatatypeConverter DatatypeConverter}
032: * class.
033: * </p>
034: *
035: * <p>
036: * A parse method for a XML schema datatype must be capable of converting any
037: * lexical representation of the XML schema datatype ( specified by the
038: * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
039: * specification</a> into a value in the value space of the XML schema datatype.
040: * If an error is encountered during conversion, then an IllegalArgumentException
041: * or a subclass of IllegalArgumentException must be thrown by the method.
042: *
043: * </p>
044: *
045: * <p>
046: * A print method for a XML schema datatype can output any lexical
047: * representation that is valid with respect to the XML schema datatype.
048: * If an error is encountered during conversion, then an IllegalArgumentException,
049: * or a subclass of IllegalArgumentException must be thrown by the method.
050: * </p>
051: *
052: * The prefix xsd: is used to refer to XML schema datatypes
053: * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
054: * specification.</a>
055: *
056: * <p>
057: * @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>
058: * @version $Revision: 1.5 $
059: * @see DatatypeConverter
060: * @see ParseConversionEvent
061: * @see PrintConversionEvent
062: * @since JAXB1.0
063: */
064:
065: public interface DatatypeConverterInterface {
066: /**
067: * <p>
068: * Convert the string argument into a string.
069: * @param lexicalXSDString
070: * A lexical representation of the XML Schema datatype xsd:string
071: * @return
072: * A string that is the same as the input string.
073: */
074: public String parseString(String lexicalXSDString);
075:
076: /**
077: * <p>
078: * Convert the string argument into a BigInteger value.
079: * @param lexicalXSDInteger
080: * A string containing a lexical representation of
081: * xsd:integer.
082: * @return
083: * A BigInteger value represented by the string argument.
084: * @throws NumberFormatException <code>lexicalXSDInteger</code> is not a valid string representation of a {@link java.math.BigInteger} value.
085: */
086: public java.math.BigInteger parseInteger(String lexicalXSDInteger);
087:
088: /**
089: * <p>
090: * Convert the string argument into an int value.
091: * @param lexicalXSDInt
092: * A string containing a lexical representation of
093: * xsd:int.
094: * @return
095: * An int value represented byte the string argument.
096: * @throws NumberFormatException <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value.
097: */
098: public int parseInt(String lexicalXSDInt);
099:
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: * <p>
335: * Converts a long value into a string.
336: * @param val
337: * A long value
338: * @return
339: * A string containing a lexical representation of xsd:long
340: */
341: public String printLong(long val);
342:
343: /**
344: * <p>
345: * Converts a short value into a string.
346: * @param val
347: * A short value
348: * @return
349: * A string containing a lexical representation of xsd:short
350: */
351: public String printShort(short val);
352:
353: /**
354: * <p>
355: * Converts a BigDecimal value into a string.
356: * @param val
357: * A BigDecimal value
358: * @return
359: * A string containing a lexical representation of xsd:decimal
360: * @throws IllegalArgumentException <tt>val</tt> is null.
361: */
362: public String printDecimal(java.math.BigDecimal val);
363:
364: /**
365: * <p>
366: * Converts a float value into a string.
367: * @param val
368: * A float value
369: * @return
370: * A string containing a lexical representation of xsd:float
371: */
372: public String printFloat(float val);
373:
374: /**
375: * <p>
376: * Converts a double value into a string.
377: * @param val
378: * A double value
379: * @return
380: * A string containing a lexical representation of xsd:double
381: */
382: public String printDouble(double val);
383:
384: /**
385: * <p>
386: * Converts a boolean value into a string.
387: * @param val
388: * A boolean value
389: * @return
390: * A string containing a lexical representation of xsd:boolean
391: */
392: public String printBoolean(boolean val);
393:
394: /**
395: * <p>
396: * Converts a byte value into a string.
397: * @param val
398: * A byte value
399: * @return
400: * A string containing a lexical representation of xsd:byte
401: */
402: public String printByte(byte val);
403:
404: /**
405: * <p>
406: * Converts a QName instance into a string.
407: * @param val
408: * A QName value
409: * @param nsc
410: * A namespace context for interpreting a prefix within a QName.
411: * @return
412: * A string containing a lexical representation of QName
413: * @throws IllegalArgumentException if <tt>val</tt> is null or
414: * if <tt>nsc</tt> is non-null or <tt>nsc.getPrefix(nsprefixFromVal)</tt> is null.
415: */
416: public String printQName(javax.xml.namespace.QName val,
417: javax.xml.namespace.NamespaceContext nsc);
418:
419: /**
420: * <p>
421: * Converts a Calendar value into a string.
422: * @param val
423: * A Calendar value
424: * @return
425: * A string containing a lexical representation of xsd:dateTime
426: * @throws IllegalArgumentException if <tt>val</tt> is null.
427: */
428: public String printDateTime(java.util.Calendar val);
429:
430: /**
431: * <p>
432: * Converts an array of bytes into a string.
433: * @param val
434: * an array of bytes
435: * @return
436: * A string containing a lexical representation of xsd:base64Binary
437: * @throws IllegalArgumentException if <tt>val</tt> is null.
438: */
439: public String printBase64Binary(byte[] val);
440:
441: /**
442: * <p>
443: * Converts an array of bytes into a string.
444: * @param val
445: * an array of bytes
446: * @return
447: * A string containing a lexical representation of xsd:hexBinary
448: * @throws IllegalArgumentException if <tt>val</tt> is null.
449: */
450: public String printHexBinary(byte[] val);
451:
452: /**
453: * <p>
454: * Converts a long value into a string.
455: * @param val
456: * A long value
457: * @return
458: * A string containing a lexical representation of xsd:unsignedInt
459: */
460: public String printUnsignedInt(long val);
461:
462: /**
463: * <p>
464: * Converts an int value into a string.
465: * @param val
466: * An int value
467: * @return
468: * A string containing a lexical representation of xsd:unsignedShort
469: */
470: public String printUnsignedShort(int val);
471:
472: /**
473: * <p>
474: * Converts a Calendar value into a string.
475: * @param val
476: * A Calendar value
477: * @return
478: * A string containing a lexical representation of xsd:time
479: * @throws IllegalArgumentException if <tt>val</tt> is null.
480: */
481: public String printTime(java.util.Calendar val);
482:
483: /**
484: * <p>
485: * Converts a Calendar value into a string.
486: * @param val
487: * A Calendar value
488: * @return
489: * A string containing a lexical representation of xsd:date
490: * @throws IllegalArgumentException if <tt>val</tt> is null.
491: */
492: public String printDate(java.util.Calendar val);
493:
494: /**
495: * <p>
496: * Converts a string value into a string.
497: * @param val
498: * A string value
499: * @return
500: * A string containing a lexical representation of xsd:AnySimpleType
501: */
502: public String printAnySimpleType(String val);
503: }
|