1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/javax/xml/bind/Marshaller.java Tue Mar 06 16:09:35 2012 -0800
1.3 @@ -0,0 +1,823 @@
1.4 +/*
1.5 + * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package javax.xml.bind;
1.30 +
1.31 +import javax.xml.bind.annotation.XmlRootElement;
1.32 +import javax.xml.bind.annotation.adapters.XmlAdapter;
1.33 +import javax.xml.bind.attachment.AttachmentMarshaller;
1.34 +import javax.xml.validation.Schema;
1.35 +import java.io.File;
1.36 +
1.37 +/**
1.38 + * <p>
1.39 + * The <tt>Marshaller</tt> class is responsible for governing the process
1.40 + * of serializing Java content trees back into XML data. It provides the basic
1.41 + * marshalling methods:
1.42 + *
1.43 + * <p>
1.44 + * <i>Assume the following setup code for all following code fragments:</i>
1.45 + * <blockquote>
1.46 + * <pre>
1.47 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
1.48 + * Unmarshaller u = jc.createUnmarshaller();
1.49 + * Object element = u.unmarshal( new File( "foo.xml" ) );
1.50 + * Marshaller m = jc.createMarshaller();
1.51 + * </pre>
1.52 + * </blockquote>
1.53 + *
1.54 + * <p>
1.55 + * Marshalling to a File:
1.56 + * <blockquote>
1.57 + * <pre>
1.58 + * OutputStream os = new FileOutputStream( "nosferatu.xml" );
1.59 + * m.marshal( element, os );
1.60 + * </pre>
1.61 + * </blockquote>
1.62 + *
1.63 + * <p>
1.64 + * Marshalling to a SAX ContentHandler:
1.65 + * <blockquote>
1.66 + * <pre>
1.67 + * // assume MyContentHandler instanceof ContentHandler
1.68 + * m.marshal( element, new MyContentHandler() );
1.69 + * </pre>
1.70 + * </blockquote>
1.71 + *
1.72 + * <p>
1.73 + * Marshalling to a DOM Node:
1.74 + * <blockquote>
1.75 + * <pre>
1.76 + * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
1.77 + * dbf.setNamespaceAware(true);
1.78 + * DocumentBuilder db = dbf.newDocumentBuilder();
1.79 + * Document doc = db.newDocument();
1.80 + *
1.81 + * m.marshal( element, doc );
1.82 + * </pre>
1.83 + * </blockquote>
1.84 + *
1.85 + * <p>
1.86 + * Marshalling to a java.io.OutputStream:
1.87 + * <blockquote>
1.88 + * <pre>
1.89 + * m.marshal( element, System.out );
1.90 + * </pre>
1.91 + * </blockquote>
1.92 + *
1.93 + * <p>
1.94 + * Marshalling to a java.io.Writer:
1.95 + * <blockquote>
1.96 + * <pre>
1.97 + * m.marshal( element, new PrintWriter( System.out ) );
1.98 + * </pre>
1.99 + * </blockquote>
1.100 + *
1.101 + * <p>
1.102 + * Marshalling to a javax.xml.transform.SAXResult:
1.103 + * <blockquote>
1.104 + * <pre>
1.105 + * // assume MyContentHandler instanceof ContentHandler
1.106 + * SAXResult result = new SAXResult( new MyContentHandler() );
1.107 + *
1.108 + * m.marshal( element, result );
1.109 + * </pre>
1.110 + * </blockquote>
1.111 + *
1.112 + * <p>
1.113 + * Marshalling to a javax.xml.transform.DOMResult:
1.114 + * <blockquote>
1.115 + * <pre>
1.116 + * DOMResult result = new DOMResult();
1.117 + *
1.118 + * m.marshal( element, result );
1.119 + * </pre>
1.120 + * </blockquote>
1.121 + *
1.122 + * <p>
1.123 + * Marshalling to a javax.xml.transform.StreamResult:
1.124 + * <blockquote>
1.125 + * <pre>
1.126 + * StreamResult result = new StreamResult( System.out );
1.127 + *
1.128 + * m.marshal( element, result );
1.129 + * </pre>
1.130 + * </blockquote>
1.131 + *
1.132 + * <p>
1.133 + * Marshalling to a javax.xml.stream.XMLStreamWriter:
1.134 + * <blockquote>
1.135 + * <pre>
1.136 + * XMLStreamWriter xmlStreamWriter =
1.137 + * XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
1.138 + *
1.139 + * m.marshal( element, xmlStreamWriter );
1.140 + * </pre>
1.141 + * </blockquote>
1.142 + *
1.143 + * <p>
1.144 + * Marshalling to a javax.xml.stream.XMLEventWriter:
1.145 + * <blockquote>
1.146 + * <pre>
1.147 + * XMLEventWriter xmlEventWriter =
1.148 + * XMLOutputFactory.newInstance().createXMLEventWriter( ... );
1.149 + *
1.150 + * m.marshal( element, xmlEventWriter );
1.151 + * </pre>
1.152 + * </blockquote>
1.153 + *
1.154 + * <p>
1.155 + * <a name="elementMarshalling"></a>
1.156 + * <b>Marshalling content tree rooted by a JAXB element</b><br>
1.157 + * <blockquote>
1.158 + * The first parameter of the overloaded
1.159 + * <tt>Marshaller.marshal(java.lang.Object, ...)</tt> methods must be a
1.160 + * JAXB element as computed by
1.161 + * {@link JAXBIntrospector#isElement(java.lang.Object)};
1.162 + * otherwise, a <tt>Marshaller.marshal</tt> method must throw a
1.163 + * {@link MarshalException}. There exist two mechanisms
1.164 + * to enable marshalling an instance that is not a JAXB element.
1.165 + * One method is to wrap the instance as a value of a {@link JAXBElement},
1.166 + * and pass the wrapper element as the first parameter to
1.167 + * a <tt>Marshaller.marshal</tt> method. For java to schema binding, it
1.168 + * is also possible to simply annotate the instance's class with
1.169 + * @{@link XmlRootElement}.
1.170 + * </blockquote>
1.171 + *
1.172 + * <p>
1.173 + * <b>Encoding</b><br>
1.174 + * <blockquote>
1.175 + * By default, the Marshaller will use UTF-8 encoding when generating XML data
1.176 + * to a <tt>java.io.OutputStream</tt>, or a <tt>java.io.Writer</tt>. Use the
1.177 + * {@link #setProperty(String,Object) setProperty} API to change the output
1.178 + * encoding used during these marshal operations. Client applications are
1.179 + * expected to supply a valid character encoding name as defined in the
1.180 + * <a href="http://www.w3.org/TR/2000/REC-xml-20001006#charencoding">W3C XML 1.0
1.181 + * Recommendation</a> and supported by your
1.182 + * <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc">
1.183 + * Java Platform</a>.
1.184 + * </blockquote>
1.185 + *
1.186 + * <p>
1.187 + * <b>Validation and Well-Formedness</b><br>
1.188 + * <blockquote>
1.189 + * <p>
1.190 + * Client applications are not required to validate the Java content tree prior
1.191 + * to calling any of the marshal API's. Furthermore, there is no requirement
1.192 + * that the Java content tree be valid with respect to its original schema in
1.193 + * order to marshal it back into XML data. Different JAXB Providers will
1.194 + * support marshalling invalid Java content trees at varying levels, however
1.195 + * all JAXB Providers must be able to marshal a valid content tree back to
1.196 + * XML data. A JAXB Provider must throw a <tt>MarshalException</tt> when it
1.197 + * is unable to complete the marshal operation due to invalid content. Some
1.198 + * JAXB Providers will fully allow marshalling invalid content, others will fail
1.199 + * on the first validation error.
1.200 + * <p>
1.201 + * Even when schema validation is not explictly enabled for the marshal operation,
1.202 + * it is possible that certain types of validation events will be detected
1.203 + * during the operation. Validation events will be reported to the registered
1.204 + * event handler. If the client application has not registered an event handler
1.205 + * prior to invoking one of the marshal API's, then events will be delivered to
1.206 + * a default event handler which will terminate the marshal operation after
1.207 + * encountering the first error or fatal error. Note that for JAXB 2.0 and
1.208 + * later versions, {@link javax.xml.bind.helpers.DefaultValidationEventHandler} is
1.209 + * no longer used.
1.210 + *
1.211 + * </blockquote>
1.212 + *
1.213 + * <p>
1.214 + * <a name="supportedProps"></a>
1.215 + * <b>Supported Properties</b><br>
1.216 + * <blockquote>
1.217 + * <p>
1.218 + * All JAXB Providers are required to support the following set of properties.
1.219 + * Some providers may support additional properties.
1.220 + * <dl>
1.221 + * <dt><tt>jaxb.encoding</tt> - value must be a java.lang.String</dt>
1.222 + * <dd>The output encoding to use when marshalling the XML data. The
1.223 + * Marshaller will use "UTF-8" by default if this property is not
1.224 + * specified.</dd>
1.225 + * <dt><tt>jaxb.formatted.output</tt> - value must be a java.lang.Boolean</dt>
1.226 + * <dd>This property controls whether or not the Marshaller will format
1.227 + * the resulting XML data with line breaks and indentation. A
1.228 + * true value for this property indicates human readable indented
1.229 + * xml data, while a false value indicates unformatted xml data.
1.230 + * The Marshaller will default to false (unformatted) if this
1.231 + * property is not specified.</dd>
1.232 + * <dt><tt>jaxb.schemaLocation</tt> - value must be a java.lang.String</dt>
1.233 + * <dd>This property allows the client application to specify an
1.234 + * xsi:schemaLocation attribute in the generated XML data. The format of
1.235 + * the schemaLocation attribute value is discussed in an easy to
1.236 + * understand, non-normative form in
1.237 + * <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
1.238 + * of the W3C XML Schema Part 0: Primer</a> and specified in
1.239 + * <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
1.240 + * Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
1.241 + * <dt><tt>jaxb.noNamespaceSchemaLocation</tt> - value must be a java.lang.String</dt>
1.242 + * <dd>This property allows the client application to specify an
1.243 + * xsi:noNamespaceSchemaLocation attribute in the generated XML
1.244 + * data. The format of the schemaLocation attribute value is discussed in
1.245 + * an easy to understand, non-normative form in
1.246 + * <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
1.247 + * of the W3C XML Schema Part 0: Primer</a> and specified in
1.248 + * <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
1.249 + * Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
1.250 + * <dt><tt>jaxb.fragment</tt> - value must be a java.lang.Boolean</dt>
1.251 + * <dd>This property determines whether or not document level events will be
1.252 + * generated by the Marshaller. If the property is not specified, the
1.253 + * default is <tt>false</tt>. This property has different implications depending
1.254 + * on which marshal api you are using - when this property is set to true:<br>
1.255 + * <ul>
1.256 + * <li>{@link #marshal(Object,org.xml.sax.ContentHandler) marshal(Object,ContentHandler)} - the Marshaller won't
1.257 + * invoke {@link org.xml.sax.ContentHandler#startDocument()} and
1.258 + * {@link org.xml.sax.ContentHandler#endDocument()}.</li>
1.259 + * <li>{@link #marshal(Object,org.w3c.dom.Node) marshal(Object,Node)} - the property has no effect on this
1.260 + * API.</li>
1.261 + * <li>{@link #marshal(Object,java.io.OutputStream) marshal(Object,OutputStream)} - the Marshaller won't
1.262 + * generate an xml declaration.</li>
1.263 + * <li>{@link #marshal(Object,java.io.Writer) marshal(Object,Writer)} - the Marshaller won't
1.264 + * generate an xml declaration.</li>
1.265 + * <li>{@link #marshal(Object,javax.xml.transform.Result) marshal(Object,Result)} - depends on the kind of
1.266 + * Result object, see semantics for Node, ContentHandler, and Stream APIs</li>
1.267 + * <li>{@link #marshal(Object,javax.xml.stream.XMLEventWriter) marshal(Object,XMLEventWriter)} - the
1.268 + * Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and
1.269 + * {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.</li>
1.270 + * <li>{@link #marshal(Object,javax.xml.stream.XMLStreamWriter) marshal(Object,XMLStreamWriter)} - the
1.271 + * Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and
1.272 + * {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.</li>
1.273 + * </ul>
1.274 + * </dd>
1.275 + * </dl>
1.276 + * </blockquote>
1.277 + *
1.278 + * <p>
1.279 + * <a name="marshalEventCallback"></a>
1.280 + * <b>Marshal Event Callbacks</b><br>
1.281 + * <blockquote>
1.282 + * "The {@link Marshaller} provides two styles of callback mechanisms
1.283 + * that allow application specific processing during key points in the
1.284 + * unmarshalling process. In 'class defined' event callbacks, application
1.285 + * specific code placed in JAXB mapped classes is triggered during
1.286 + * marshalling. 'External listeners' allow for centralized processing
1.287 + * of marshal events in one callback method rather than by type event callbacks.
1.288 + *
1.289 + * <p>
1.290 + * Class defined event callback methods allow any JAXB mapped class to specify
1.291 + * its own specific callback methods by defining methods with the following method signatures:
1.292 + * <blockquote>
1.293 + * <pre>
1.294 + * // Invoked by Marshaller after it has created an instance of this object.
1.295 + * boolean beforeMarshal(Marshaller);
1.296 + *
1.297 + * // Invoked by Marshaller after it has marshalled all properties of this object.
1.298 + * void afterMmarshal(Marshaller);
1.299 + * </pre>
1.300 + * </blockquote>
1.301 + * The class defined event callback methods should be used when the callback method requires
1.302 + * access to non-public methods and/or fields of the class.
1.303 + * <p>
1.304 + * The external listener callback mechanism enables the registration of a {@link Listener}
1.305 + * instance with a {@link Marshaller#setListener(Listener)}. The external listener receives all callback events,
1.306 + * allowing for more centralized processing than per class defined callback methods.
1.307 + * <p>
1.308 + * The 'class defined' and external listener event callback methods are independent of each other,
1.309 + * both can be called for one event. The invocation ordering when both listener callback methods exist is
1.310 + * defined in {@link Listener#beforeMarshal(Object)} and {@link Listener#afterMarshal(Object)}.
1.311 + * <p>
1.312 + * An event callback method throwing an exception terminates the current marshal process.
1.313 + * </blockquote>
1.314 + *
1.315 + * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
1.316 + * @see JAXBContext
1.317 + * @see Validator
1.318 + * @see Unmarshaller
1.319 + * @since JAXB1.0
1.320 + */
1.321 +public interface Marshaller {
1.322 +
1.323 + /**
1.324 + * The name of the property used to specify the output encoding in
1.325 + * the marshalled XML data.
1.326 + */
1.327 + public static final String JAXB_ENCODING =
1.328 + "jaxb.encoding";
1.329 +
1.330 + /**
1.331 + * The name of the property used to specify whether or not the marshalled
1.332 + * XML data is formatted with linefeeds and indentation.
1.333 + */
1.334 + public static final String JAXB_FORMATTED_OUTPUT =
1.335 + "jaxb.formatted.output";
1.336 +
1.337 + /**
1.338 + * The name of the property used to specify the xsi:schemaLocation
1.339 + * attribute value to place in the marshalled XML output.
1.340 + */
1.341 + public static final String JAXB_SCHEMA_LOCATION =
1.342 + "jaxb.schemaLocation";
1.343 +
1.344 + /**
1.345 + * The name of the property used to specify the
1.346 + * xsi:noNamespaceSchemaLocation attribute value to place in the marshalled
1.347 + * XML output.
1.348 + */
1.349 + public static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION =
1.350 + "jaxb.noNamespaceSchemaLocation";
1.351 +
1.352 + /**
1.353 + * The name of the property used to specify whether or not the marshaller
1.354 + * will generate document level events (ie calling startDocument or endDocument).
1.355 + */
1.356 + public static final String JAXB_FRAGMENT =
1.357 + "jaxb.fragment";
1.358 +
1.359 + /**
1.360 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into the specified
1.361 + * <tt>javax.xml.transform.Result</tt>.
1.362 + *
1.363 + * <p>
1.364 + * All JAXB Providers must at least support
1.365 + * {@link javax.xml.transform.dom.DOMResult},
1.366 + * {@link javax.xml.transform.sax.SAXResult}, and
1.367 + * {@link javax.xml.transform.stream.StreamResult}. It can
1.368 + * support other derived classes of <tt>Result</tt> as well.
1.369 + *
1.370 + * @param jaxbElement
1.371 + * The root of content tree to be marshalled.
1.372 + * @param result
1.373 + * XML will be sent to this Result
1.374 + *
1.375 + * @throws JAXBException
1.376 + * If any unexpected problem occurs during the marshalling.
1.377 + * @throws MarshalException
1.378 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.379 + * returns false from its <tt>handleEvent</tt> method or the
1.380 + * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
1.381 + * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
1.382 + * Marshalling a JAXB element</a>.
1.383 + * @throws IllegalArgumentException
1.384 + * If any of the method parameters are null
1.385 + */
1.386 + public void marshal( Object jaxbElement, javax.xml.transform.Result result )
1.387 + throws JAXBException;
1.388 +
1.389 + /**
1.390 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into an output stream.
1.391 + *
1.392 + * @param jaxbElement
1.393 + * The root of content tree to be marshalled.
1.394 + * @param os
1.395 + * XML will be added to this stream.
1.396 + *
1.397 + * @throws JAXBException
1.398 + * If any unexpected problem occurs during the marshalling.
1.399 + * @throws MarshalException
1.400 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.401 + * returns false from its <tt>handleEvent</tt> method or the
1.402 + * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
1.403 + * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
1.404 + * Marshalling a JAXB element</a>.
1.405 + * @throws IllegalArgumentException
1.406 + * If any of the method parameters are null
1.407 + */
1.408 + public void marshal( Object jaxbElement, java.io.OutputStream os )
1.409 + throws JAXBException;
1.410 +
1.411 + /**
1.412 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into a file.
1.413 + *
1.414 + * @param jaxbElement
1.415 + * The root of content tree to be marshalled.
1.416 + * @param output
1.417 + * File to be written. If this file already exists, it will be overwritten.
1.418 + *
1.419 + * @throws JAXBException
1.420 + * If any unexpected problem occurs during the marshalling.
1.421 + * @throws MarshalException
1.422 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.423 + * returns false from its <tt>handleEvent</tt> method or the
1.424 + * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
1.425 + * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
1.426 + * Marshalling a JAXB element</a>.
1.427 + * @throws IllegalArgumentException
1.428 + * If any of the method parameters are null
1.429 + * @since JAXB2.1
1.430 + */
1.431 + public void marshal( Object jaxbElement, File output )
1.432 + throws JAXBException;
1.433 +
1.434 + /**
1.435 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into a Writer.
1.436 + *
1.437 + * @param jaxbElement
1.438 + * The root of content tree to be marshalled.
1.439 + * @param writer
1.440 + * XML will be sent to this writer.
1.441 + *
1.442 + * @throws JAXBException
1.443 + * If any unexpected problem occurs during the marshalling.
1.444 + * @throws MarshalException
1.445 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.446 + * returns false from its <tt>handleEvent</tt> method or the
1.447 + * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
1.448 + * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
1.449 + * Marshalling a JAXB element</a>.
1.450 + * @throws IllegalArgumentException
1.451 + * If any of the method parameters are null
1.452 + */
1.453 + public void marshal( Object jaxbElement, java.io.Writer writer )
1.454 + throws JAXBException;
1.455 +
1.456 + /**
1.457 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into SAX2 events.
1.458 + *
1.459 + * @param jaxbElement
1.460 + * The root of content tree to be marshalled.
1.461 + * @param handler
1.462 + * XML will be sent to this handler as SAX2 events.
1.463 + *
1.464 + * @throws JAXBException
1.465 + * If any unexpected problem occurs during the marshalling.
1.466 + * @throws MarshalException
1.467 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.468 + * returns false from its <tt>handleEvent</tt> method or the
1.469 + * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
1.470 + * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
1.471 + * Marshalling a JAXB element</a>.
1.472 + * @throws IllegalArgumentException
1.473 + * If any of the method parameters are null
1.474 + */
1.475 + public void marshal( Object jaxbElement, org.xml.sax.ContentHandler handler )
1.476 + throws JAXBException;
1.477 +
1.478 + /**
1.479 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into a DOM tree.
1.480 + *
1.481 + * @param jaxbElement
1.482 + * The content tree to be marshalled.
1.483 + * @param node
1.484 + * DOM nodes will be added as children of this node.
1.485 + * This parameter must be a Node that accepts children
1.486 + * ({@link org.w3c.dom.Document},
1.487 + * {@link org.w3c.dom.DocumentFragment}, or
1.488 + * {@link org.w3c.dom.Element})
1.489 + *
1.490 + * @throws JAXBException
1.491 + * If any unexpected problem occurs during the marshalling.
1.492 + * @throws MarshalException
1.493 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.494 + * returns false from its <tt>handleEvent</tt> method or the
1.495 + * <tt>Marshaller</tt> is unable to marshal <tt>jaxbElement</tt> (or any
1.496 + * object reachable from <tt>jaxbElement</tt>). See <a href="#elementMarshalling">
1.497 + * Marshalling a JAXB element</a>.
1.498 + * @throws IllegalArgumentException
1.499 + * If any of the method parameters are null
1.500 + */
1.501 + public void marshal( Object jaxbElement, org.w3c.dom.Node node )
1.502 + throws JAXBException;
1.503 +
1.504 + /**
1.505 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
1.506 + * {@link javax.xml.stream.XMLStreamWriter}.
1.507 + *
1.508 + * @param jaxbElement
1.509 + * The content tree to be marshalled.
1.510 + * @param writer
1.511 + * XML will be sent to this writer.
1.512 + *
1.513 + * @throws JAXBException
1.514 + * If any unexpected problem occurs during the marshalling.
1.515 + * @throws MarshalException
1.516 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.517 + * returns false from its <tt>handleEvent</tt> method or the
1.518 + * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
1.519 + * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
1.520 + * Marshalling a JAXB element</a>.
1.521 + * @throws IllegalArgumentException
1.522 + * If any of the method parameters are null
1.523 + * @since JAXB 2.0
1.524 + */
1.525 + public void marshal( Object jaxbElement, javax.xml.stream.XMLStreamWriter writer )
1.526 + throws JAXBException;
1.527 +
1.528 + /**
1.529 + * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
1.530 + * {@link javax.xml.stream.XMLEventWriter}.
1.531 + *
1.532 + * @param jaxbElement
1.533 + * The content tree rooted at jaxbElement to be marshalled.
1.534 + * @param writer
1.535 + * XML will be sent to this writer.
1.536 + *
1.537 + * @throws JAXBException
1.538 + * If any unexpected problem occurs during the marshalling.
1.539 + * @throws MarshalException
1.540 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.541 + * returns false from its <tt>handleEvent</tt> method or the
1.542 + * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
1.543 + * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
1.544 + * Marshalling a JAXB element</a>.
1.545 + * @throws IllegalArgumentException
1.546 + * If any of the method parameters are null
1.547 + * @since JAXB 2.0
1.548 + */
1.549 + public void marshal( Object jaxbElement, javax.xml.stream.XMLEventWriter writer )
1.550 + throws JAXBException;
1.551 +
1.552 + /**
1.553 + * Get a DOM tree view of the content tree(Optional).
1.554 + *
1.555 + * If the returned DOM tree is updated, these changes are also
1.556 + * visible in the content tree.
1.557 + * Use {@link #marshal(Object, org.w3c.dom.Node)} to force
1.558 + * a deep copy of the content tree to a DOM representation.
1.559 + *
1.560 + * @param contentTree - JAXB Java representation of XML content
1.561 + *
1.562 + * @return the DOM tree view of the contentTree
1.563 + *
1.564 + * @throws UnsupportedOperationException
1.565 + * If the JAXB provider implementation does not support a
1.566 + * DOM view of the content tree
1.567 + *
1.568 + * @throws IllegalArgumentException
1.569 + * If any of the method parameters are null
1.570 + *
1.571 + * @throws JAXBException
1.572 + * If any unexpected problem occurs
1.573 + *
1.574 + */
1.575 + public org.w3c.dom.Node getNode( java.lang.Object contentTree )
1.576 + throws JAXBException;
1.577 +
1.578 + /**
1.579 + * Set the particular property in the underlying implementation of
1.580 + * <tt>Marshaller</tt>. This method can only be used to set one of
1.581 + * the standard JAXB defined properties above or a provider specific
1.582 + * property. Attempting to set an undefined property will result in
1.583 + * a PropertyException being thrown. See <a href="#supportedProps">
1.584 + * Supported Properties</a>.
1.585 + *
1.586 + * @param name the name of the property to be set. This value can either
1.587 + * be specified using one of the constant fields or a user
1.588 + * supplied string.
1.589 + * @param value the value of the property to be set
1.590 + *
1.591 + * @throws PropertyException when there is an error processing the given
1.592 + * property or value
1.593 + * @throws IllegalArgumentException
1.594 + * If the name parameter is null
1.595 + */
1.596 + public void setProperty( String name, Object value )
1.597 + throws PropertyException;
1.598 +
1.599 + /**
1.600 + * Get the particular property in the underlying implementation of
1.601 + * <tt>Marshaller</tt>. This method can only be used to get one of
1.602 + * the standard JAXB defined properties above or a provider specific
1.603 + * property. Attempting to get an undefined property will result in
1.604 + * a PropertyException being thrown. See <a href="#supportedProps">
1.605 + * Supported Properties</a>.
1.606 + *
1.607 + * @param name the name of the property to retrieve
1.608 + * @return the value of the requested property
1.609 + *
1.610 + * @throws PropertyException
1.611 + * when there is an error retrieving the given property or value
1.612 + * property name
1.613 + * @throws IllegalArgumentException
1.614 + * If the name parameter is null
1.615 + */
1.616 + public Object getProperty( String name ) throws PropertyException;
1.617 +
1.618 + /**
1.619 + * Allow an application to register a validation event handler.
1.620 + * <p>
1.621 + * The validation event handler will be called by the JAXB Provider if any
1.622 + * validation errors are encountered during calls to any of the marshal
1.623 + * API's. If the client application does not register a validation event
1.624 + * handler before invoking one of the marshal methods, then validation
1.625 + * events will be handled by the default event handler which will terminate
1.626 + * the marshal operation after the first error or fatal error is encountered.
1.627 + * <p>
1.628 + * Calling this method with a null parameter will cause the Marshaller
1.629 + * to revert back to the default default event handler.
1.630 + *
1.631 + * @param handler the validation event handler
1.632 + * @throws JAXBException if an error was encountered while setting the
1.633 + * event handler
1.634 + */
1.635 + public void setEventHandler( ValidationEventHandler handler )
1.636 + throws JAXBException;
1.637 +
1.638 + /**
1.639 + * Return the current event handler or the default event handler if one
1.640 + * hasn't been set.
1.641 + *
1.642 + * @return the current ValidationEventHandler or the default event handler
1.643 + * if it hasn't been set
1.644 + * @throws JAXBException if an error was encountered while getting the
1.645 + * current event handler
1.646 + */
1.647 + public ValidationEventHandler getEventHandler()
1.648 + throws JAXBException;
1.649 +
1.650 +
1.651 +
1.652 + /**
1.653 + * Associates a configured instance of {@link XmlAdapter} with this marshaller.
1.654 + *
1.655 + * <p>
1.656 + * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
1.657 + *
1.658 + * @see #setAdapter(Class,XmlAdapter)
1.659 + * @throws IllegalArgumentException
1.660 + * if the adapter parameter is null.
1.661 + * @throws UnsupportedOperationException
1.662 + * if invoked agains a JAXB 1.0 implementation.
1.663 + * @since JAXB 2.0
1.664 + */
1.665 + public void setAdapter( XmlAdapter adapter );
1.666 +
1.667 + /**
1.668 + * Associates a configured instance of {@link XmlAdapter} with this marshaller.
1.669 + *
1.670 + * <p>
1.671 + * Every marshaller internally maintains a
1.672 + * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
1.673 + * which it uses for marshalling classes whose fields/methods are annotated
1.674 + * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
1.675 + *
1.676 + * <p>
1.677 + * This method allows applications to use a configured instance of {@link XmlAdapter}.
1.678 + * When an instance of an adapter is not given, a marshaller will create
1.679 + * one by invoking its default constructor.
1.680 + *
1.681 + * @param type
1.682 + * The type of the adapter. The specified instance will be used when
1.683 + * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
1.684 + * refers to this type.
1.685 + * @param adapter
1.686 + * The instance of the adapter to be used. If null, it will un-register
1.687 + * the current adapter set for this type.
1.688 + * @throws IllegalArgumentException
1.689 + * if the type parameter is null.
1.690 + * @throws UnsupportedOperationException
1.691 + * if invoked agains a JAXB 1.0 implementation.
1.692 + * @since JAXB 2.0
1.693 + */
1.694 + public <A extends XmlAdapter> void setAdapter( Class<A> type, A adapter );
1.695 +
1.696 + /**
1.697 + * Gets the adapter associated with the specified type.
1.698 + *
1.699 + * This is the reverse operation of the {@link #setAdapter} method.
1.700 + *
1.701 + * @throws IllegalArgumentException
1.702 + * if the type parameter is null.
1.703 + * @throws UnsupportedOperationException
1.704 + * if invoked agains a JAXB 1.0 implementation.
1.705 + * @since JAXB 2.0
1.706 + */
1.707 + public <A extends XmlAdapter> A getAdapter( Class<A> type );
1.708 +
1.709 +
1.710 + /**
1.711 + * <p>Associate a context that enables binary data within an XML document
1.712 + * to be transmitted as XML-binary optimized attachment.
1.713 + * The attachment is referenced from the XML document content model
1.714 + * by content-id URIs(cid) references stored within the xml document.
1.715 + *
1.716 + * @throws IllegalStateException if attempt to concurrently call this
1.717 + * method during a marshal operation.
1.718 + */
1.719 + void setAttachmentMarshaller(AttachmentMarshaller am);
1.720 +
1.721 + AttachmentMarshaller getAttachmentMarshaller();
1.722 +
1.723 + /**
1.724 + * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
1.725 + * object that should be used to validate subsequent marshal operations
1.726 + * against. Passing null into this method will disable validation.
1.727 + *
1.728 + * <p>
1.729 + * This method allows the caller to validate the marshalled XML as it's marshalled.
1.730 + *
1.731 + * <p>
1.732 + * Initially this property is set to <tt>null</tt>.
1.733 + *
1.734 + * @param schema Schema object to validate marshal operations against or null to disable validation
1.735 + * @throws UnsupportedOperationException could be thrown if this method is
1.736 + * invoked on an Marshaller created from a JAXBContext referencing
1.737 + * JAXB 1.0 mapped classes
1.738 + * @since JAXB2.0
1.739 + */
1.740 + public void setSchema( Schema schema );
1.741 +
1.742 + /**
1.743 + * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
1.744 + * being used to perform marshal-time validation. If there is no
1.745 + * Schema set on the marshaller, then this method will return null
1.746 + * indicating that marshal-time validation will not be performed.
1.747 + *
1.748 + * @return the Schema object being used to perform marshal-time
1.749 + * validation or null if not present.
1.750 + * @throws UnsupportedOperationException could be thrown if this method is
1.751 + * invoked on an Marshaller created from a JAXBContext referencing
1.752 + * JAXB 1.0 mapped classes
1.753 + * @since JAXB2.0
1.754 + */
1.755 + public Schema getSchema();
1.756 +
1.757 + /**
1.758 + * <p/>
1.759 + * Register an instance of an implementation of this class with a {@link Marshaller} to externally listen
1.760 + * for marshal events.
1.761 + * <p/>
1.762 + * <p/>
1.763 + * This class enables pre and post processing of each marshalled object.
1.764 + * The event callbacks are called when marshalling from an instance that maps to an xml element or
1.765 + * complex type definition. The event callbacks are not called when marshalling from an instance of a
1.766 + * Java datatype that represents a simple type definition.
1.767 + * <p/>
1.768 + * <p/>
1.769 + * External listener is one of two different mechanisms for defining marshal event callbacks.
1.770 + * See <a href="Marshaller.html#marshalEventCallback">Marshal Event Callbacks</a> for an overview.
1.771 + *
1.772 + * @see Marshaller#setListener(Listener)
1.773 + * @see Marshaller#getListener()
1.774 + * @since JAXB2.0
1.775 + */
1.776 + public static abstract class Listener {
1.777 + /**
1.778 + * <p/>
1.779 + * Callback method invoked before marshalling from <tt>source</tt> to XML.
1.780 + * <p/>
1.781 + * <p/>
1.782 + * This method is invoked just before marshalling process starts to marshal <tt>source</tt>.
1.783 + * Note that if the class of <tt>source</tt> defines its own <tt>beforeMarshal</tt> method,
1.784 + * the class specific callback method is invoked just before this method is invoked.
1.785 + *
1.786 + * @param source instance of JAXB mapped class prior to marshalling from it.
1.787 + */
1.788 + public void beforeMarshal(Object source) {
1.789 + }
1.790 +
1.791 + /**
1.792 + * <p/>
1.793 + * Callback method invoked after marshalling <tt>source</tt> to XML.
1.794 + * <p/>
1.795 + * <p/>
1.796 + * This method is invoked after <tt>source</tt> and all its descendants have been marshalled.
1.797 + * Note that if the class of <tt>source</tt> defines its own <tt>afterMarshal</tt> method,
1.798 + * the class specific callback method is invoked just before this method is invoked.
1.799 + *
1.800 + * @param source instance of JAXB mapped class after marshalling it.
1.801 + */
1.802 + public void afterMarshal(Object source) {
1.803 + }
1.804 + }
1.805 +
1.806 + /**
1.807 + * <p>
1.808 + * Register marshal event callback {@link Listener} with this {@link Marshaller}.
1.809 + *
1.810 + * <p>
1.811 + * There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener.
1.812 + * One can unregister current Listener by setting listener to <tt>null</tt>.
1.813 + *
1.814 + * @param listener an instance of a class that implements {@link Listener}
1.815 + * @since JAXB2.0
1.816 + */
1.817 + public void setListener(Listener listener);
1.818 +
1.819 + /**
1.820 + * <p>Return {@link Listener} registered with this {@link Marshaller}.
1.821 + *
1.822 + * @return registered {@link Listener} or <code>null</code> if no Listener is registered with this Marshaller.
1.823 + * @since JAXB2.0
1.824 + */
1.825 + public Listener getListener();
1.826 +}
