51 * <p>
52 * Methods defined in this class are convenience methods that combine several basic operations
53 * in the {@link JAXBContext}, {@link Unmarshaller}, and {@link Marshaller}.
54 *
55 * They are designed
56 * to be the prefered methods for developers new to JAXB. They have
57 * the following characterstics:
58 *
59 * <ol>
60 * <li>Generally speaking, the performance is not necessarily optimal.
61 * It is expected that people who need to write performance
62 * critical code will use the rest of the JAXB API directly.
63 * <li>Errors that happen during the processing is wrapped into
64 * {@link DataBindingException} (which will have {@link JAXBException}
65 * as its {@link Throwable#getCause() cause}. It is expected that
66 * people who prefer the checked exception would use
67 * the rest of the JAXB API directly.
68 * </ol>
69 *
70 * <p>
71 * In addition, the <tt>unmarshal</tt> methods have the following characteristic:
72 *
73 * <ol>
74 * <li>Schema validation is not performed on the input XML.
75 * The processing will try to continue even if there
76 * are errors in the XML, as much as possible. Only as
77 * the last resort, this method fails with {@link DataBindingException}.
78 * </ol>
79 *
80 * <p>
81 * Similarly, the <tt>marshal</tt> methods have the following characteristic:
82 * <ol>
83 * <li>The processing will try to continue even if the Java object tree
84 * does not meet the validity requirement. Only as
85 * the last resort, this method fails with {@link DataBindingException}.
86 * </ol>
87 *
88 *
89 * <p>
90 * All the methods on this class require non-null arguments to all parameters.
91 * The <tt>unmarshal</tt> methods either fail with an exception or return
92 * a non-null value.
93 *
94 * @author Kohsuke Kawaguchi
95 * @since 1.6, JAXB 2.1
96 */
97 public final class JAXB {
98 /**
99 * No instanciation is allowed.
100 */
101 private JAXB() {}
102
103 /**
104 * To improve the performance, we'll cache the last {@link JAXBContext} used.
105 */
106 private static final class Cache {
107 final Class type;
108 final JAXBContext context;
109
110 public Cache(Class type) throws JAXBException {
111 this.type = type;
162 *
163 * @param xml
164 * The resource pointed by the URL is read in its entirety.
165 */
166 public static <T> T unmarshal( URL xml, Class<T> type ) {
167 try {
168 JAXBElement<T> item = getContext(type).createUnmarshaller().unmarshal(toSource(xml), type);
169 return item.getValue();
170 } catch (JAXBException e) {
171 throw new DataBindingException(e);
172 } catch (IOException e) {
173 throw new DataBindingException(e);
174 }
175 }
176
177 /**
178 * Reads in a Java object tree from the given XML input.
179 *
180 * @param xml
181 * The URI is {@link URI#toURL() turned into URL} and then
182 * follows the handling of <tt>URL</tt>.
183 */
184 public static <T> T unmarshal( URI xml, Class<T> type ) {
185 try {
186 JAXBElement<T> item = getContext(type).createUnmarshaller().unmarshal(toSource(xml), type);
187 return item.getValue();
188 } catch (JAXBException e) {
189 throw new DataBindingException(e);
190 } catch (IOException e) {
191 throw new DataBindingException(e);
192 }
193 }
194
195 /**
196 * Reads in a Java object tree from the given XML input.
197 *
198 * @param xml
199 * The string is first interpreted as an absolute <tt>URI</tt>.
200 * If it's not {@link URI#isAbsolute() a valid absolute URI},
201 * then it's interpreted as a <tt>File</tt>
202 */
203 public static <T> T unmarshal( String xml, Class<T> type ) {
204 try {
205 JAXBElement<T> item = getContext(type).createUnmarshaller().unmarshal(toSource(xml), type);
206 return item.getValue();
207 } catch (JAXBException e) {
208 throw new DataBindingException(e);
209 } catch (IOException e) {
210 throw new DataBindingException(e);
211 }
212 }
213
214 /**
215 * Reads in a Java object tree from the given XML input.
216 *
217 * @param xml
218 * The entire stream is read as an XML infoset.
219 * Upon a successful completion, the stream will be closed by this method.
220 */
221 public static <T> T unmarshal( InputStream xml, Class<T> type ) {
330 */
331 public static void marshal( Object jaxbObject, File xml ) {
332 _marshal(jaxbObject,xml);
333 }
334
335 /**
336 * Writes a Java object tree to XML and store it to the specified location.
337 *
338 * @param jaxbObject
339 * The Java object to be marshalled into XML. If this object is
340 * a {@link JAXBElement}, it will provide the root tag name and
341 * the body. If this object has {@link XmlRootElement}
342 * on its class definition, that will be used as the root tag name
343 * and the given object will provide the body. Otherwise,
344 * the root tag name is {@link Introspector#decapitalize(String) infered} from
345 * {@link Class#getSimpleName() the short class name}.
346 * This parameter must not be null.
347 *
348 * @param xml
349 * The XML will be {@link URLConnection#getOutputStream() sent} to the
350 * resource pointed by this URL. Note that not all <tt>URL</tt>s support
351 * such operation, and exact semantics depends on the <tt>URL</tt>
352 * implementations. In case of {@link HttpURLConnection HTTP URLs},
353 * this will perform HTTP POST.
354 *
355 * @throws DataBindingException
356 * If the operation fails, such as due to I/O error, unbindable classes.
357 */
358 public static void marshal( Object jaxbObject, URL xml ) {
359 _marshal(jaxbObject,xml);
360 }
361
362 /**
363 * Writes a Java object tree to XML and store it to the specified location.
364 *
365 * @param jaxbObject
366 * The Java object to be marshalled into XML. If this object is
367 * a {@link JAXBElement}, it will provide the root tag name and
368 * the body. If this object has {@link XmlRootElement}
369 * on its class definition, that will be used as the root tag name
370 * and the given object will provide the body. Otherwise,
371 * the root tag name is {@link Introspector#decapitalize(String) infered} from
372 * {@link Class#getSimpleName() the short class name}.
373 * This parameter must not be null.
374 *
375 * @param xml
376 * The URI is {@link URI#toURL() turned into URL} and then
377 * follows the handling of <tt>URL</tt>. See above.
378 *
379 * @throws DataBindingException
380 * If the operation fails, such as due to I/O error, unbindable classes.
381 */
382 public static void marshal( Object jaxbObject, URI xml ) {
383 _marshal(jaxbObject,xml);
384 }
385
386 /**
387 * Writes a Java object tree to XML and store it to the specified location.
388 *
389 * @param jaxbObject
390 * The Java object to be marshalled into XML. If this object is
391 * a {@link JAXBElement}, it will provide the root tag name and
392 * the body. If this object has {@link XmlRootElement}
393 * on its class definition, that will be used as the root tag name
394 * and the given object will provide the body. Otherwise,
395 * the root tag name is {@link Introspector#decapitalize(String) infered} from
396 * {@link Class#getSimpleName() the short class name}.
397 * This parameter must not be null.
398 *
399 * @param xml
400 * The string is first interpreted as an absolute <tt>URI</tt>.
401 * If it's not {@link URI#isAbsolute() a valid absolute URI},
402 * then it's interpreted as a <tt>File</tt>
403 *
404 * @throws DataBindingException
405 * If the operation fails, such as due to I/O error, unbindable classes.
406 */
407 public static void marshal( Object jaxbObject, String xml ) {
408 _marshal(jaxbObject,xml);
409 }
410
411 /**
412 * Writes a Java object tree to XML and store it to the specified location.
413 *
414 * @param jaxbObject
415 * The Java object to be marshalled into XML. If this object is
416 * a {@link JAXBElement}, it will provide the root tag name and
417 * the body. If this object has {@link XmlRootElement}
418 * on its class definition, that will be used as the root tag name
419 * and the given object will provide the body. Otherwise,
420 * the root tag name is {@link Introspector#decapitalize(String) infered} from
421 * {@link Class#getSimpleName() the short class name}.
422 * This parameter must not be null.
505 * the body. If this object has {@link XmlRootElement}
506 * on its class definition, that will be used as the root tag name
507 * and the given object will provide the body. Otherwise,
508 * the root tag name is {@link Introspector#decapitalize(String) infered} from
509 * {@link Class#getSimpleName() the short class name}.
510 * This parameter must not be null.
511 *
512 * @param xml
513 * Represents the receiver of XML. Objects of the following types are allowed.
514 *
515 * <table><tr>
516 * <th>Type</th>
517 * <th>Operation</th>
518 * </tr><tr>
519 * <td>{@link File}</td>
520 * <td>XML will be written to this file. If it already exists,
521 * it will be overwritten.</td>
522 * </tr><tr>
523 * <td>{@link URL}</td>
524 * <td>The XML will be {@link URLConnection#getOutputStream() sent} to the
525 * resource pointed by this URL. Note that not all <tt>URL</tt>s support
526 * such operation, and exact semantics depends on the <tt>URL</tt>
527 * implementations. In case of {@link HttpURLConnection HTTP URLs},
528 * this will perform HTTP POST.</td>
529 * </tr><tr>
530 * <td>{@link URI}</td>
531 * <td>The URI is {@link URI#toURL() turned into URL} and then
532 * follows the handling of <tt>URL</tt>. See above.</td>
533 * </tr><tr>
534 * <td>{@link String}</td>
535 * <td>The string is first interpreted as an absolute <tt>URI</tt>.
536 * If it's not {@link URI#isAbsolute() a valid absolute URI},
537 * then it's interpreted as a <tt>File</tt></td>
538 * </tr><tr>
539 * <td>{@link OutputStream}</td>
540 * <td>The XML will be sent to the given {@link OutputStream}.
541 * Upon a successful completion, the stream will be closed by this method.</td>
542 * </tr><tr>
543 * <td>{@link Writer}</td>
544 * <td>The XML will be sent as a character stream to the given {@link Writer}.
545 * Upon a successful completion, the stream will be closed by this method.</td>
546 * </tr><tr>
547 * <td>{@link Result}</td>
548 * <td>The XML will be sent to the {@link Result} object.</td>
549 * </tr></table>
550 *
551 * @throws DataBindingException
552 * If the operation fails, such as due to I/O error, unbindable classes.
553 */
554 private static void _marshal( Object jaxbObject, Object xml ) {
555 try {
556 JAXBContext context;
557
|
51 * <p>
52 * Methods defined in this class are convenience methods that combine several basic operations
53 * in the {@link JAXBContext}, {@link Unmarshaller}, and {@link Marshaller}.
54 *
55 * They are designed
56 * to be the prefered methods for developers new to JAXB. They have
57 * the following characterstics:
58 *
59 * <ol>
60 * <li>Generally speaking, the performance is not necessarily optimal.
61 * It is expected that people who need to write performance
62 * critical code will use the rest of the JAXB API directly.
63 * <li>Errors that happen during the processing is wrapped into
64 * {@link DataBindingException} (which will have {@link JAXBException}
65 * as its {@link Throwable#getCause() cause}. It is expected that
66 * people who prefer the checked exception would use
67 * the rest of the JAXB API directly.
68 * </ol>
69 *
70 * <p>
71 * In addition, the {@code unmarshal} methods have the following characteristic:
72 *
73 * <ol>
74 * <li>Schema validation is not performed on the input XML.
75 * The processing will try to continue even if there
76 * are errors in the XML, as much as possible. Only as
77 * the last resort, this method fails with {@link DataBindingException}.
78 * </ol>
79 *
80 * <p>
81 * Similarly, the {@code marshal} methods have the following characteristic:
82 * <ol>
83 * <li>The processing will try to continue even if the Java object tree
84 * does not meet the validity requirement. Only as
85 * the last resort, this method fails with {@link DataBindingException}.
86 * </ol>
87 *
88 *
89 * <p>
90 * All the methods on this class require non-null arguments to all parameters.
91 * The {@code unmarshal} methods either fail with an exception or return
92 * a non-null value.
93 *
94 * @author Kohsuke Kawaguchi
95 * @since 1.6, JAXB 2.1
96 */
97 public final class JAXB {
98 /**
99 * No instanciation is allowed.
100 */
101 private JAXB() {}
102
103 /**
104 * To improve the performance, we'll cache the last {@link JAXBContext} used.
105 */
106 private static final class Cache {
107 final Class type;
108 final JAXBContext context;
109
110 public Cache(Class type) throws JAXBException {
111 this.type = type;
162 *
163 * @param xml
164 * The resource pointed by the URL is read in its entirety.
165 */
166 public static <T> T unmarshal( URL xml, Class<T> type ) {
167 try {
168 JAXBElement<T> item = getContext(type).createUnmarshaller().unmarshal(toSource(xml), type);
169 return item.getValue();
170 } catch (JAXBException e) {
171 throw new DataBindingException(e);
172 } catch (IOException e) {
173 throw new DataBindingException(e);
174 }
175 }
176
177 /**
178 * Reads in a Java object tree from the given XML input.
179 *
180 * @param xml
181 * The URI is {@link URI#toURL() turned into URL} and then
182 * follows the handling of {@code URL}.
183 */
184 public static <T> T unmarshal( URI xml, Class<T> type ) {
185 try {
186 JAXBElement<T> item = getContext(type).createUnmarshaller().unmarshal(toSource(xml), type);
187 return item.getValue();
188 } catch (JAXBException e) {
189 throw new DataBindingException(e);
190 } catch (IOException e) {
191 throw new DataBindingException(e);
192 }
193 }
194
195 /**
196 * Reads in a Java object tree from the given XML input.
197 *
198 * @param xml
199 * The string is first interpreted as an absolute {@code URI}.
200 * If it's not {@link URI#isAbsolute() a valid absolute URI},
201 * then it's interpreted as a {@code File}
202 */
203 public static <T> T unmarshal( String xml, Class<T> type ) {
204 try {
205 JAXBElement<T> item = getContext(type).createUnmarshaller().unmarshal(toSource(xml), type);
206 return item.getValue();
207 } catch (JAXBException e) {
208 throw new DataBindingException(e);
209 } catch (IOException e) {
210 throw new DataBindingException(e);
211 }
212 }
213
214 /**
215 * Reads in a Java object tree from the given XML input.
216 *
217 * @param xml
218 * The entire stream is read as an XML infoset.
219 * Upon a successful completion, the stream will be closed by this method.
220 */
221 public static <T> T unmarshal( InputStream xml, Class<T> type ) {
330 */
331 public static void marshal( Object jaxbObject, File xml ) {
332 _marshal(jaxbObject,xml);
333 }
334
335 /**
336 * Writes a Java object tree to XML and store it to the specified location.
337 *
338 * @param jaxbObject
339 * The Java object to be marshalled into XML. If this object is
340 * a {@link JAXBElement}, it will provide the root tag name and
341 * the body. If this object has {@link XmlRootElement}
342 * on its class definition, that will be used as the root tag name
343 * and the given object will provide the body. Otherwise,
344 * the root tag name is {@link Introspector#decapitalize(String) infered} from
345 * {@link Class#getSimpleName() the short class name}.
346 * This parameter must not be null.
347 *
348 * @param xml
349 * The XML will be {@link URLConnection#getOutputStream() sent} to the
350 * resource pointed by this URL. Note that not all {@code URL}s support
351 * such operation, and exact semantics depends on the {@code URL}
352 * implementations. In case of {@link HttpURLConnection HTTP URLs},
353 * this will perform HTTP POST.
354 *
355 * @throws DataBindingException
356 * If the operation fails, such as due to I/O error, unbindable classes.
357 */
358 public static void marshal( Object jaxbObject, URL xml ) {
359 _marshal(jaxbObject,xml);
360 }
361
362 /**
363 * Writes a Java object tree to XML and store it to the specified location.
364 *
365 * @param jaxbObject
366 * The Java object to be marshalled into XML. If this object is
367 * a {@link JAXBElement}, it will provide the root tag name and
368 * the body. If this object has {@link XmlRootElement}
369 * on its class definition, that will be used as the root tag name
370 * and the given object will provide the body. Otherwise,
371 * the root tag name is {@link Introspector#decapitalize(String) infered} from
372 * {@link Class#getSimpleName() the short class name}.
373 * This parameter must not be null.
374 *
375 * @param xml
376 * The URI is {@link URI#toURL() turned into URL} and then
377 * follows the handling of {@code URL}. See above.
378 *
379 * @throws DataBindingException
380 * If the operation fails, such as due to I/O error, unbindable classes.
381 */
382 public static void marshal( Object jaxbObject, URI xml ) {
383 _marshal(jaxbObject,xml);
384 }
385
386 /**
387 * Writes a Java object tree to XML and store it to the specified location.
388 *
389 * @param jaxbObject
390 * The Java object to be marshalled into XML. If this object is
391 * a {@link JAXBElement}, it will provide the root tag name and
392 * the body. If this object has {@link XmlRootElement}
393 * on its class definition, that will be used as the root tag name
394 * and the given object will provide the body. Otherwise,
395 * the root tag name is {@link Introspector#decapitalize(String) infered} from
396 * {@link Class#getSimpleName() the short class name}.
397 * This parameter must not be null.
398 *
399 * @param xml
400 * The string is first interpreted as an absolute {@code URI}.
401 * If it's not {@link URI#isAbsolute() a valid absolute URI},
402 * then it's interpreted as a {@code File}
403 *
404 * @throws DataBindingException
405 * If the operation fails, such as due to I/O error, unbindable classes.
406 */
407 public static void marshal( Object jaxbObject, String xml ) {
408 _marshal(jaxbObject,xml);
409 }
410
411 /**
412 * Writes a Java object tree to XML and store it to the specified location.
413 *
414 * @param jaxbObject
415 * The Java object to be marshalled into XML. If this object is
416 * a {@link JAXBElement}, it will provide the root tag name and
417 * the body. If this object has {@link XmlRootElement}
418 * on its class definition, that will be used as the root tag name
419 * and the given object will provide the body. Otherwise,
420 * the root tag name is {@link Introspector#decapitalize(String) infered} from
421 * {@link Class#getSimpleName() the short class name}.
422 * This parameter must not be null.
505 * the body. If this object has {@link XmlRootElement}
506 * on its class definition, that will be used as the root tag name
507 * and the given object will provide the body. Otherwise,
508 * the root tag name is {@link Introspector#decapitalize(String) infered} from
509 * {@link Class#getSimpleName() the short class name}.
510 * This parameter must not be null.
511 *
512 * @param xml
513 * Represents the receiver of XML. Objects of the following types are allowed.
514 *
515 * <table><tr>
516 * <th>Type</th>
517 * <th>Operation</th>
518 * </tr><tr>
519 * <td>{@link File}</td>
520 * <td>XML will be written to this file. If it already exists,
521 * it will be overwritten.</td>
522 * </tr><tr>
523 * <td>{@link URL}</td>
524 * <td>The XML will be {@link URLConnection#getOutputStream() sent} to the
525 * resource pointed by this URL. Note that not all {@code URL}s support
526 * such operation, and exact semantics depends on the {@code URL}
527 * implementations. In case of {@link HttpURLConnection HTTP URLs},
528 * this will perform HTTP POST.</td>
529 * </tr><tr>
530 * <td>{@link URI}</td>
531 * <td>The URI is {@link URI#toURL() turned into URL} and then
532 * follows the handling of {@code URL}. See above.</td>
533 * </tr><tr>
534 * <td>{@link String}</td>
535 * <td>The string is first interpreted as an absolute {@code URI}.
536 * If it's not {@link URI#isAbsolute() a valid absolute URI},
537 * then it's interpreted as a {@code File}</td>
538 * </tr><tr>
539 * <td>{@link OutputStream}</td>
540 * <td>The XML will be sent to the given {@link OutputStream}.
541 * Upon a successful completion, the stream will be closed by this method.</td>
542 * </tr><tr>
543 * <td>{@link Writer}</td>
544 * <td>The XML will be sent as a character stream to the given {@link Writer}.
545 * Upon a successful completion, the stream will be closed by this method.</td>
546 * </tr><tr>
547 * <td>{@link Result}</td>
548 * <td>The XML will be sent to the {@link Result} object.</td>
549 * </tr></table>
550 *
551 * @throws DataBindingException
552 * If the operation fails, such as due to I/O error, unbindable classes.
553 */
554 private static void _marshal( Object jaxbObject, Object xml ) {
555 try {
556 JAXBContext context;
557
|