001 /*
002 * $Id: DatatypeConverterInterface.java,v 1.1 2002/12/04 17:04:30 ryans Exp $
003 *
004 * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
005 *
006 * This software is the proprietary information of Sun Microsystems, Inc.
007 * Use is subject to license terms.
008 *
009 */
010
011 package javax.xml.bind;
012
013 /**
014 * <p>
015 * The DatatypeConverterInterface is for JAXB provider use only. A
016 * JAXB provider must supply a class that implements this interface.
017 * JAXB Providers are required to call the
018 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
019 * DatatypeConverter.setDatatypeConverter} api at
020 * some point before the first marshal or unmarshal operation (perhaps during
021 * the call to JAXBContext.newInstance). This step is necessary to configure
022 * the converter that should be used to perform the print and parse
023 * functionality. Calling this api repeatedly will have no effect - the
024 * DatatypeConverter instance passed into the first invocation is the one that
025 * will be used from then on.
026 * </p>
027 *
028 * <p>
029 * This interface defines the parse and print methods. There is one
030 * parse and print method for each XML schema datatype specified in the
031 * the default binding Table 5-1 in the JAXB specification.
032 * </p>
033 *
034 * <p>
035 * The parse and print methods defined here are invoked by the static parse
036 * and print methods defined in the {@link DatatypeConverter DatatypeConverter}
037 * class.
038 * </p>
039 *
040 * <p>
041 * A parse method for a XML schema datatype must be capable of converting any
042 * lexical representation of the XML schema datatype ( specified by the
043 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
044 * specification</a> into a value in the value space of the XML schema datatype.
045 * If an error is encountered during conversion, then a ParseConversionEvent
046 * must be generated.
047 * </p>
048 *
049 * <p>
050 * A print method for a XML schema datatype can output any lexical
051 * representation that is valid with respect to the XML schema datatype.
052 * If an error is encountered during conversion, then a PrintConversionEvent
053 * must be generated.
054 * </p>
055 *
056 * The prefix xsd: is used to refer to XML schema datatypes
057 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
058 * specification.</a>
059 *
060 * <p>
061 * @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>
062 * @version $Revision: 1.1 $
063 * @see DatatypeConverter
064 * @see ParseConversionEvent
065 * @see PrintConversionEvent
066 * @since JAXB1.0
067 */
068
069 public interface DatatypeConverterInterface {
070 /**
071 * <p>
072 * Convert the string argument into a string.
073 * @param lexicalXSDString
074 * A lexical representation of the XML Schema datatype xsd:string
075 * @return
076 * A string that is the same as the input string.
077 */
078 public String parseString( String lexicalXSDString );
079
080 /**
081 * <p>
082 * Convert the string argument into a BigInteger value.
083 * @param
084 * lexicalXSDInteger A string containing a lexical representation of
085 * xsd:integer.
086 * @return
087 * A BigInteger value represented by the string argument.
088 */
089 public java.math.BigInteger parseInteger( String lexicalXSDInteger );
090
091 /**
092 * <p>
093 * Convert the string argument into an int value.
094 * @param
095 * lexicalXSDInt A string containing a lexical representation of
096 * xsd:int.
097 * @return
098 * An int value represented byte the string argument.
099 */
100 public int parseInt( String lexicalXSDInt );
101
102 /**
103 * <p>
104 * Converts the string argument into a long value.
105 * @param
106 * lexicalXSDLong A string containing lexical representation of
107 * xsd:long.
108 * @return
109 * A long value represented by the string argument.
110 */
111 public long parseLong( String lexicalXSLong );
112
113 /**
114 * <p>
115 * Converts the string argument into a short value.
116 * @param
117 * lexicalXSDShort A string containing lexical representation of
118 * xsd:short.
119 * @return
120 * A short value represented by the string argument.
121 */
122 public short parseShort( String lexicalXSDShort );
123
124 /**
125 * <p>
126 * Converts the string argument into a BigDecimal value.
127 * @param
128 * lexicalXSDDecimal A string containing lexical representation of
129 * xsd:decimal.
130 * @return
131 * A BigDecimal value represented by the string argument.
132 */
133 public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal );
134
135 /**
136 * <p>
137 * Converts the string argument into a float value.
138 * @param
139 * lexicalXSDFloat A string containing lexical representation of
140 * xsd:float.
141 * @return
142 * A float value represented by the string argument.
143 */
144 public float parseFloat( String lexicalXSDFloat );
145
146 /**
147 * <p>
148 * Converts the string argument into a double value.
149 * @param
150 * lexicalXSDDouble A string containing lexical representation of
151 * xsd:double.
152 * @return
153 * A double value represented by the string argument.
154 */
155 public double parseDouble( String lexicalXSDDouble );
156
157 /**
158 * <p>
159 * Converts the string argument into a boolean value.
160 * @param
161 * lexicalXSDBoolean A string containing lexical representation of
162 * xsd:boolean.
163 * @return
164 * A boolean value represented by the string argument.
165 */
166 public boolean parseBoolean( String lexicalXSDBoolean );
167
168 /**
169 * <p>
170 * Converts the string argument into a byte value.
171 * @param
172 * lexicalXSDByte A string containing lexical representation of
173 * xsd:byte.
174 * @return
175 * A byte value represented by the string argument.
176 */
177 public byte parseByte( String lexicalXSDByte );
178
179 /**
180 * <p>
181 * Converts the string argument into a QName value.
182 * @param lexicalXSDQName
183 * A string containing lexical representation of xsd:QName.
184 * @param nsc
185 * A namespace context for interpreting a prefix within a QName.
186 * @return
187 * A QName value represented by the string argument.
188 */
189 public javax.xml.namespace.QName parseQName( String lexicalXSDQName,
190 javax.xml.namespace.NamespaceContext nsc);
191
192 /**
193 * <p>
194 * Converts the string argument into a Calendar value.
195 * @param
196 * lexicalXSDDateTime A string containing lexical representation of
197 * xsd:datetime.
198 * @return
199 * A Calendar object represented by the string argument.
200 */
201 public java.util.Calendar parseDateTime( String lexicalXSDDateTime );
202
203 /**
204 * <p>
205 * Converts the string argument into an array of bytes.
206 * @param
207 * lexicalXSDBase64Binary A string containing lexical representation
208 * of xsd:base64Binary.
209 * @return
210 * An array of bytes represented by the string argument.
211 */
212 public byte[] parseBase64Binary( String lexicalXSDBase64Binary );
213
214 /**
215 * <p>
216 * Converts the string argument into an array of bytes.
217 * @param
218 * lexicalXSDHexBinary A string containing lexical representation of
219 * xsd:hexBinary.
220 * @return
221 * An array of bytes represented by the string argument.
222 */
223 public byte[] parseHexBinary( String lexicalXSDHexBinary );
224
225 /**
226 * <p>
227 * Converts the string argument into a long value.
228 * @param
229 * lexicalXSDUnsignedInt A string containing lexical representation
230 * of xsd:unsignedInt.
231 * @return
232 * A long value represented by the string argument.
233 */
234 public long parseUnsignedInt( String lexicalXSDUnsignedInt );
235
236 /**
237 * <p>
238 * Converts the string argument into an int value.
239 * @param
240 * lexicalXSDUnsignedShort -A string containing lexical
241 * representation of xsd:unsignedShort.
242 * @return
243 * An int value represented by the string argument.
244 */
245 public int parseUnsignedShort( String lexicalXSDUnsignedShort );
246
247 /**
248 * <p>
249 * Converts the string argument into a Calendar value.
250 * @param
251 * lexicalXSDTime A string containing lexical representation of
252 * xsd:time.
253 * @return
254 * A Calendar value represented by the string argument.
255 */
256 public java.util.Calendar parseTime( String lexicalXSDTime );
257
258 /**
259 * <p>
260 * Converts the string argument into a Calendar value.
261 * @param
262 * lexicalXSDDate A string containing lexical representation of
263 * xsd:Date.
264 * @return
265 * A Calendar value represented by the string argument.
266 */
267 public java.util.Calendar parseDate( String lexicalXSDDate );
268
269 /**
270 * <p>
271 * Return a string containing the lexical representation of the
272 * simple type.
273 * @param
274 * lexicalXSDAnySimpleType A string containing lexical
275 * representation of the simple type.
276 * @return
277 * A string containing the lexical representation of the
278 * simple type.
279 */
280 public String parseAnySimpleType( String lexicalXSDAnySimpleType );
281
282 /**
283 * <p>
284 * Converts the string argument into a string.
285 * @param val
286 * A string value.
287 * @return
288 * A string containing a lexical representation of xsd:string
289 */
290 public String printString( String val );
291
292 /**
293 * <p>
294 * Converts a BigInteger value into a string.
295 * @param val
296 * A BigInteger value
297 * @return
298 * A string containing a lexical representation of xsd:integer
299 */
300 public String printInteger( java.math.BigInteger val );
301
302 /**
303 * <p>
304 * Converts an int value into a string.
305 * @param val
306 * An int value
307 * @return
308 * A string containing a lexical representation of xsd:int
309 */
310 public String printInt( int val );
311
312
313 /**
314 * <p>
315 * Converts a long value into a string.
316 * @param val
317 * A long value
318 * @return
319 * A string containing a lexical representation of xsd:long
320 */
321 public String printLong( long val );
322
323 /**
324 * <p>
325 * Converts a short value into a string.
326 * @param val
327 * A short value
328 * @return
329 * A string containing a lexical representation of xsd:short
330 */
331 public String printShort( short val );
332
333 /**
334 * <p>
335 * Converts a BigDecimal value into a string.
336 * @param val
337 * A BigDecimal value
338 * @return
339 * A string containing a lexical representation of xsd:decimal
340 */
341 public String printDecimal( java.math.BigDecimal val );
342
343 /**
344 * <p>
345 * Converts a float value into a string.
346 * @param val
347 * A float value
348 * @return
349 * A string containing a lexical representation of xsd:float
350 */
351 public String printFloat( float val );
352
353 /**
354 * <p>
355 * Converts a double value into a string.
356 * @param val
357 * A double value
358 * @return
359 * A string containing a lexical representation of xsd:double
360 */
361 public String printDouble( double val );
362
363 /**
364 * <p>
365 * Converts a boolean value into a string.
366 * @param val
367 * A boolean value
368 * @return
369 * A string containing a lexical representation of xsd:boolean
370 */
371 public String printBoolean( boolean val );
372
373 /**
374 * <p>
375 * Converts a byte value into a string.
376 * @param val
377 * A byte value
378 * @return
379 * A string containing a lexical representation of xsd:byte
380 */
381 public String printByte( byte val );
382
383 /**
384 * <p>
385 * Converts a QName instance into a string.
386 * @param val
387 * A QName value
388 * @param nsc
389 * A namespace context for interpreting a prefix within a QName.
390 * @return
391 * A string containing a lexical representation of QName
392 */
393 public String printQName( javax.xml.namespace.QName val,
394 javax.xml.namespace.NamespaceContext nsc );
395
396 /**
397 * <p>
398 * Converts a Calendar value into a string.
399 * @param val
400 * A Calendar value
401 * @return
402 * A string containing a lexical representation of xsd:dateTime
403 */
404 public String printDateTime( java.util.Calendar val );
405
406 /**
407 * <p>
408 * Converts an array of bytes into a string.
409 * @param val
410 * an array of bytes
411 * @return
412 * A string containing a lexical representation of xsd:base64Binary
413 */
414 public String printBase64Binary( byte[] val );
415
416 /**
417 * <p>
418 * Converts an array of bytes into a string.
419 * @param val
420 * an array of bytes
421 * @return
422 * A string containing a lexical representation of xsd:hexBinary
423 */
424 public String printHexBinary( byte[] val );
425
426 /**
427 * <p>
428 * Converts a long value into a string.
429 * @param val
430 * A long value
431 * @return
432 * A string containing a lexical representation of xsd:unsignedInt
433 */
434 public String printUnsignedInt( long val );
435
436 /**
437 * <p>
438 * Converts an int value into a string.
439 * @param val
440 * An int value
441 * @return
442 * A string containing a lexical representation of xsd:unsignedShort
443 */
444 public String printUnsignedShort( int val );
445
446 /**
447 * <p>
448 * Converts a Calendar value into a string.
449 * @param val
450 * A Calendar value
451 * @return
452 * A string containing a lexical representation of xsd:time
453 */
454 public String printTime( java.util.Calendar val );
455
456 /**
457 * <p>
458 * Converts a Calendar value into a string.
459 * @param val
460 * A Calendar value
461 * @return
462 * A string containing a lexical representation of xsd:date
463 */
464 public String printDate( java.util.Calendar val );
465
466 /**
467 * <p>
468 * Converts a string value into a string.
469 * @param val
470 * A string value
471 * @return
472 * A string containing a lexical representation of xsd:AnySimpleType
473 */
474 public String printAnySimpleType( String val );
475 }