356 * {@code javax.xml.transform.Result}.
357 *
358 * <p>
359 * All JAXB Providers must at least support
360 * {@link javax.xml.transform.dom.DOMResult},
361 * {@link javax.xml.transform.sax.SAXResult}, and
362 * {@link javax.xml.transform.stream.StreamResult}. It can
363 * support other derived classes of {@code Result} as well.
364 *
365 * @param jaxbElement
366 * The root of content tree to be marshalled.
367 * @param result
368 * XML will be sent to this Result
369 *
370 * @throws JAXBException
371 * If any unexpected problem occurs during the marshalling.
372 * @throws MarshalException
373 * If the {@link ValidationEventHandler ValidationEventHandler}
374 * returns false from its {@code handleEvent} method or the
375 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
376 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
377 * Marshalling a JAXB element</a>.
378 * @throws IllegalArgumentException
379 * If any of the method parameters are null
380 */
381 public void marshal( Object jaxbElement, javax.xml.transform.Result result )
382 throws JAXBException;
383
384 /**
385 * Marshal the content tree rooted at {@code jaxbElement} into an output stream.
386 *
387 * @param jaxbElement
388 * The root of content tree to be marshalled.
389 * @param os
390 * XML will be added to this stream.
391 *
392 * @throws JAXBException
393 * If any unexpected problem occurs during the marshalling.
394 * @throws MarshalException
395 * If the {@link ValidationEventHandler ValidationEventHandler}
396 * returns false from its {@code handleEvent} method or the
397 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
398 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
399 * Marshalling a JAXB element</a>.
400 * @throws IllegalArgumentException
401 * If any of the method parameters are null
402 */
403 public void marshal( Object jaxbElement, java.io.OutputStream os )
404 throws JAXBException;
405
406 /**
407 * Marshal the content tree rooted at {@code jaxbElement} into a file.
408 *
409 * @param jaxbElement
410 * The root of content tree to be marshalled.
411 * @param output
412 * File to be written. If this file already exists, it will be overwritten.
413 *
414 * @throws JAXBException
415 * If any unexpected problem occurs during the marshalling.
416 * @throws MarshalException
417 * If the {@link ValidationEventHandler ValidationEventHandler}
418 * returns false from its {@code handleEvent} method or the
419 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
420 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
421 * Marshalling a JAXB element</a>.
422 * @throws IllegalArgumentException
423 * If any of the method parameters are null
424 * @since 1.6, JAXB 2.1
425 */
426 public void marshal( Object jaxbElement, File output )
427 throws JAXBException;
428
429 /**
430 * Marshal the content tree rooted at {@code jaxbElement} into a Writer.
431 *
432 * @param jaxbElement
433 * The root of content tree to be marshalled.
434 * @param writer
435 * XML will be sent to this writer.
436 *
437 * @throws JAXBException
438 * If any unexpected problem occurs during the marshalling.
439 * @throws MarshalException
440 * If the {@link ValidationEventHandler ValidationEventHandler}
441 * returns false from its {@code handleEvent} method or the
442 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
443 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
444 * Marshalling a JAXB element</a>.
445 * @throws IllegalArgumentException
446 * If any of the method parameters are null
447 */
448 public void marshal( Object jaxbElement, java.io.Writer writer )
449 throws JAXBException;
450
451 /**
452 * Marshal the content tree rooted at {@code jaxbElement} into SAX2 events.
453 *
454 * @param jaxbElement
455 * The root of content tree to be marshalled.
456 * @param handler
457 * XML will be sent to this handler as SAX2 events.
458 *
459 * @throws JAXBException
460 * If any unexpected problem occurs during the marshalling.
461 * @throws MarshalException
462 * If the {@link ValidationEventHandler ValidationEventHandler}
463 * returns false from its {@code handleEvent} method or the
464 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
465 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
466 * Marshalling a JAXB element</a>.
467 * @throws IllegalArgumentException
468 * If any of the method parameters are null
469 */
470 public void marshal( Object jaxbElement, org.xml.sax.ContentHandler handler )
471 throws JAXBException;
472
473 /**
474 * Marshal the content tree rooted at {@code jaxbElement} into a DOM tree.
475 *
476 * @param jaxbElement
477 * The content tree to be marshalled.
478 * @param node
479 * DOM nodes will be added as children of this node.
480 * This parameter must be a Node that accepts children
481 * ({@link org.w3c.dom.Document},
482 * {@link org.w3c.dom.DocumentFragment}, or
483 * {@link org.w3c.dom.Element})
484 *
485 * @throws JAXBException
486 * If any unexpected problem occurs during the marshalling.
487 * @throws MarshalException
488 * If the {@link ValidationEventHandler ValidationEventHandler}
489 * returns false from its {@code handleEvent} method or the
490 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
491 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
492 * Marshalling a JAXB element</a>.
493 * @throws IllegalArgumentException
494 * If any of the method parameters are null
495 */
496 public void marshal( Object jaxbElement, org.w3c.dom.Node node )
497 throws JAXBException;
498
499 /**
500 * Marshal the content tree rooted at {@code jaxbElement} into a
501 * {@link javax.xml.stream.XMLStreamWriter}.
502 *
503 * @param jaxbElement
504 * The content tree to be marshalled.
505 * @param writer
506 * XML will be sent to this writer.
507 *
508 * @throws JAXBException
509 * If any unexpected problem occurs during the marshalling.
510 * @throws MarshalException
511 * If the {@link ValidationEventHandler ValidationEventHandler}
512 * returns false from its {@code handleEvent} method or the
513 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
514 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
515 * Marshalling a JAXB element</a>.
516 * @throws IllegalArgumentException
517 * If any of the method parameters are null
518 * @since 1.6, JAXB 2.0
519 */
520 public void marshal( Object jaxbElement, javax.xml.stream.XMLStreamWriter writer )
521 throws JAXBException;
522
523 /**
524 * Marshal the content tree rooted at {@code jaxbElement} into a
525 * {@link javax.xml.stream.XMLEventWriter}.
526 *
527 * @param jaxbElement
528 * The content tree rooted at jaxbElement to be marshalled.
529 * @param writer
530 * XML will be sent to this writer.
531 *
532 * @throws JAXBException
533 * If any unexpected problem occurs during the marshalling.
534 * @throws MarshalException
535 * If the {@link ValidationEventHandler ValidationEventHandler}
536 * returns false from its {@code handleEvent} method or the
537 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
538 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#elementMarshalling">
539 * Marshalling a JAXB element</a>.
540 * @throws IllegalArgumentException
541 * If any of the method parameters are null
542 * @since 1.6, JAXB 2.0
543 */
544 public void marshal( Object jaxbElement, javax.xml.stream.XMLEventWriter writer )
545 throws JAXBException;
546
547 /**
548 * Get a DOM tree view of the content tree(Optional).
549 *
550 * If the returned DOM tree is updated, these changes are also
551 * visible in the content tree.
552 * Use {@link #marshal(Object, org.w3c.dom.Node)} to force
553 * a deep copy of the content tree to a DOM representation.
554 *
555 * @param contentTree - JAXB Java representation of XML content
556 *
557 * @return the DOM tree view of the contentTree
558 *
559 * @throws UnsupportedOperationException
560 * If the JAXB provider implementation does not support a
561 * DOM view of the content tree
562 *
563 * @throws IllegalArgumentException
564 * If any of the method parameters are null
565 *
566 * @throws JAXBException
567 * If any unexpected problem occurs
568 *
569 */
570 public org.w3c.dom.Node getNode( java.lang.Object contentTree )
571 throws JAXBException;
572
573 /**
574 * Set the particular property in the underlying implementation of
575 * {@code Marshaller}. This method can only be used to set one of
576 * the standard JAXB defined properties above or a provider specific
577 * property. Attempting to set an undefined property will result in
578 * a PropertyException being thrown. See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#supportedProps">
579 * Supported Properties</a>.
580 *
581 * @param name the name of the property to be set. This value can either
582 * be specified using one of the constant fields or a user
583 * supplied string.
584 * @param value the value of the property to be set
585 *
586 * @throws PropertyException when there is an error processing the given
587 * property or value
588 * @throws IllegalArgumentException
589 * If the name parameter is null
590 */
591 public void setProperty( String name, Object value )
592 throws PropertyException;
593
594 /**
595 * Get the particular property in the underlying implementation of
596 * {@code Marshaller}. This method can only be used to get one of
597 * the standard JAXB defined properties above or a provider specific
598 * property. Attempting to get an undefined property will result in
599 * a PropertyException being thrown. See <a href="{@docRoot}/javax/xml/bind/Marshaller.html#supportedProps">
600 * Supported Properties</a>.
601 *
602 * @param name the name of the property to retrieve
603 * @return the value of the requested property
604 *
605 * @throws PropertyException
606 * when there is an error retrieving the given property or value
607 * property name
608 * @throws IllegalArgumentException
609 * If the name parameter is null
610 */
611 public Object getProperty( String name ) throws PropertyException;
612
613 /**
614 * Allow an application to register a validation event handler.
615 * <p>
616 * The validation event handler will be called by the JAXB Provider if any
617 * validation errors are encountered during calls to any of the marshal
618 * API's. If the client application does not register a validation event
619 * handler before invoking one of the marshal methods, then validation
|
356 * {@code javax.xml.transform.Result}.
357 *
358 * <p>
359 * All JAXB Providers must at least support
360 * {@link javax.xml.transform.dom.DOMResult},
361 * {@link javax.xml.transform.sax.SAXResult}, and
362 * {@link javax.xml.transform.stream.StreamResult}. It can
363 * support other derived classes of {@code Result} as well.
364 *
365 * @param jaxbElement
366 * The root of content tree to be marshalled.
367 * @param result
368 * XML will be sent to this Result
369 *
370 * @throws JAXBException
371 * If any unexpected problem occurs during the marshalling.
372 * @throws MarshalException
373 * If the {@link ValidationEventHandler ValidationEventHandler}
374 * returns false from its {@code handleEvent} method or the
375 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
376 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
377 * Marshalling a JAXB element</a>.
378 * @throws IllegalArgumentException
379 * If any of the method parameters are null
380 */
381 public void marshal( Object jaxbElement, javax.xml.transform.Result result )
382 throws JAXBException;
383
384 /**
385 * Marshal the content tree rooted at {@code jaxbElement} into an output stream.
386 *
387 * @param jaxbElement
388 * The root of content tree to be marshalled.
389 * @param os
390 * XML will be added to this stream.
391 *
392 * @throws JAXBException
393 * If any unexpected problem occurs during the marshalling.
394 * @throws MarshalException
395 * If the {@link ValidationEventHandler ValidationEventHandler}
396 * returns false from its {@code handleEvent} method or the
397 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
398 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
399 * Marshalling a JAXB element</a>.
400 * @throws IllegalArgumentException
401 * If any of the method parameters are null
402 */
403 public void marshal( Object jaxbElement, java.io.OutputStream os )
404 throws JAXBException;
405
406 /**
407 * Marshal the content tree rooted at {@code jaxbElement} into a file.
408 *
409 * @param jaxbElement
410 * The root of content tree to be marshalled.
411 * @param output
412 * File to be written. If this file already exists, it will be overwritten.
413 *
414 * @throws JAXBException
415 * If any unexpected problem occurs during the marshalling.
416 * @throws MarshalException
417 * If the {@link ValidationEventHandler ValidationEventHandler}
418 * returns false from its {@code handleEvent} method or the
419 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
420 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
421 * Marshalling a JAXB element</a>.
422 * @throws IllegalArgumentException
423 * If any of the method parameters are null
424 * @since 1.6, JAXB 2.1
425 */
426 public void marshal( Object jaxbElement, File output )
427 throws JAXBException;
428
429 /**
430 * Marshal the content tree rooted at {@code jaxbElement} into a Writer.
431 *
432 * @param jaxbElement
433 * The root of content tree to be marshalled.
434 * @param writer
435 * XML will be sent to this writer.
436 *
437 * @throws JAXBException
438 * If any unexpected problem occurs during the marshalling.
439 * @throws MarshalException
440 * If the {@link ValidationEventHandler ValidationEventHandler}
441 * returns false from its {@code handleEvent} method or the
442 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
443 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
444 * Marshalling a JAXB element</a>.
445 * @throws IllegalArgumentException
446 * If any of the method parameters are null
447 */
448 public void marshal( Object jaxbElement, java.io.Writer writer )
449 throws JAXBException;
450
451 /**
452 * Marshal the content tree rooted at {@code jaxbElement} into SAX2 events.
453 *
454 * @param jaxbElement
455 * The root of content tree to be marshalled.
456 * @param handler
457 * XML will be sent to this handler as SAX2 events.
458 *
459 * @throws JAXBException
460 * If any unexpected problem occurs during the marshalling.
461 * @throws MarshalException
462 * If the {@link ValidationEventHandler ValidationEventHandler}
463 * returns false from its {@code handleEvent} method or the
464 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
465 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
466 * Marshalling a JAXB element</a>.
467 * @throws IllegalArgumentException
468 * If any of the method parameters are null
469 */
470 public void marshal( Object jaxbElement, org.xml.sax.ContentHandler handler )
471 throws JAXBException;
472
473 /**
474 * Marshal the content tree rooted at {@code jaxbElement} into a DOM tree.
475 *
476 * @param jaxbElement
477 * The content tree to be marshalled.
478 * @param node
479 * DOM nodes will be added as children of this node.
480 * This parameter must be a Node that accepts children
481 * ({@link org.w3c.dom.Document},
482 * {@link org.w3c.dom.DocumentFragment}, or
483 * {@link org.w3c.dom.Element})
484 *
485 * @throws JAXBException
486 * If any unexpected problem occurs during the marshalling.
487 * @throws MarshalException
488 * If the {@link ValidationEventHandler ValidationEventHandler}
489 * returns false from its {@code handleEvent} method or the
490 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
491 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
492 * Marshalling a JAXB element</a>.
493 * @throws IllegalArgumentException
494 * If any of the method parameters are null
495 */
496 public void marshal( Object jaxbElement, org.w3c.dom.Node node )
497 throws JAXBException;
498
499 /**
500 * Marshal the content tree rooted at {@code jaxbElement} into a
501 * {@link javax.xml.stream.XMLStreamWriter}.
502 *
503 * @param jaxbElement
504 * The content tree to be marshalled.
505 * @param writer
506 * XML will be sent to this writer.
507 *
508 * @throws JAXBException
509 * If any unexpected problem occurs during the marshalling.
510 * @throws MarshalException
511 * If the {@link ValidationEventHandler ValidationEventHandler}
512 * returns false from its {@code handleEvent} method or the
513 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
514 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
515 * Marshalling a JAXB element</a>.
516 * @throws IllegalArgumentException
517 * If any of the method parameters are null
518 * @since 1.6, JAXB 2.0
519 */
520 public void marshal( Object jaxbElement, javax.xml.stream.XMLStreamWriter writer )
521 throws JAXBException;
522
523 /**
524 * Marshal the content tree rooted at {@code jaxbElement} into a
525 * {@link javax.xml.stream.XMLEventWriter}.
526 *
527 * @param jaxbElement
528 * The content tree rooted at jaxbElement to be marshalled.
529 * @param writer
530 * XML will be sent to this writer.
531 *
532 * @throws JAXBException
533 * If any unexpected problem occurs during the marshalling.
534 * @throws MarshalException
535 * If the {@link ValidationEventHandler ValidationEventHandler}
536 * returns false from its {@code handleEvent} method or the
537 * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
538 * object reachable from {@code jaxbElement}). See <a href="{@docRoot}/java/xml/bind/Marshaller.html#elementMarshalling">
539 * Marshalling a JAXB element</a>.
540 * @throws IllegalArgumentException
541 * If any of the method parameters are null
542 * @since 1.6, JAXB 2.0
543 */
544 public void marshal( Object jaxbElement, javax.xml.stream.XMLEventWriter writer )
545 throws JAXBException;
546
547 /**
548 * Get a DOM tree view of the content tree(Optional).
549 *
550 * If the returned DOM tree is updated, these changes are also
551 * visible in the content tree.
552 * Use {@link #marshal(Object, org.w3c.dom.Node)} to force
553 * a deep copy of the content tree to a DOM representation.
554 *
555 * @param contentTree - JAXB Java representation of XML content
556 *
557 * @return the DOM tree view of the contentTree
558 *
559 * @throws UnsupportedOperationException
560 * If the JAXB provider implementation does not support a
561 * DOM view of the content tree
562 *
563 * @throws IllegalArgumentException
564 * If any of the method parameters are null
565 *
566 * @throws JAXBException
567 * If any unexpected problem occurs
568 *
569 */
570 public org.w3c.dom.Node getNode( java.lang.Object contentTree )
571 throws JAXBException;
572
573 /**
574 * Set the particular property in the underlying implementation of
575 * {@code Marshaller}. This method can only be used to set one of
576 * the standard JAXB defined properties above or a provider specific
577 * property. Attempting to set an undefined property will result in
578 * a PropertyException being thrown. See <a href="{@docRoot}/java/xml/bind/Marshaller.html#supportedProps">
579 * Supported Properties</a>.
580 *
581 * @param name the name of the property to be set. This value can either
582 * be specified using one of the constant fields or a user
583 * supplied string.
584 * @param value the value of the property to be set
585 *
586 * @throws PropertyException when there is an error processing the given
587 * property or value
588 * @throws IllegalArgumentException
589 * If the name parameter is null
590 */
591 public void setProperty( String name, Object value )
592 throws PropertyException;
593
594 /**
595 * Get the particular property in the underlying implementation of
596 * {@code Marshaller}. This method can only be used to get one of
597 * the standard JAXB defined properties above or a provider specific
598 * property. Attempting to get an undefined property will result in
599 * a PropertyException being thrown. See <a href="{@docRoot}/java/xml/bind/Marshaller.html#supportedProps">
600 * Supported Properties</a>.
601 *
602 * @param name the name of the property to retrieve
603 * @return the value of the requested property
604 *
605 * @throws PropertyException
606 * when there is an error retrieving the given property or value
607 * property name
608 * @throws IllegalArgumentException
609 * If the name parameter is null
610 */
611 public Object getProperty( String name ) throws PropertyException;
612
613 /**
614 * Allow an application to register a validation event handler.
615 * <p>
616 * The validation event handler will be called by the JAXB Provider if any
617 * validation errors are encountered during calls to any of the marshal
618 * API's. If the client application does not register a validation event
619 * handler before invoking one of the marshal methods, then validation
|