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
26package 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 *
42 * <p>
43 * This interface defines the parse and print methods. There is one
44 * parse and print method for each XML schema datatype specified in the
45 * the default binding Table 5-1 in the JAXB specification.
46 *
47 * <p>
48 * The parse and print methods defined here are invoked by the static parse
49 * and print methods defined in the {@link DatatypeConverter DatatypeConverter}
50 * class.
51 *
52 * <p>
53 * A parse method for a XML schema datatype must be capable of converting any
54 * lexical representation of the XML schema datatype ( specified by the
55 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
56 * specification</a> into a value in the value space of the XML schema datatype.
57 * If an error is encountered during conversion, then an IllegalArgumentException
58 * or a subclass of IllegalArgumentException must be thrown by the method.
59 *
60 * <p>
61 * A print method for a XML schema datatype can output any lexical
62 * representation that is valid with respect to the XML schema datatype.
63 * If an error is encountered during conversion, then an IllegalArgumentException,
64 * or a subclass of IllegalArgumentException must be thrown by the method.
65 *
66 * <p>
67 * The prefix xsd: is used to refer to XML schema datatypes
68 * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
69 * specification.</a>
70 *
71 * @author <ul>
72 *         <li>Sekhar Vajjhala, Sun Microsystems, Inc.</li>
73 *         <li>Joe Fialli, Sun Microsystems Inc.</li>
74 *         <li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li>
75 *         <li>Ryan Shoemaker,Sun Microsystems Inc.</li>
76 *         </ul>
77 * @see DatatypeConverter
78 * @see ParseConversionEvent
79 * @see PrintConversionEvent
80 * @since 1.6, JAXB 1.0
81 */
82
83public interface DatatypeConverterInterface {
84    /**
85     * Convert the string argument into a string.
86     * @param lexicalXSDString
87     *     A lexical representation of the XML Schema datatype xsd:string
88     * @return
89     *     A string that is the same as the input string.
90     */
91    public String parseString( String lexicalXSDString );
92
93    /**
94     * Convert the string argument into a BigInteger value.
95     * @param lexicalXSDInteger
96     *     A string containing a lexical representation of
97     *     xsd:integer.
98     * @return
99     *     A BigInteger value represented by the string argument.
100     * @throws NumberFormatException {@code lexicalXSDInteger} is not a valid string representation of a {@link java.math.BigInteger} value.
101     */
102    public java.math.BigInteger parseInteger( String lexicalXSDInteger );
103
104    /**
105     * Convert the string argument into an int value.
106     * @param lexicalXSDInt
107     *     A string containing a lexical representation of
108     *     xsd:int.
109     * @return
110     *     An int value represented byte the string argument.
111     * @throws NumberFormatException {@code lexicalXSDInt} is not a valid string representation of an {@code int} value.
112     */
113    public int parseInt( String lexicalXSDInt );
114
115    /**
116     * Converts the string argument into a long value.
117     * @param lexicalXSDLong
118     *     A string containing lexical representation of
119     *     xsd:long.
120     * @return
121     *     A long value represented by the string argument.
122     * @throws NumberFormatException {@code lexicalXSDLong} is not a valid string representation of a {@code long} value.
123     */
124    public long parseLong( String lexicalXSDLong );
125
126    /**
127     * Converts the string argument into a short value.
128     * @param lexicalXSDShort
129     *     A string containing lexical representation of
130     *     xsd:short.
131     * @return
132     *     A short value represented by the string argument.
133     * @throws NumberFormatException {@code lexicalXSDShort} is not a valid string representation of a {@code short} value.
134     */
135    public short parseShort( String lexicalXSDShort );
136
137    /**
138     * Converts the string argument into a BigDecimal value.
139     * @param lexicalXSDDecimal
140     *     A string containing lexical representation of
141     *     xsd:decimal.
142     * @return
143     *     A BigDecimal value represented by the string argument.
144     * @throws NumberFormatException {@code lexicalXSDDecimal} is not a valid string representation of {@link java.math.BigDecimal}.
145     */
146    public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal );
147
148    /**
149     * Converts the string argument into a float value.
150     * @param lexicalXSDFloat
151     *     A string containing lexical representation of
152     *     xsd:float.
153     * @return
154     *     A float value represented by the string argument.
155     * @throws NumberFormatException {@code lexicalXSDFloat} is not a valid string representation of a {@code float} value.
156     */
157    public float parseFloat( String lexicalXSDFloat );
158
159    /**
160     * Converts the string argument into a double value.
161     * @param lexicalXSDDouble
162     *     A string containing lexical representation of
163     *     xsd:double.
164     * @return
165     *     A double value represented by the string argument.
166     * @throws NumberFormatException {@code lexicalXSDDouble} is not a valid string representation of a {@code double} value.
167     */
168    public double parseDouble( String lexicalXSDDouble );
169
170    /**
171     * Converts the string argument into a boolean value.
172     * @param lexicalXSDBoolean
173     *     A string containing lexical representation of
174     *     xsd:boolean.
175     * @return
176     *     A boolean value represented by the string argument.
177     * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.
178     */
179    public boolean parseBoolean( String lexicalXSDBoolean );
180
181    /**
182     * Converts the string argument into a byte value.
183     * @param lexicalXSDByte
184     *     A string containing lexical representation of
185     *     xsd:byte.
186     * @return
187     *     A byte value represented by the string argument.
188     * @throws NumberFormatException {@code lexicalXSDByte} does not contain a parseable byte.
189     * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.
190     */
191    public byte parseByte( String lexicalXSDByte );
192
193    /**
194     * Converts the string argument into a QName value.
195     *
196     * <p>
197     * String parameter {@code lexicalXSDQname} must conform to lexical value space specifed at
198     * <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part 2:Datatypes specification:QNames</a>
199     *
200     * @param lexicalXSDQName
201     *     A string containing lexical representation of xsd:QName.
202     * @param nsc
203     *     A namespace context for interpreting a prefix within a QName.
204     * @return
205     *     A QName value represented by the string argument.
206     * @throws IllegalArgumentException  if string parameter does not conform to XML Schema Part 2 specification or
207     *      if namespace prefix of {@code lexicalXSDQname} is not bound to a URI in NamespaceContext {@code nsc}.
208     */
209    public javax.xml.namespace.QName parseQName( String lexicalXSDQName,
210                                             javax.xml.namespace.NamespaceContext nsc);
211
212    /**
213     * Converts the string argument into a Calendar value.
214     * @param lexicalXSDDateTime
215     *     A string containing lexical representation of
216     *     xsd:datetime.
217     * @return
218     *     A Calendar object represented by the string argument.
219     * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.
220     */
221    public java.util.Calendar parseDateTime( String lexicalXSDDateTime );
222
223    /**
224     * Converts the string argument into an array of bytes.
225     * @param lexicalXSDBase64Binary
226     *     A string containing lexical representation
227     *     of xsd:base64Binary.
228     * @return
229     *     An array of bytes represented by the string argument.
230     * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary
231     */
232    public byte[] parseBase64Binary( String lexicalXSDBase64Binary );
233
234    /**
235     * Converts the string argument into an array of bytes.
236     * @param lexicalXSDHexBinary
237     *     A string containing lexical representation of
238     *     xsd:hexBinary.
239     * @return
240     *     An array of bytes represented by the string argument.
241     * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.
242     */
243    public byte[] parseHexBinary( String lexicalXSDHexBinary );
244
245    /**
246     * Converts the string argument into a long value.
247     * @param lexicalXSDUnsignedInt
248     *     A string containing lexical representation
249     *     of xsd:unsignedInt.
250     * @return
251     *     A long value represented by the string argument.
252     * @throws NumberFormatException if string parameter can not be parsed into a {@code long} value.
253     */
254    public long parseUnsignedInt( String lexicalXSDUnsignedInt );
255
256    /**
257     * Converts the string argument into an int value.
258     * @param lexicalXSDUnsignedShort
259     *     A string containing lexical
260     *     representation of xsd:unsignedShort.
261     * @return
262     *     An int value represented by the string argument.
263     * @throws NumberFormatException if string parameter can not be parsed into an {@code int} value.
264     */
265    public int parseUnsignedShort( String lexicalXSDUnsignedShort );
266
267    /**
268     * Converts the string argument into a Calendar value.
269     * @param lexicalXSDTime
270     *     A string containing lexical representation of
271     *     xsd:Time.
272     * @return
273     *     A Calendar value represented by the string argument.
274     * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.
275     */
276    public java.util.Calendar parseTime( String lexicalXSDTime );
277
278    /**
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     * Return a string containing the lexical representation of the
291     * simple type.
292     * @param lexicalXSDAnySimpleType
293     *     A string containing lexical
294     *     representation of the simple type.
295     * @return
296     *     A string containing the lexical representation of the
297     *     simple type.
298     */
299    public String parseAnySimpleType( String lexicalXSDAnySimpleType );
300
301    /**
302     * Converts the string argument into a string.
303     * @param val
304     *     A string value.
305     * @return
306     *     A string containing a lexical representation of xsd:string
307     */
308    public String printString( String val );
309
310    /**
311     * Converts a BigInteger value into a string.
312     * @param val
313     *     A BigInteger value
314     * @return
315     *     A string containing a lexical representation of xsd:integer
316     * @throws IllegalArgumentException {@code val} is null.
317     */
318    public String printInteger( java.math.BigInteger val );
319
320    /**
321     * Converts an int value into a string.
322     * @param val
323     *     An int value
324     * @return
325     *     A string containing a lexical representation of xsd:int
326     */
327    public String printInt( int val );
328
329
330    /**
331     * Converts a long value into a string.
332     * @param val
333     *     A long value
334     * @return
335     *     A string containing a lexical representation of xsd:long
336     */
337    public String printLong( long val );
338
339    /**
340     * Converts a short value into a string.
341     * @param val
342     *     A short value
343     * @return
344     *     A string containing a lexical representation of xsd:short
345     */
346    public String printShort( short val );
347
348    /**
349     * Converts a BigDecimal value into a string.
350     * @param val
351     *     A BigDecimal value
352     * @return
353     *     A string containing a lexical representation of xsd:decimal
354     * @throws IllegalArgumentException {@code val} is null.
355     */
356    public String printDecimal( java.math.BigDecimal val );
357
358    /**
359     * Converts a float value into a string.
360     * @param val
361     *     A float value
362     * @return
363     *     A string containing a lexical representation of xsd:float
364     */
365    public String printFloat( float val );
366
367    /**
368     * Converts a double value into a string.
369     * @param val
370     *     A double value
371     * @return
372     *     A string containing a lexical representation of xsd:double
373     */
374    public String printDouble( double val );
375
376    /**
377     * Converts a boolean value into a string.
378     * @param val
379     *     A boolean value
380     * @return
381     *     A string containing a lexical representation of xsd:boolean
382     */
383    public String printBoolean( boolean val );
384
385    /**
386     * Converts a byte value into a string.
387     * @param val
388     *     A byte value
389     * @return
390     *     A string containing a lexical representation of xsd:byte
391     */
392    public String printByte( byte val );
393
394    /**
395     * Converts a QName instance into a string.
396     * @param val
397     *     A QName value
398     * @param nsc
399     *     A namespace context for interpreting a prefix within a QName.
400     * @return
401     *     A string containing a lexical representation of QName
402     * @throws IllegalArgumentException if {@code val} is null or
403     * if {@code nsc} is non-null or {@code nsc.getPrefix(nsprefixFromVal)} is null.
404     */
405    public String printQName( javax.xml.namespace.QName val,
406                              javax.xml.namespace.NamespaceContext nsc );
407
408    /**
409     * Converts a Calendar value into a string.
410     * @param val
411     *     A Calendar value
412     * @return
413     *     A string containing a lexical representation of xsd:dateTime
414     * @throws IllegalArgumentException if {@code val} is null.
415     */
416    public String printDateTime( java.util.Calendar val );
417
418    /**
419     * Converts an array of bytes into a string.
420     * @param val
421     *     an array of bytes
422     * @return
423     *     A string containing a lexical representation of xsd:base64Binary
424     * @throws IllegalArgumentException if {@code val} is null.
425     */
426    public String printBase64Binary( byte[] val );
427
428    /**
429     * Converts an array of bytes into a string.
430     * @param val
431     *     an array of bytes
432     * @return
433     *     A string containing a lexical representation of xsd:hexBinary
434     * @throws IllegalArgumentException if {@code val} is null.
435     */
436    public String printHexBinary( byte[] val );
437
438    /**
439     * Converts a long value into a string.
440     * @param val
441     *     A long value
442     * @return
443     *     A string containing a lexical representation of xsd:unsignedInt
444     */
445    public String printUnsignedInt( long val );
446
447    /**
448     * Converts an int value into a string.
449     * @param val
450     *     An int value
451     * @return
452     *     A string containing a lexical representation of xsd:unsignedShort
453     */
454    public String printUnsignedShort( int val );
455
456    /**
457     * Converts a Calendar value into a string.
458     * @param val
459     *     A Calendar value
460     * @return
461     *     A string containing a lexical representation of xsd:time
462     * @throws IllegalArgumentException if {@code val} is null.
463     */
464    public String printTime( java.util.Calendar val );
465
466    /**
467     * Converts a Calendar value into a string.
468     * @param val
469     *     A Calendar value
470     * @return
471     *     A string containing a lexical representation of xsd:date
472     * @throws IllegalArgumentException if {@code val} is null.
473     */
474    public String printDate( java.util.Calendar val );
475
476    /**
477     * Converts a string value into a string.
478     * @param val
479     *     A string value
480     * @return
481     *     A string containing a lexical representation of xsd:AnySimpleType
482     */
483    public String printAnySimpleType( String val );
484}
485