--- a/jaxws/src/java.xml.bind/share/classes/javax/xml/bind/Marshaller.java Wed Jul 05 20:50:41 2017 +0200
+++ b/jaxws/src/java.xml.bind/share/classes/javax/xml/bind/Marshaller.java Thu Sep 24 18:26:42 2015 +0300
@@ -33,7 +33,7 @@
/**
* <p>
- * The <tt>Marshaller</tt> class is responsible for governing the process
+ * The {@code Marshaller} class is responsible for governing the process
* of serializing Java content trees back into XML data. It provides the basic
* marshalling methods:
*
@@ -153,15 +153,15 @@
* <b>Marshalling content tree rooted by a JAXB element</b><br>
* <blockquote>
* The first parameter of the overloaded
- * <tt>Marshaller.marshal(java.lang.Object, ...)</tt> methods must be a
+ * {@code Marshaller.marshal(java.lang.Object, ...)} methods must be a
* JAXB element as computed by
* {@link JAXBIntrospector#isElement(java.lang.Object)};
- * otherwise, a <tt>Marshaller.marshal</tt> method must throw a
+ * otherwise, a {@code Marshaller.marshal} method must throw a
* {@link MarshalException}. There exist two mechanisms
* to enable marshalling an instance that is not a JAXB element.
* One method is to wrap the instance as a value of a {@link JAXBElement},
* and pass the wrapper element as the first parameter to
- * a <tt>Marshaller.marshal</tt> method. For java to schema binding, it
+ * a {@code Marshaller.marshal} method. For java to schema binding, it
* is also possible to simply annotate the instance's class with
* @{@link XmlRootElement}.
* </blockquote>
@@ -170,7 +170,7 @@
* <b>Encoding</b><br>
* <blockquote>
* By default, the Marshaller will use UTF-8 encoding when generating XML data
- * to a <tt>java.io.OutputStream</tt>, or a <tt>java.io.Writer</tt>. Use the
+ * to a {@code java.io.OutputStream}, or a {@code java.io.Writer}. Use the
* {@link #setProperty(String,Object) setProperty} API to change the output
* encoding used during these marshal operations. Client applications are
* expected to supply a valid character encoding name as defined in the
@@ -188,7 +188,7 @@
* order to marshal it back into XML data. Different JAXB Providers will
* support marshalling invalid Java content trees at varying levels, however
* all JAXB Providers must be able to marshal a valid content tree back to
- * XML data. A JAXB Provider must throw a <tt>MarshalException</tt> when it
+ * XML data. A JAXB Provider must throw a {@code MarshalException} when it
* is unable to complete the marshal operation due to invalid content. Some
* JAXB Providers will fully allow marshalling invalid content, others will fail
* on the first validation error.
@@ -213,18 +213,18 @@
* All JAXB Providers are required to support the following set of properties.
* Some providers may support additional properties.
* <dl>
- * <dt><tt>jaxb.encoding</tt> - value must be a java.lang.String</dt>
+ * <dt>{@code jaxb.encoding} - value must be a java.lang.String</dt>
* <dd>The output encoding to use when marshalling the XML data. The
* Marshaller will use "UTF-8" by default if this property is not
* specified.</dd>
- * <dt><tt>jaxb.formatted.output</tt> - value must be a java.lang.Boolean</dt>
+ * <dt>{@code jaxb.formatted.output} - value must be a java.lang.Boolean</dt>
* <dd>This property controls whether or not the Marshaller will format
* the resulting XML data with line breaks and indentation. A
* true value for this property indicates human readable indented
* xml data, while a false value indicates unformatted xml data.
* The Marshaller will default to false (unformatted) if this
* property is not specified.</dd>
- * <dt><tt>jaxb.schemaLocation</tt> - value must be a java.lang.String</dt>
+ * <dt>{@code jaxb.schemaLocation} - value must be a java.lang.String</dt>
* <dd>This property allows the client application to specify an
* xsi:schemaLocation attribute in the generated XML data. The format of
* the schemaLocation attribute value is discussed in an easy to
@@ -233,7 +233,7 @@
* of the W3C XML Schema Part 0: Primer</a> and specified in
* <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
* Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
- * <dt><tt>jaxb.noNamespaceSchemaLocation</tt> - value must be a java.lang.String</dt>
+ * <dt>{@code jaxb.noNamespaceSchemaLocation} - value must be a java.lang.String</dt>
* <dd>This property allows the client application to specify an
* xsi:noNamespaceSchemaLocation attribute in the generated XML
* data. The format of the schemaLocation attribute value is discussed in
@@ -242,10 +242,10 @@
* of the W3C XML Schema Part 0: Primer</a> and specified in
* <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
* Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
- * <dt><tt>jaxb.fragment</tt> - value must be a java.lang.Boolean</dt>
+ * <dt>{@code jaxb.fragment} - value must be a java.lang.Boolean</dt>
* <dd>This property determines whether or not document level events will be
* generated by the Marshaller. If the property is not specified, the
- * default is <tt>false</tt>. This property has different implications depending
+ * default is {@code false}. This property has different implications depending
* on which marshal api you are using - when this property is set to true:<br>
* <ul>
* <li>{@link #marshal(Object,org.xml.sax.ContentHandler) marshal(Object,ContentHandler)} - the Marshaller won't
@@ -352,15 +352,15 @@
"jaxb.fragment";
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into the specified
- * <tt>javax.xml.transform.Result</tt>.
+ * Marshal the content tree rooted at {@code jaxbElement} into the specified
+ * {@code javax.xml.transform.Result}.
*
* <p>
* All JAXB Providers must at least support
* {@link javax.xml.transform.dom.DOMResult},
* {@link javax.xml.transform.sax.SAXResult}, and
* {@link javax.xml.transform.stream.StreamResult}. It can
- * support other derived classes of <tt>Result</tt> as well.
+ * support other derived classes of {@code Result} as well.
*
* @param jaxbElement
* The root of content tree to be marshalled.
@@ -371,9 +371,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
- * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code obj} (or any
+ * object reachable from {@code obj}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -382,7 +382,7 @@
throws JAXBException;
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into an output stream.
+ * Marshal the content tree rooted at {@code jaxbElement} into an output stream.
*
* @param jaxbElement
* The root of content tree to be marshalled.
@@ -393,9 +393,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
- * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code obj} (or any
+ * object reachable from {@code obj}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -404,7 +404,7 @@
throws JAXBException;
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into a file.
+ * Marshal the content tree rooted at {@code jaxbElement} into a file.
*
* @param jaxbElement
* The root of content tree to be marshalled.
@@ -415,9 +415,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
- * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code obj} (or any
+ * object reachable from {@code obj}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -427,7 +427,7 @@
throws JAXBException;
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into a Writer.
+ * Marshal the content tree rooted at {@code jaxbElement} into a Writer.
*
* @param jaxbElement
* The root of content tree to be marshalled.
@@ -438,9 +438,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
- * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code obj} (or any
+ * object reachable from {@code obj}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -449,7 +449,7 @@
throws JAXBException;
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into SAX2 events.
+ * Marshal the content tree rooted at {@code jaxbElement} into SAX2 events.
*
* @param jaxbElement
* The root of content tree to be marshalled.
@@ -460,9 +460,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
- * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code obj} (or any
+ * object reachable from {@code obj}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -471,7 +471,7 @@
throws JAXBException;
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into a DOM tree.
+ * Marshal the content tree rooted at {@code jaxbElement} into a DOM tree.
*
* @param jaxbElement
* The content tree to be marshalled.
@@ -486,9 +486,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>jaxbElement</tt> (or any
- * object reachable from <tt>jaxbElement</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code jaxbElement} (or any
+ * object reachable from {@code jaxbElement}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -497,7 +497,7 @@
throws JAXBException;
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
+ * Marshal the content tree rooted at {@code jaxbElement} into a
* {@link javax.xml.stream.XMLStreamWriter}.
*
* @param jaxbElement
@@ -509,9 +509,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
- * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code obj} (or any
+ * object reachable from {@code obj}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -521,7 +521,7 @@
throws JAXBException;
/**
- * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
+ * Marshal the content tree rooted at {@code jaxbElement} into a
* {@link javax.xml.stream.XMLEventWriter}.
*
* @param jaxbElement
@@ -533,9 +533,9 @@
* If any unexpected problem occurs during the marshalling.
* @throws MarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
- * returns false from its <tt>handleEvent</tt> method or the
- * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
- * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
+ * returns false from its {@code handleEvent} method or the
+ * {@code Marshaller} is unable to marshal {@code obj} (or any
+ * object reachable from {@code obj}). See <a href="#elementMarshalling">
* Marshalling a JAXB element</a>.
* @throws IllegalArgumentException
* If any of the method parameters are null
@@ -572,7 +572,7 @@
/**
* Set the particular property in the underlying implementation of
- * <tt>Marshaller</tt>. This method can only be used to set one of
+ * {@code Marshaller}. This method can only be used to set one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to set an undefined property will result in
* a PropertyException being thrown. See <a href="#supportedProps">
@@ -593,7 +593,7 @@
/**
* Get the particular property in the underlying implementation of
- * <tt>Marshaller</tt>. This method can only be used to get one of
+ * {@code Marshaller}. This method can only be used to get one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to get an undefined property will result in
* a PropertyException being thrown. See <a href="#supportedProps">
@@ -648,7 +648,7 @@
* Associates a configured instance of {@link XmlAdapter} with this marshaller.
*
* <p>
- * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
+ * This is a convenience method that invokes {@code setAdapter(adapter.getClass(),adapter);}.
*
* @see #setAdapter(Class,XmlAdapter)
* @throws IllegalArgumentException
@@ -724,7 +724,7 @@
* This method allows the caller to validate the marshalled XML as it's marshalled.
*
* <p>
- * Initially this property is set to <tt>null</tt>.
+ * Initially this property is set to {@code null}.
*
* @param schema Schema object to validate marshal operations against or null to disable validation
* @throws UnsupportedOperationException could be thrown if this method is
@@ -771,11 +771,11 @@
public static abstract class Listener {
/**
* <p>
- * Callback method invoked before marshalling from <tt>source</tt> to XML.
+ * Callback method invoked before marshalling from {@code source} to XML.
* </p>
* <p>
- * This method is invoked just before marshalling process starts to marshal <tt>source</tt>.
- * Note that if the class of <tt>source</tt> defines its own <tt>beforeMarshal</tt> method,
+ * This method is invoked just before marshalling process starts to marshal {@code source}.
+ * Note that if the class of {@code source} defines its own {@code beforeMarshal} method,
* the class specific callback method is invoked just before this method is invoked.
*
* @param source instance of JAXB mapped class prior to marshalling from it.
@@ -785,11 +785,11 @@
/**
* <p>
- * Callback method invoked after marshalling <tt>source</tt> to XML.
+ * Callback method invoked after marshalling {@code source} to XML.
* </p>
* <p>
- * This method is invoked after <tt>source</tt> and all its descendants have been marshalled.
- * Note that if the class of <tt>source</tt> defines its own <tt>afterMarshal</tt> method,
+ * This method is invoked after {@code source} and all its descendants have been marshalled.
+ * Note that if the class of {@code source} defines its own {@code afterMarshal} method,
* the class specific callback method is invoked just before this method is invoked.
*
* @param source instance of JAXB mapped class after marshalling it.
@@ -804,7 +804,7 @@
*
* <p>
* There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener.
- * One can unregister current Listener by setting listener to <tt>null</tt>.
+ * One can unregister current Listener by setting listener to {@code null}.
*
* @param listener an instance of a class that implements {@link Listener}
* @since 1.6, JAXB 2.0
@@ -814,7 +814,8 @@
/**
* <p>Return {@link Listener} registered with this {@link Marshaller}.
*
- * @return registered {@link Listener} or <code>null</code> if no Listener is registered with this Marshaller.
+ * @return registered {@link Listener} or {@code null}
+ * if no Listener is registered with this Marshaller.
* @since 1.6, JAXB 2.0
*/
public Listener getListener();