marshaller.html

来自「j2ee帮助文档软件设计/软件工程 文件格式」· HTML 代码 · 共 1,114 行 · 第 1/5 页

 <A HREF="../../../javax/xml/bind/MarshalException.html" title="class in javax.xml.bind"><CODE>MarshalException</CODE></A>. 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 <A HREF="../../../javax/xml/bind/JAXBElement.html" title="class in javax.xml.bind"><CODE>JAXBElement</CODE></A>, 
 and pass the wrapper element as the first parameter to 
 a <tt>Marshaller.marshal</tt> method. For java to schema binding, it 
 is also possible to simply annotate the instance's class with 
 &#64;<A HREF="../../../javax/xml/bind/annotation/XmlRootElement.html" title="annotation in javax.xml.bind.annotation"><CODE>XmlRootElement</CODE></A>.
 </blockquote>

 <p>
 <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 
 <A HREF="../../../javax/xml/bind/Marshaller.html#setProperty(java.lang.String, java.lang.Object)"><CODE>setProperty</CODE></A> 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
 <a href="http://www.w3.org/TR/2000/REC-xml-20001006#charencoding">W3C XML 1.0
 Recommendation</a> and supported by your 
 <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc">
 Java Platform</a>.
 </blockquote>
 
 <p>
 <b>Validation and Well-Formedness</b><br>
 <blockquote>
 <p>
 Client applications are not required to validate the Java content tree prior
 to calling any of the marshal API's.  Furthermore, there is no requirement 
 that the Java content tree be valid with respect to its original schema in
 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
 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.
 <p>
 Even when schema validation is not explictly enabled for the marshal operation,
 it is possible that certain types of validation events will be detected 
 during the operation.  Validation events will be reported to the registered
 event handler.  If the client application has not registered an event handler
 prior to invoking one of the marshal API's, then events will be delivered to
 a default event handler which will terminate the marshal operation after
 encountering the first error or fatal error. Note that for JAXB 2.0 and
 later versions, <A HREF="../../../javax/xml/bind/helpers/DefaultValidationEventHandler.html" title="class in javax.xml.bind.helpers"><CODE>DefaultValidationEventHandler</CODE></A> is
 no longer used.
 
 </blockquote>

 <p>
 <a name="supportedProps"></a>
 <b>Supported Properties</b><br>
 <blockquote>
 <p>
 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</dd>
   <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</dd>
   <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</dd>
   <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 
       understand, non-normative form in 
       <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6 
       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</dd>
   <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 
       an easy to understand, non-normative form in 
       <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6 
       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</dd>
   <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
       on which marshal api you are using - when this property is set to true:<br>
       <ul>
         <li><A HREF="../../../javax/xml/bind/Marshaller.html#marshal(java.lang.Object, org.xml.sax.ContentHandler)"><CODE>marshal(Object,ContentHandler)</CODE></A> - the Marshaller won't
             invoke <A HREF="http://java.sun.com/j2se/1.5/docs/api/org/xml/sax/ContentHandler.html#startDocument()" title="class or interface in org.xml.sax"><CODE>ContentHandler.startDocument()</CODE></A> and
             <A HREF="http://java.sun.com/j2se/1.5/docs/api/org/xml/sax/ContentHandler.html#endDocument()" title="class or interface in org.xml.sax"><CODE>ContentHandler.endDocument()</CODE></A>.</li>
         <li><A HREF="../../../javax/xml/bind/Marshaller.html#marshal(java.lang.Object, org.w3c.dom.Node)"><CODE>marshal(Object,Node)</CODE></A> - the property has no effect on this
             API.</li>
         <li><A HREF="../../../javax/xml/bind/Marshaller.html#marshal(java.lang.Object, java.io.OutputStream)"><CODE>marshal(Object,OutputStream)</CODE></A> - the Marshaller won't
             generate an xml declaration.</li>
         <li><A HREF="../../../javax/xml/bind/Marshaller.html#marshal(java.lang.Object, java.io.Writer)"><CODE>marshal(Object,Writer)</CODE></A> - the Marshaller won't
             generate an xml declaration.</li>
         <li><A HREF="../../../javax/xml/bind/Marshaller.html#marshal(java.lang.Object, javax.xml.transform.Result)"><CODE>marshal(Object,Result)</CODE></A> - depends on the kind of
             Result object, see semantics for Node, ContentHandler, and Stream APIs</li>
         <li><A HREF="../../../javax/xml/bind/Marshaller.html#marshal(java.lang.Object, javax.xml.stream.XMLEventWriter)"><CODE>marshal(Object,XMLEventWriter)</CODE></A> - the
             Marshaller will not generate <A HREF="../../../javax/xml/stream/XMLStreamConstants.html#START_DOCUMENT"><CODE>XMLStreamConstants.START_DOCUMENT</CODE></A> and
             <A HREF="../../../javax/xml/stream/XMLStreamConstants.html#END_DOCUMENT"><CODE>XMLStreamConstants.END_DOCUMENT</CODE></A> events.</li>
         <li><A HREF="../../../javax/xml/bind/Marshaller.html#marshal(java.lang.Object, javax.xml.stream.XMLStreamWriter)"><CODE>marshal(Object,XMLStreamWriter)</CODE></A> - the
             Marshaller will not generate <A HREF="../../../javax/xml/stream/XMLStreamConstants.html#START_DOCUMENT"><CODE>XMLStreamConstants.START_DOCUMENT</CODE></A> and
             <A HREF="../../../javax/xml/stream/XMLStreamConstants.html#END_DOCUMENT"><CODE>XMLStreamConstants.END_DOCUMENT</CODE></A> events.</li>
       </ul>
   </dd>
 </dl>
 </blockquote>
 
 <p>
 <a name="marshalEventCallback"></a>
 <b>Marshal Event Callbacks</b><br>
 <blockquote>
 "The <A HREF="../../../javax/xml/bind/Marshaller.html" title="interface in javax.xml.bind"><CODE>Marshaller</CODE></A> provides two styles of callback mechanisms
 that allow application specific processing during key points in the
 unmarshalling process.  In 'class defined' event callbacks, application
 specific code placed in JAXB mapped classes is triggered during
 marshalling.  'External listeners' allow for centralized processing
 of marshal events in one callback method rather than by type event callbacks.

 <p>
 Class defined event callback methods allow any JAXB mapped class to specify 
 its own specific callback methods by defining methods with the following method signatures:
 <blockquote>
 <pre>
   // Invoked by Marshaller after it has created an instance of this object.
   boolean beforeMarshal(Marshaller, Object parent);
 
   // Invoked by Marshaller after it has marshalled all properties of this object.
   void afterMmarshal(Marshaller, Object parent);
 </pre>
 </blockquote>
 The class defined event callback methods should be used when the callback method requires
 access to non-public methods and/or fields of the class. 
 <p>
 The external listener callback mechanism enables the registration of a <A HREF="../../../javax/xml/bind/Marshaller.Listener.html" title="class in javax.xml.bind"><CODE>Marshaller.Listener</CODE></A> 
 instance with a <A HREF="../../../javax/xml/bind/Marshaller.html#setListener(javax.xml.bind.Marshaller.Listener)"><CODE>setListener(Listener)</CODE></A>. The external listener receives all callback events, 
 allowing for more centralized processing than per class defined callback methods.
 <p>
 The 'class defined' and external listener event callback methods are independent of each other,
 both can be called for one event. The invocation ordering when both listener callback methods exist is
 defined in <A HREF="../../../javax/xml/bind/Marshaller.Listener.html#beforeMarshal(java.lang.Object)"><CODE>Marshaller.Listener.beforeMarshal(Object)</CODE></A> and <A HREF="../../../javax/xml/bind/Marshaller.Listener.html#afterMarshal(java.lang.Object)"><CODE>Marshaller.Listener.afterMarshal(Object)</CODE></A>.
 <p>
 An event callback method throwing an exception terminates the current marshal process.
 </blockquote>
