Source code: javax/xml/bind/DatatypeConverter.java
1 /*
2 * Copyright 2003, 2004 The Apache Software Foundation
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15
16 */
17 package javax.xml.bind;
18
19 import java.math.BigDecimal;
20 import java.math.BigInteger;
21 import java.util.Calendar;
22
23 import javax.xml.namespace.NamespaceContext;
24 import javax.xml.namespace.QName;
25
26 /** <p>This is a helper class for customized datatypes. It provides a
27 * set of static methods which may be useful in custom methods for
28 * parsing and printing values.</p>
29 * <p>The JAXB provider is responsible to initialize the
30 * <code>DatatypeConverter</code> class by invoking
31 * {@link #setDatatypeConverter(DatatypeConverterInterface)} as soon
32 * as possible.</p>
33 *
34 * @author JSR-31
35 * @since JAXB1.0
36 */
37 public final class DatatypeConverter {
38 private static DatatypeConverterInterface converter;
39
40 /** <p>This method must be invoked by the JAXB provider to set the actual
41 * instance, which is invoked by the static methods. Subsequent
42 * invocations of the method are ignored: First come, first wins.</p>
43 * @throws IllegalArgumentException The parameter was null.
44 */
45 public static void setDatatypeConverter(DatatypeConverterInterface pConverter) {
46 if (pConverter == null) {
47 throw new IllegalArgumentException("The parameter must not be null.");
48 }
49 synchronized (DatatypeConverter.class) {
50 if (converter == null) {
51 converter = pConverter;
52 }
53 }
54 }
55
56 /** <p>Parses the lexical representation and converts it into a String.</p>
57 *
58 * @param pLexicalXSDString The input string being parsed.
59 * @return The unmodified input string.
60 * @see javax.xml.bind.ParseConversionEvent
61 */
62 public static String parseString(String pLexicalXSDString) {
63 return converter.parseString(pLexicalXSDString);
64 }
65
66 /** <p>Parses the lexical representation of the given integer value
67 * (arbitrary precision) and converts it into an instance of
68 * {@link java.math.BigInteger}.</p>
69 * @param pLexicalXSDInteger The input string being parsed.
70 * @return The input string converted into an instance of {@link BigInteger}.
71 * @see javax.xml.bind.ParseConversionEvent
72 */
73 public static BigInteger parseInteger(String pLexicalXSDInteger) {
74 return converter.parseInteger(pLexicalXSDInteger);
75 }
76
77 /** <p>Parses the lexical representation of the given 32 bit integer value
78 * and converts it into a primitive <code>int</code> value.</p>
79 * @param pLexicalXSDInt The input string being parsed.
80 * @return The input string converted into a primitive <code>int</code>.
81 * @see javax.xml.bind.ParseConversionEvent
82 */
83 public static int parseInt(String pLexicalXSDInt) {
84 return converter.parseInt(pLexicalXSDInt);
85 }
86
87 /** <p>Parses the lexical representation of the given 64 bit integer value
88 * and converts it into a primitive <code>long</code> value.</p>
89 * @param pLexicalXSDLong The input string being parsed.
90 * @return The input string converted into a primitive <code>long</code>.
91 * @see javax.xml.bind.ParseConversionEvent
92 */
93 public static long parseLong(String pLexicalXSDLong) {
94 return converter.parseLong(pLexicalXSDLong);
95 }
96
97 /** <p>Parses the lexical representation of the given 16 bit integer value
98 * and converts it into a primitive <code>short</code> value.</p>
99 * @param pLexicalXSDShort The input string being parsed.
100 * @return The input string converted into a primitive <code>short</code>.
101 * @see javax.xml.bind.ParseConversionEvent
102 */
103 public static short parseShort(String pLexicalXSDShort) {
104 return converter.parseShort(pLexicalXSDShort);
105 }
106
107 /** <p>Parses the lexical representation of the given decimal value
108 * (arbitrary precision) and converts it into an instance of
109 * {@link java.math.BigDecimal}.</p>
110 * @param pLexicalXSDDecimal The input string being parsed.
111 * @return The input string converted into an instance of {@link java.math.BigDecimal}.
112 * @see javax.xml.bind.ParseConversionEvent
113 */
114 public static BigDecimal parseDecimal(String pLexicalXSDDecimal) {
115 return converter.parseDecimal(pLexicalXSDDecimal);
116 }
117
118 /** <p>Parses the lexical representation of the given 32 bit floating
119 * point value and converts it into a primitive <code>float</code> value.</p>
120 * @param pLexicalXSDFloat The input string being parsed.
121 * @return The input string converted into a primitive <code>float</code>.
122 * @see javax.xml.bind.ParseConversionEvent
123 */
124 public static float parseFloat(String pLexicalXSDFloat) {
125 return converter.parseFloat(pLexicalXSDFloat);
126 }
127
128 /** <p>Parses the lexical representation of the given 64 bit floating
129 * point value and converts it into a primitive <code>double</code> value.</p>
130 * @param pLexicalXSDDouble The input string being parsed.
131 * @return The input string converted into a primitive <code>double</code>.
132 * @see javax.xml.bind.ParseConversionEvent
133 */
134 public static double parseDouble(String pLexicalXSDDouble) {
135 return converter.parseDouble(pLexicalXSDDouble);
136 }
137
138 /** <p>Parses the lexical representation of the given boolean value
139 * and converts it into a primitive <code>boolean</code> value.</p>
140 * @param pLexicalXSDBoolean The input string being parsed.
141 * @return The input string converted into a primitive <code>boolean</code>.
142 * @see javax.xml.bind.ParseConversionEvent
143 */
144 public static boolean parseBoolean(String pLexicalXSDBoolean) {
145 return converter.parseBoolean(pLexicalXSDBoolean);
146 }
147
148 /** <p>Parses the lexical representation of the given 8 bit integer value
149 * and converts it into a primitive <code>byte</code> value.</p>
150 * @param pLexicalXSDByte The input string being parsed.
151 * @return The input string converted into a primitive <code>byte</code>.
152 * @see javax.xml.bind.ParseConversionEvent
153 */
154 public static byte parseByte(String pLexicalXSDByte) {
155 return converter.parseByte(pLexicalXSDByte);
156 }
157
158 /** <p>Parses the lexical representation of the given qualified name
159 * and converts it into an instance of {@link javax.xml.namespace.QName}.
160 * The {@link javax.xml.namespace.QName} consists of a namespace URI
161 * and a local name.</p>
162 * @param pLexicalXSDQName The input string being parsed, an optional
163 * namespace prefix, followed by the local name, if any. If a prefix
164 * is present, they are separated by a colon.
165 * @param pNamespaceContext The namespace context is used to query
166 * mappings between prefixes and namespace URI's.
167 * @return The input string converted into an instance of
168 * {@link javax.xml.namespace.QName}.
169 * @see javax.xml.bind.ParseConversionEvent
170 */
171 public static QName parseQName(String pLexicalXSDQName,
172 NamespaceContext pNamespaceContext) {
173 return converter.parseQName(pLexicalXSDQName, pNamespaceContext);
174 }
175
176 /** <p>Parses the lexical representation of the given dateTime value
177 * and converts it into an instance of {@link java.util.Calendar}.
178 * Valid lexical representations of a dateTime value include
179 * <pre>
180 * YYYY-MM-DDThh:mm:ss
181 * YYYY-MM-DDThh:mm:ss.sss
182 * YYYY-MM-DDThh:mm:ssZ
183 * YYYY-MM-DDThh:mm:ss-01:00
184 * </pre>
185 * The former examples are all specified in UTC time. The last example
186 * uses a negatice offset of one hour to UTC.</p>
187 * @param pLexicalXSDDateTime The input string being parsed.
188 * @return The input string converted into an instance of
189 * {@link java.util.Calendar}.
190 * @see javax.xml.bind.ParseConversionEvent
191 */
192 public static Calendar parseDateTime(String pLexicalXSDDateTime) {
193 return converter.parseDateTime(pLexicalXSDDateTime);
194 }
195
196 /** <p>Parses the lexical representation of the given byte array, which
197 * is encoded in base 64.</p>
198 * @param pLexicalXSDBase64Binary The input string being parsed, a
199 * base 64 encoded array of bytes.
200 * @return The decoded byte array.
201 * @see javax.xml.bind.ParseConversionEvent
202 */
203 public static byte[] parseBase64Binary(String pLexicalXSDBase64Binary) {
204 return converter.parseBase64Binary(pLexicalXSDBase64Binary);
205 }
206
207 /** <p>Parses the lexical representation of the given byte array, which
208 * is encoded in hex digits.</p>
209 * @param pLexicalXSDHexBinary The input string being parsed, an
210 * array of bytes encoded in hex digits.
211 * @return The decoded byte array.
212 * @see javax.xml.bind.ParseConversionEvent
213 */
214 public static byte[] parseHexBinary(String pLexicalXSDHexBinary) {
215 return converter.parseHexBinary(pLexicalXSDHexBinary);
216 }
217
218 /** <p>Parses the lexical representation of the given 32 bit
219 * unsignet integer value and converts it into a primitive <code>long</code>
220 * value.</p>
221 * @param pLexicalXSDUnsignedInt The input string being parsed.
222 * @return The input string converted into a primitive <code>long</code>.
223 * @see javax.xml.bind.ParseConversionEvent
224 */
225 public static long parseUnsignedInt(String pLexicalXSDUnsignedInt) {
226 return converter.parseUnsignedInt(pLexicalXSDUnsignedInt);
227 }
228
229 /** <p>Parses the lexical representation of the given 16 bit
230 * unsignet integer value and converts it into a primitive <code>int</code>
231 * value.</p>
232 * @param pLexicalXSDUnsignedShort The input string being parsed.
233 * @return The input string conve
234 * rted into a primitive <code>int</code>.
235 * @see javax.xml.bind.ParseConversionEvent
236 */
237 public static int parseUnsignedShort(String pLexicalXSDUnsignedShort) {
238 return converter.parseUnsignedShort(pLexicalXSDUnsignedShort);
239 }
240
241 /** <p>Parses the lexical representation of the given time value
242 * and converts it into an instance of {@link java.util.Calendar}.
243 * Valid lexical representations of a time value include
244 * <pre>
245 * hh:mm:ss
246 * hh:mm:ss.sss
247 * hh:mm:ssZ
248 * hh:mm:ss-01:00
249 * </pre>
250 * The former examples are all specified in UTC time. The last example
251 * uses a negatice offset of one hour to UTC.</p>
252 * @param pLexicalXSDTime The input string being parsed.
253 * @return The input string converted into an instance of
254 * {@link java.util.Calendar}.
255 * @see javax.xml.bind.ParseConversionEvent
256 */
257 public static Calendar parseTime(String pLexicalXSDTime) {
258 return converter.parseTime(pLexicalXSDTime);
259 }
260
261 /** <p>Parses the lexical representation of the given date value
262 * and converts it into an instance of {@link java.util.Calendar}.
263 * Valid lexical representations of a date value include
264 * <pre>
265 * YYYY-MM-DD
266 * YYYY-MM-DDZ
267 * YYYY-MM-DD-01:00
268 * </pre>
269 * The former examples are all specified in UTC time. The last example
270 * uses a negatice offset of one hour to UTC.</p>
271 * @param pLexicalXSDDate The input string being parsed.
272 * @return The input string converted into an instance of
273 * {@link java.util.Calendar}.
274 * @see javax.xml.bind.ParseConversionEvent
275 */
276 public static Calendar parseDate(String pLexicalXSDDate) {
277 return converter.parseDate(pLexicalXSDDate);
278 }
279
280 /** <p>Returns the lexical representation of the input string, which is
281 * the unmodified input string.</p>
282 * @param pLexicalXSDAnySimpleType An input string in lexical representation.
283 * @return The unmodified input string.
284 * @see javax.xml.bind.ParseConversionEvent
285 */
286 public static String parseAnySimpleType(String pLexicalXSDAnySimpleType) {
287 return converter.parseAnySimpleType(pLexicalXSDAnySimpleType);
288 }
289
290 /** <p>Returns a lexical representation of the given input string, which
291 * is the unmodified input string.</p>
292 * @param pValue The input string.
293 * @return The unmodified input string.
294 * @see javax.xml.bind.PrintConversionEvent
295 */
296 public static String printString(String pValue) {
297 return converter.printString(pValue);
298 }
299
300 /** <p>Returns a lexical representation of the given instance of
301 * {@link BigInteger}, which is an integer in arbitrary precision.</p>
302 * @param pValue The integer value being converted.
303 * @return A lexical representation of the input value.
304 * @see javax.xml.bind.PrintConversionEvent
305 */
306 public static String printInteger(BigInteger pValue) {
307 return converter.printInteger(pValue);
308 }
309
310 /** <p>Returns a lexical representation of the given primitive
311 * 32 bit integer.</p>
312 * @param pValue The <code>int</code> value being converted.
313 * @return A lexical representation of the input value.
314 * @see javax.xml.bind.PrintConversionEvent
315 */
316 public static String printInt(int pValue) {
317 return converter.printInt(pValue);
318 }
319
320 /** <p>Returns a lexical representation of the given primitive
321 * 64 bit integer.</p>
322 * @param pValue The <code>long</code> value being converted.
323 * @return A lexical representation of the input value.
324 * @see javax.xml.bind.PrintConversionEvent
325 */
326 public static String printLong(long pValue) {
327 return converter.printLong(pValue);
328 }
329
330 /** <p>Returns a lexical representation of the given primitive
331 * 16 bit integer.</p>
332 * @param pValue The <code>short</code> value being converted.
333 * @return A lexical representation of the input value.
334 * @see javax.xml.bind.PrintConversionEvent
335 */
336 public static String printShort(short pValue) {
337 return converter.printShort(pValue);
338 }
339
340 /** <p>Returns a lexical representation of the given instance of
341 * {@link BigDecimal}, which is a decimal number in arbitrary
342 * precision.</p>
343 * @param pValue The decimal value being converted.
344 * @return A lexical representation of the input value.
345 * @see javax.xml.bind.PrintConversionEvent
346 */
347 public static String printDecimal(BigDecimal pValue) {
348 return converter.printDecimal(pValue);
349 }
350
351 /** <p>Returns a lexical representation of the given primitive
352 * 32 bit floating point number.</p>
353 * @param pValue The <code>float</code> value being converted.
354 * @return A lexical representation of the input value.
355 * @see javax.xml.bind.PrintConversionEvent
356 */
357 public static String printFloat(float pValue) {
358 return converter.printFloat(pValue);
359 }
360
361 /** <p>Returns a lexical representation of the given primitive
362 * 64 bit floating point number.</p>
363 * @param pValue The <code>double</code> value being converted.
364 * @return A lexical representation of the input value.
365 * @see javax.xml.bind.PrintConversionEvent
366 */
367 public static String printDouble(double pValue) {
368 return converter.printDouble(pValue);
369 }
370
371 /** <p>Returns a lexical representation of the given primitive
372 * boolean value.</p>
373 * @param pValue The <code>boolean</code> value being converted.
374 * @return A lexical representation of the input value.
375 * @see javax.xml.bind.PrintConversionEvent
376 */
377 public static String printBoolean(boolean pValue) {
378 return converter.printBoolean(pValue);
379 }
380
381 /** <p>Returns a lexical representation of the given primitive
382 * 8 bit integer.</p>
383 * @param pValue The <code>byte</code> value being converted.
384 * @return A lexical representation of the input value.
385 * @see javax.xml.bind.PrintConversionEvent
386 */
387 public static String printByte(byte pValue) {
388 return converter.printByte(pValue);
389 }
390
391 /** <p>Returns a lexical representation of the given qualified
392 * name, which is a combination of namespace URI and local name.
393 * The lexical representation is an optional prefix, which is
394 * currently mapped to namespace URI of the qualified name,
395 * followed by a colon and the local name. If the namespace URI
396 * is the current default namespace URI, then the prefix and
397 * the colon may be omitted.</p>
398 * @param pValue The qualified name being converted.
399 * @param pNamespaceContext A mapping of prefixes to namespace
400 * URI's which may be used to determine a valid prefix.
401 * @return A lexical representation of the qualified name.
402 * @see javax.xml.bind.PrintConversionEvent
403 */
404 public static String printQName(QName pValue,
405 NamespaceContext pNamespaceContext) {
406 return converter.printQName(pValue, pNamespaceContext);
407 }
408
409 /** <p>Returns a lexical representation of the given dateTime
410 * value. Valid lexical representations include:
411 * <pre>
412 * YYYY-MM-DDThh:mm:ss
413 * YYYY-MM-DDThh:mm:ss.sss
414 * YYYY-MM-DDThh:mm:ssZ
415 * YYYY-MM-DDThh:mm:ss-01:00
416 * </pre>
417 * The former examples are all specified in UTC time. The last example
418 * uses a negatice offset of one hour to UTC.</p>
419 * @param pValue The dateTime value being converted
420 * @return A lexical representation of the input value.
421 * @see javax.xml.bind.PrintConversionEvent
422 */
423 public static String printDateTime(Calendar pValue) {
424 return converter.printDateTime(pValue);
425 }
426
427 /** <p>Returns a lexical representation of the given byte array.
428 * The lexical representation is obtained by application of the
429 * base 64 encoding.</p>
430 * @param pValue The byte array being converted.
431 * @return The converted byte array.
432 * @see javax.xml.bind.PrintConversionEvent
433 */
434 public static String printBase64Binary(byte[] pValue) {
435 return converter.printBase64Binary(pValue);
436 }
437
438 /** <p>Returns a lexical representation of the given byte array.
439 * The lexical representation is obtained by encoding any byte
440 * as two hex digits.</p>
441 * @param pValue The byte array being converted.
442 * @return The converted byte array.
443 * @see javax.xml.bind.PrintConversionEvent
444 */
445 public static String printHexBinary(byte[] pValue) {
446 return converter.printHexBinary(pValue);
447 }
448
449 /** <p>Returns a lexical representation of the given primitive,
450 * unsigned 32 bit integer.</p>
451 * @param pValue The <code>long</code> value being converted.
452 * @return A lexical representation of the input value.
453 * @see javax.xml.bind.PrintConversionEvent
454 */
455 public static String printUnsignedInt(long pValue) {
456 return converter.printUnsignedInt(pValue);
457 }
458
459 /** <p>Returns a lexical representation of the given primitive,
460 * unsigned 16 bit integer.</p>
461 * @param pValue The <code>short</code> value being converted.
462 * @return A lexical representation of the input value.
463 * @see javax.xml.bind.PrintConversionEvent
464 */
465 public static String printUnsignedShort(int pValue) {
466 return converter.printUnsignedShort(pValue);
467 }
468
469 /** <p>Returns a lexical representation of the given time
470 * value. Valid lexical representations include:
471 * <pre>
472 * hh:mm:ss
473 * hh:mm:ss.sss
474 * hh:mm:ssZ
475 * hh:mm:ss-01:00
476 * </pre>
477 * The former examples are all specified in UTC time. The last example
478 * uses a negatice offset of one hour to UTC.</p>
479 * @param pValue The time value being converted
480 * @return A lexical representation of the input value.
481 * @see javax.xml.bind.PrintConversionEvent
482 */
483 public static String printTime(Calendar pValue) {
484 return converter.printTime(pValue);
485 }
486
487 /** <p>Returns a lexical representation of the given date
488 * value. Valid lexical representations include:
489 * <pre>
490 * YYYY-MM-DD
491 * YYYY-MM-DDZ
492 * YYYY-MM-DD-01:00
493 * </pre>
494 * The former examples are all specified in UTC time. The last example
495 * uses a negatice offset of one hour to UTC.</p>
496 * @param pValue The date value being converted
497 * @return A lexical representation of the input value.
498 * @see javax.xml.bind.PrintConversionEvent
499 */
500 public static String printDate(Calendar pValue) {
501 return converter.printDate(pValue);
502 }
503
504 /** <p>Returns a lexical representation of the given input
505 * string, which is the unmodified input string.</p>
506 * @param pValue The input string.
507 * @return The unmodified input string.
508 * @see javax.xml.bind.PrintConversionEvent
509 */
510 public static String printAnySimpleType(String pValue) {
511 return converter.printAnySimpleType(pValue);
512 }
513 }