1 /*
   2  * Copyright (c) 2003, 2015, 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 
  26 package javax.xml.bind;
  27 
  28 import javax.xml.bind.annotation.XmlRootElement;
  29 import javax.xml.bind.annotation.adapters.XmlAdapter;
  30 import javax.xml.bind.attachment.AttachmentMarshaller;
  31 import javax.xml.validation.Schema;
  32 import java.io.File;
  33 
  34 /**
  35  * <p>
  36  * The {@code Marshaller} class is responsible for governing the process
  37  * of serializing Java content trees back into XML data.  It provides the basic
  38  * marshalling methods:
  39  *
  40  * <p>
  41  * <i>Assume the following setup code for all following code fragments:</i>
  42  * <blockquote>
  43  *    <pre>
  44  *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
  45  *       Unmarshaller u = jc.createUnmarshaller();
  46  *       Object element = u.unmarshal( new File( "foo.xml" ) );
  47  *       Marshaller m = jc.createMarshaller();
  48  *    </pre>
  49  * </blockquote>
  50  *
  51  * <p>
  52  * Marshalling to a File:
  53  * <blockquote>
  54  *    <pre>
  55  *       OutputStream os = new FileOutputStream( "nosferatu.xml" );
  56  *       m.marshal( element, os );
  57  *    </pre>
  58  * </blockquote>
  59  *
  60  * <p>
  61  * Marshalling to a SAX ContentHandler:
  62  * <blockquote>
  63  *    <pre>
  64  *       // assume MyContentHandler instanceof ContentHandler
  65  *       m.marshal( element, new MyContentHandler() );
  66  *    </pre>
  67  * </blockquote>
  68  *
  69  * <p>
  70  * Marshalling to a DOM Node:
  71  * <blockquote>
  72  *    <pre>
  73  *       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
  74  *       dbf.setNamespaceAware(true);
  75  *       DocumentBuilder db = dbf.newDocumentBuilder();
  76  *       Document doc = db.newDocument();
  77  *
  78  *       m.marshal( element, doc );
  79  *    </pre>
  80  * </blockquote>
  81  *
  82  * <p>
  83  * Marshalling to a java.io.OutputStream:
  84  * <blockquote>
  85  *    <pre>
  86  *       m.marshal( element, System.out );
  87  *    </pre>
  88  * </blockquote>
  89  *
  90  * <p>
  91  * Marshalling to a java.io.Writer:
  92  * <blockquote>
  93  *    <pre>
  94  *       m.marshal( element, new PrintWriter( System.out ) );
  95  *    </pre>
  96  * </blockquote>
  97  *
  98  * <p>
  99  * Marshalling to a javax.xml.transform.SAXResult:
 100  * <blockquote>
 101  *    <pre>
 102  *       // assume MyContentHandler instanceof ContentHandler
 103  *       SAXResult result = new SAXResult( new MyContentHandler() );
 104  *
 105  *       m.marshal( element, result );
 106  *    </pre>
 107  * </blockquote>
 108  *
 109  * <p>
 110  * Marshalling to a javax.xml.transform.DOMResult:
 111  * <blockquote>
 112  *    <pre>
 113  *       DOMResult result = new DOMResult();
 114  *
 115  *       m.marshal( element, result );
 116  *    </pre>
 117  * </blockquote>
 118  *
 119  * <p>
 120  * Marshalling to a javax.xml.transform.StreamResult:
 121  * <blockquote>
 122  *    <pre>
 123  *       StreamResult result = new StreamResult( System.out );
 124  *
 125  *       m.marshal( element, result );
 126  *    </pre>
 127  * </blockquote>
 128  *
 129  * <p>
 130  * Marshalling to a javax.xml.stream.XMLStreamWriter:
 131  * <blockquote>
 132  *    <pre>
 133  *       XMLStreamWriter xmlStreamWriter =
 134  *           XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
 135  *
 136  *       m.marshal( element, xmlStreamWriter );
 137  *    </pre>
 138  * </blockquote>
 139  *
 140  * <p>
 141  * Marshalling to a javax.xml.stream.XMLEventWriter:
 142  * <blockquote>
 143  *    <pre>
 144  *       XMLEventWriter xmlEventWriter =
 145  *           XMLOutputFactory.newInstance().createXMLEventWriter( ... );
 146  *
 147  *       m.marshal( element, xmlEventWriter );
 148  *    </pre>
 149  * </blockquote>
 150  *
 151  * <p>
 152  * <a name="elementMarshalling"></a>
 153  * <b>Marshalling content tree rooted by a JAXB element</b><br>
 154  * <blockquote>
 155  * The first parameter of the overloaded
 156  * {@code Marshaller.marshal(java.lang.Object, ...)} methods must be a
 157  * JAXB element as computed by
 158  * {@link JAXBIntrospector#isElement(java.lang.Object)};
 159  * otherwise, a {@code Marshaller.marshal} method must throw a
 160  * {@link MarshalException}. There exist two mechanisms
 161  * to enable marshalling an instance that is not a JAXB element.
 162  * One method is to wrap the instance as a value of a {@link JAXBElement},
 163  * and pass the wrapper element as the first parameter to
 164  * a {@code Marshaller.marshal} method. For java to schema binding, it
 165  * is also possible to simply annotate the instance's class with
 166  * @{@link XmlRootElement}.
 167  * </blockquote>
 168  *
 169  * <p>
 170  * <b>Encoding</b><br>
 171  * <blockquote>
 172  * By default, the Marshaller will use UTF-8 encoding when generating XML data
 173  * to a {@code java.io.OutputStream}, or a {@code java.io.Writer}.  Use the
 174  * {@link #setProperty(String,Object) setProperty} API to change the output
 175  * encoding used during these marshal operations.  Client applications are
 176  * expected to supply a valid character encoding name as defined in the
 177  * <a href="http://www.w3.org/TR/2000/REC-xml-20001006#charencoding">W3C XML 1.0
 178  * Recommendation</a> and supported by your Java Platform.
 179  * </blockquote>
 180  *
 181  * <p>
 182  * <b>Validation and Well-Formedness</b><br>
 183  * <blockquote>
 184  * <p>
 185  * Client applications are not required to validate the Java content tree prior
 186  * to calling any of the marshal API's.  Furthermore, there is no requirement
 187  * that the Java content tree be valid with respect to its original schema in
 188  * order to marshal it back into XML data.  Different JAXB Providers will
 189  * support marshalling invalid Java content trees at varying levels, however
 190  * all JAXB Providers must be able to marshal a valid content tree back to
 191  * XML data.  A JAXB Provider must throw a {@code MarshalException} when it
 192  * is unable to complete the marshal operation due to invalid content.  Some
 193  * JAXB Providers will fully allow marshalling invalid content, others will fail
 194  * on the first validation error.
 195  * <p>
 196  * Even when schema validation is not explictly enabled for the marshal operation,
 197  * it is possible that certain types of validation events will be detected
 198  * during the operation.  Validation events will be reported to the registered
 199  * event handler.  If the client application has not registered an event handler
 200  * prior to invoking one of the marshal API's, then events will be delivered to
 201  * a default event handler which will terminate the marshal operation after
 202  * encountering the first error or fatal error. Note that for JAXB 2.0 and
 203  * later versions, {@link javax.xml.bind.helpers.DefaultValidationEventHandler} is
 204  * no longer used.
 205  *
 206  * </blockquote>
 207  *
 208  * <p>
 209  * <a name="supportedProps"></a>
 210  * <b>Supported Properties</b><br>
 211  * <blockquote>
 212  * <p>
 213  * All JAXB Providers are required to support the following set of properties.
 214  * Some providers may support additional properties.
 215  * <dl>
 216  *   <dt>{@code jaxb.encoding} - value must be a java.lang.String</dt>
 217  *   <dd>The output encoding to use when marshalling the XML data.  The
 218  *               Marshaller will use "UTF-8" by default if this property is not
 219  *       specified.</dd>
 220  *   <dt>{@code jaxb.formatted.output} - value must be a java.lang.Boolean</dt>
 221  *   <dd>This property controls whether or not the Marshaller will format
 222  *       the resulting XML data with line breaks and indentation.  A
 223  *       true value for this property indicates human readable indented
 224  *       xml data, while a false value indicates unformatted xml data.
 225  *       The Marshaller will default to false (unformatted) if this
 226  *       property is not specified.</dd>
 227  *   <dt>{@code jaxb.schemaLocation} - value must be a java.lang.String</dt>
 228  *   <dd>This property allows the client application to specify an
 229  *       xsi:schemaLocation attribute in the generated XML data.  The format of
 230  *       the schemaLocation attribute value is discussed in an easy to
 231  *       understand, non-normative form in
 232  *       <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
 233  *       of the W3C XML Schema Part 0: Primer</a> and specified in
 234  *       <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
 235  *       Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
 236  *   <dt>{@code jaxb.noNamespaceSchemaLocation} - value must be a java.lang.String</dt>
 237  *   <dd>This property allows the client application to specify an
 238  *       xsi:noNamespaceSchemaLocation attribute in the generated XML
 239  *       data.  The format of the schemaLocation attribute value is discussed in
 240  *       an easy to understand, non-normative form in
 241  *       <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
 242  *       of the W3C XML Schema Part 0: Primer</a> and specified in
 243  *       <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
 244  *       Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
 245  *   <dt>{@code jaxb.fragment} - value must be a java.lang.Boolean</dt>
 246  *   <dd>This property determines whether or not document level events will be
 247  *       generated by the Marshaller.  If the property is not specified, the
 248  *       default is {@code false}. This property has different implications depending
 249  *       on which marshal api you are using - when this property is set to true:<br>
 250  *       <ul>
 251  *         <li>{@link #marshal(Object,org.xml.sax.ContentHandler) marshal(Object,ContentHandler)} - the Marshaller won't
 252  *             invoke {@link org.xml.sax.ContentHandler#startDocument()} and
 253  *             {@link org.xml.sax.ContentHandler#endDocument()}.</li>
 254  *         <li>{@link #marshal(Object,org.w3c.dom.Node) marshal(Object,Node)} - the property has no effect on this
 255  *             API.</li>
 256  *         <li>{@link #marshal(Object,java.io.OutputStream) marshal(Object,OutputStream)} - the Marshaller won't
 257  *             generate an xml declaration.</li>
 258  *         <li>{@link #marshal(Object,java.io.Writer) marshal(Object,Writer)} - the Marshaller won't
 259  *             generate an xml declaration.</li>
 260  *         <li>{@link #marshal(Object,javax.xml.transform.Result) marshal(Object,Result)} - depends on the kind of
 261  *             Result object, see semantics for Node, ContentHandler, and Stream APIs</li>
 262  *         <li>{@link #marshal(Object,javax.xml.stream.XMLEventWriter) marshal(Object,XMLEventWriter)} - the
 263  *             Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and
 264  *             {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.</li>
 265  *         <li>{@link #marshal(Object,javax.xml.stream.XMLStreamWriter) marshal(Object,XMLStreamWriter)} - the
 266  *             Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and
 267  *             {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.</li>
 268  *       </ul>
 269  *   </dd>
 270  * </dl>
 271  * </blockquote>
 272  *
 273  * <p>
 274  * <a name="marshalEventCallback"></a>
 275  * <b>Marshal Event Callbacks</b><br>
 276  * <blockquote>
 277  * "The {@link Marshaller} provides two styles of callback mechanisms
 278  * that allow application specific processing during key points in the
 279  * unmarshalling process.  In 'class defined' event callbacks, application
 280  * specific code placed in JAXB mapped classes is triggered during
 281  * marshalling.  'External listeners' allow for centralized processing
 282  * of marshal events in one callback method rather than by type event callbacks.
 283  *
 284  * <p>
 285  * Class defined event callback methods allow any JAXB mapped class to specify
 286  * its own specific callback methods by defining methods with the following method signatures:
 287  * <blockquote>
 288  * <pre>
 289  *   // Invoked by Marshaller after it has created an instance of this object.
 290  *   boolean beforeMarshal(Marshaller);
 291  *
 292  *   // Invoked by Marshaller after it has marshalled all properties of this object.
 293  *   void afterMarshal(Marshaller);
 294  * </pre>
 295  * </blockquote>
 296  * The class defined event callback methods should be used when the callback method requires
 297  * access to non-public methods and/or fields of the class.
 298  * <p>
 299  * The external listener callback mechanism enables the registration of a {@link Listener}
 300  * instance with a {@link Marshaller#setListener(Listener)}. The external listener receives all callback events,
 301  * allowing for more centralized processing than per class defined callback methods.
 302  * <p>
 303  * The 'class defined' and external listener event callback methods are independent of each other,
 304  * both can be called for one event. The invocation ordering when both listener callback methods exist is
 305  * defined in {@link Listener#beforeMarshal(Object)} and {@link Listener#afterMarshal(Object)}.
 306  * <p>
 307  * An event callback method throwing an exception terminates the current marshal process.
 308  * </blockquote>
 309  *
 310  * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
 311  * @see JAXBContext
 312  * @see Validator
 313  * @see Unmarshaller
 314  * @since 1.6, JAXB 1.0
 315  */
 316 public interface Marshaller {
 317 
 318     /**
 319      * The name of the property used to specify the output encoding in
 320      * the marshalled XML data.
 321      */
 322     public static final String JAXB_ENCODING =
 323         "jaxb.encoding";
 324 
 325     /**
 326      * The name of the property used to specify whether or not the marshalled
 327      * XML data is formatted with linefeeds and indentation.
 328      */
 329     public static final String JAXB_FORMATTED_OUTPUT =
 330         "jaxb.formatted.output";
 331 
 332     /**
 333      * The name of the property used to specify the xsi:schemaLocation
 334      * attribute value to place in the marshalled XML output.
 335      */
 336     public static final String JAXB_SCHEMA_LOCATION =
 337         "jaxb.schemaLocation";
 338 
 339     /**
 340      * The name of the property used to specify the
 341      * xsi:noNamespaceSchemaLocation attribute value to place in the marshalled
 342      * XML output.
 343      */
 344     public static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION =
 345         "jaxb.noNamespaceSchemaLocation";
 346 
 347     /**
 348      * The name of the property used to specify whether or not the marshaller
 349      * will generate document level events (ie calling startDocument or endDocument).
 350      */
 351     public static final String JAXB_FRAGMENT =
 352         "jaxb.fragment";
 353 
 354     /**
 355      * Marshal the content tree rooted at {@code jaxbElement} into the specified
 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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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
 620      * events will be handled by the default event handler which will terminate
 621      * the marshal operation after the first error or fatal error is encountered.
 622      * <p>
 623      * Calling this method with a null parameter will cause the Marshaller
 624      * to revert back to the default default event handler.
 625      *
 626      * @param handler the validation event handler
 627      * @throws JAXBException if an error was encountered while setting the
 628      *         event handler
 629      */
 630     public void setEventHandler( ValidationEventHandler handler )
 631         throws JAXBException;
 632 
 633     /**
 634      * Return the current event handler or the default event handler if one
 635      * hasn't been set.
 636      *
 637      * @return the current ValidationEventHandler or the default event handler
 638      *         if it hasn't been set
 639      * @throws JAXBException if an error was encountered while getting the
 640      *         current event handler
 641      */
 642     public ValidationEventHandler getEventHandler()
 643         throws JAXBException;
 644 
 645 
 646 
 647     /**
 648      * Associates a configured instance of {@link XmlAdapter} with this marshaller.
 649      *
 650      * <p>
 651      * This is a convenience method that invokes {@code setAdapter(adapter.getClass(),adapter);}.
 652      *
 653      * @see #setAdapter(Class,XmlAdapter)
 654      * @throws IllegalArgumentException
 655      *      if the adapter parameter is null.
 656      * @throws UnsupportedOperationException
 657      *      if invoked agains a JAXB 1.0 implementation.
 658      * @since 1.6, JAXB 2.0
 659      */
 660     public void setAdapter( XmlAdapter adapter );
 661 
 662     /**
 663      * Associates a configured instance of {@link XmlAdapter} with this marshaller.
 664      *
 665      * <p>
 666      * Every marshaller internally maintains a
 667      * {@link java.util.Map}&lt;{@link Class},{@link XmlAdapter}&gt;,
 668      * which it uses for marshalling classes whose fields/methods are annotated
 669      * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
 670      *
 671      * <p>
 672      * This method allows applications to use a configured instance of {@link XmlAdapter}.
 673      * When an instance of an adapter is not given, a marshaller will create
 674      * one by invoking its default constructor.
 675      *
 676      * @param type
 677      *      The type of the adapter. The specified instance will be used when
 678      *      {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
 679      *      refers to this type.
 680      * @param adapter
 681      *      The instance of the adapter to be used. If null, it will un-register
 682      *      the current adapter set for this type.
 683      * @throws IllegalArgumentException
 684      *      if the type parameter is null.
 685      * @throws UnsupportedOperationException
 686      *      if invoked agains a JAXB 1.0 implementation.
 687      * @since 1.6, JAXB 2.0
 688      */
 689     public <A extends XmlAdapter> void setAdapter( Class<A> type, A adapter );
 690 
 691     /**
 692      * Gets the adapter associated with the specified type.
 693      *
 694      * This is the reverse operation of the {@link #setAdapter} method.
 695      *
 696      * @throws IllegalArgumentException
 697      *      if the type parameter is null.
 698      * @throws UnsupportedOperationException
 699      *      if invoked agains a JAXB 1.0 implementation.
 700      * @since 1.6, JAXB 2.0
 701      */
 702     public <A extends XmlAdapter> A getAdapter( Class<A> type );
 703 
 704 
 705     /**
 706      * <p>Associate a context that enables binary data within an XML document
 707      * to be transmitted as XML-binary optimized attachment.
 708      * The attachment is referenced from the XML document content model
 709      * by content-id URIs(cid) references stored within the xml document.
 710      *
 711      * @throws IllegalStateException if attempt to concurrently call this
 712      *                               method during a marshal operation.
 713      */
 714     void setAttachmentMarshaller(AttachmentMarshaller am);
 715 
 716     AttachmentMarshaller getAttachmentMarshaller();
 717 
 718     /**
 719      * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
 720      * object that should be used to validate subsequent marshal operations
 721      * against.  Passing null into this method will disable validation.
 722      *
 723      * <p>
 724      * This method allows the caller to validate the marshalled XML as it's marshalled.
 725      *
 726      * <p>
 727      * Initially this property is set to {@code null}.
 728      *
 729      * @param schema Schema object to validate marshal operations against or null to disable validation
 730      * @throws UnsupportedOperationException could be thrown if this method is
 731      *         invoked on an Marshaller created from a JAXBContext referencing
 732      *         JAXB 1.0 mapped classes
 733      * @since 1.6, JAXB 2.0
 734      */
 735     public void setSchema( Schema schema );
 736 
 737     /**
 738      * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
 739      * being used to perform marshal-time validation.  If there is no
 740      * Schema set on the marshaller, then this method will return null
 741      * indicating that marshal-time validation will not be performed.
 742      *
 743      * @return the Schema object being used to perform marshal-time
 744      *      validation or null if not present.
 745      * @throws UnsupportedOperationException could be thrown if this method is
 746      *         invoked on an Marshaller created from a JAXBContext referencing
 747      *         JAXB 1.0 mapped classes
 748      * @since 1.6, JAXB 2.0
 749      */
 750     public Schema getSchema();
 751 
 752     /**
 753      * <p>
 754      * Register an instance of an implementation of this class with a {@link Marshaller} to externally listen
 755      * for marshal events.
 756      * </p>
 757      * <p>
 758      * This class enables pre and post processing of each marshalled object.
 759      * The event callbacks are called when marshalling from an instance that maps to an xml element or
 760      * complex type definition. The event callbacks are not called when marshalling from an instance of a
 761      * Java datatype that represents a simple type definition.
 762      * </p>
 763      * <p>
 764      * External listener is one of two different mechanisms for defining marshal event callbacks.
 765      * See <a href="Marshaller.html#marshalEventCallback">Marshal Event Callbacks</a> for an overview.
 766      *
 767      * @see Marshaller#setListener(Listener)
 768      * @see Marshaller#getListener()
 769      * @since 1.6, JAXB 2.0
 770      */
 771     public static abstract class Listener {
 772         /**
 773          * <p>
 774          * Callback method invoked before marshalling from {@code source} to XML.
 775          * </p>
 776          * <p>
 777          * This method is invoked just before marshalling process starts to marshal {@code source}.
 778          * Note that if the class of {@code source} defines its own {@code beforeMarshal} method,
 779          * the class specific callback method is invoked just before this method is invoked.
 780          *
 781          * @param source instance of JAXB mapped class prior to marshalling from it.
 782          */
 783         public void beforeMarshal(Object source) {
 784         }
 785 
 786         /**
 787          * <p>
 788          * Callback method invoked after marshalling {@code source} to XML.
 789          * </p>
 790          * <p>
 791          * This method is invoked after {@code source} and all its descendants have been marshalled.
 792          * Note that if the class of {@code source} defines its own {@code afterMarshal} method,
 793          * the class specific callback method is invoked just before this method is invoked.
 794          *
 795          * @param source instance of JAXB mapped class after marshalling it.
 796          */
 797         public void afterMarshal(Object source) {
 798         }
 799     }
 800 
 801     /**
 802      * <p>
 803      * Register marshal event callback {@link Listener} with this {@link Marshaller}.
 804      *
 805      * <p>
 806      * There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener.
 807      * One can unregister current Listener by setting listener to {@code null}.
 808      *
 809      * @param listener an instance of a class that implements {@link Listener}
 810      * @since 1.6, JAXB 2.0
 811      */
 812     public void setListener(Listener listener);
 813 
 814     /**
 815      * <p>Return {@link Listener} registered with this {@link Marshaller}.
 816      *
 817      * @return registered {@link Listener} or {@code null}
 818      *         if no Listener is registered with this Marshaller.
 819      * @since 1.6, JAXB 2.0
 820      */
 821     public Listener getListener();
 822 }