<P>

<P>
<DL>
<DT><B>Since:</B></DT>
  <DD>JAXB1.0</DD>
<DT><B>Version:</B></DT>
  <DD>$Revision: 1.19 $ $Date: 2006/03/08 16:54:42 $</DD>
<DT><B>Author:</B></DT>
  <DD><ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul></DD>
<DT><B>See Also:</B><DD><A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A>, 
<A HREF="../../../javax/xml/bind/Validator.html" title="interface in javax.xml.bind"><CODE>Validator</CODE></A>, 
<A HREF="../../../javax/xml/bind/Unmarshaller.html" title="interface in javax.xml.bind"><CODE>Unmarshaller</CODE></A></DL>
<HR>

<P>
<!-- ======== NESTED CLASS SUMMARY ======== -->

<A NAME="nested_class_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Nested Class Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;class</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/xml/bind/Marshaller.Listener.html" title="class in javax.xml.bind">Marshaller.Listener</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<p/>
 Register an instance of an implementation of this class with a <A HREF="../../../javax/xml/bind/Marshaller.html" title="interface in javax.xml.bind"><CODE>Marshaller</CODE></A> to externally listen
 for marshal events.</TD>
</TR>
</TABLE>
&nbsp;<!-- =========== FIELD SUMMARY =========== -->

<A NAME="field_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Field Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="http://java.sun.com/j2se/1.5/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/xml/bind/Marshaller.html#JAXB_ENCODING">JAXB_ENCODING</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The name of the property used to specify the output encoding in
 the marshalled XML data.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="http://java.sun.com/j2se/1.5/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/xml/bind/Marshaller.html#JAXB_FORMATTED_OUTPUT">JAXB_FORMATTED_OUTPUT</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The name of the property used to specify whether or not the marshalled 
 XML data is formatted with linefeeds and indentation.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="http://java.sun.com/j2se/1.5/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/xml/bind/Marshaller.html#JAXB_FRAGMENT">JAXB_FRAGMENT</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The name of the property used to specify whether or not the marshaller
 will generate document level events (ie calling startDocument or endDocument).</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">