KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > bind > Marshaller


1 /*
2  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
3  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4  */
5
6 package javax.xml.bind;
7
8 import javax.xml.bind.annotation.XmlRootElement;
9 import javax.xml.bind.annotation.adapters.XmlAdapter;
10 import javax.xml.bind.attachment.AttachmentMarshaller;
11 import javax.xml.validation.Schema JavaDoc;
12 import java.io.File JavaDoc;
13
14 /**
15  * <p>
16  * The <tt>Marshaller</tt> class is responsible for governing the process
17  * of serializing Java content trees back into XML data. It provides the basic
18  * marshalling methods:
19  *
20  * <p>
21  * <i>Assume the following setup code for all following code fragments:</i>
22  * <blockquote>
23  * <pre>
24  * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
25  * Unmarshaller u = jc.createUnmarshaller();
26  * Object element = u.unmarshal( new File( "foo.xml" ) );
27  * Marshaller m = jc.createMarshaller();
28  * </pre>
29  * </blockquote>
30  *
31  * <p>
32  * Marshalling to a File:
33  * <blockquote>
34  * <pre>
35  * OutputStream os = new FileOutputStream( "nosferatu.xml" );
36  * m.marshal( element, os );
37  * </pre>
38  * </blockquote>
39  *
40  * <p>
41  * Marshalling to a SAX ContentHandler:
42  * <blockquote>
43  * <pre>
44  * // assume MyContentHandler instanceof ContentHandler
45  * m.marshal( element, new MyContentHandler() );
46  * </pre>
47  * </blockquote>
48  *
49  * <p>
50  * Marshalling to a DOM Node:
51  * <blockquote>
52  * <pre>
53  * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
54  * dbf.setNamespaceAware(true);
55  * DocumentBuilder db = dbf.newDocumentBuilder();
56  * Document doc = db.newDocument();
57  *
58  * m.marshal( element, doc );
59  * </pre>
60  * </blockquote>
61  *
62  * <p>
63  * Marshalling to a java.io.OutputStream:
64  * <blockquote>
65  * <pre>
66  * m.marshal( element, System.out );
67  * </pre>
68  * </blockquote>
69  *
70  * <p>
71  * Marshalling to a java.io.Writer:
72  * <blockquote>
73  * <pre>
74  * m.marshal( element, new PrintWriter( System.out ) );
75  * </pre>
76  * </blockquote>
77  *
78  * <p>
79  * Marshalling to a javax.xml.transform.SAXResult:
80  * <blockquote>
81  * <pre>
82  * // assume MyContentHandler instanceof ContentHandler
83  * SAXResult result = new SAXResult( new MyContentHandler() );
84  *
85  * m.marshal( element, result );
86  * </pre>
87  * </blockquote>
88  *
89  * <p>
90  * Marshalling to a javax.xml.transform.DOMResult:
91  * <blockquote>
92  * <pre>
93  * DOMResult result = new DOMResult();
94  *
95  * m.marshal( element, result );
96  * </pre>
97  * </blockquote>
98  *
99  * <p>
100  * Marshalling to a javax.xml.transform.StreamResult:
101  * <blockquote>
102  * <pre>
103  * StreamResult result = new StreamResult( System.out );
104  *
105  * m.marshal( element, result );
106  * </pre>
107  * </blockquote>
108  *
109  * <p>
110  * Marshalling to a javax.xml.stream.XMLStreamWriter:
111  * <blockquote>
112  * <pre>
113  * XMLStreamWriter xmlStreamWriter =
114  * XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
115  *
116  * m.marshal( element, xmlStreamWriter );
117  * </pre>
118  * </blockquote>
119  *
120  * <p>
121  * Marshalling to a javax.xml.stream.XMLEventWriter:
122  * <blockquote>
123  * <pre>
124  * XMLEventWriter xmlEventWriter =
125  * XMLOutputFactory.newInstance().createXMLEventWriter( ... );
126  *
127  * m.marshal( element, xmlEventWriter );
128  * </pre>
129  * </blockquote>
130  *
131  * <p>
132  * <a name="elementMarshalling"></a>
133  * <b>Marshalling content tree rooted by a JAXB element</b><br>
134  * <blockquote>
135  * The first parameter of the overloaded
136  * <tt>Marshaller.marshal(java.lang.Object, ...)</tt> methods must be a
137  * JAXB element as computed by
138  * {@link JAXBIntrospector#isElement(java.lang.Object)};
139  * otherwise, a <tt>Marshaller.marshal</tt> method must throw a
140  * {@link MarshalException}. There exist two mechanisms
141  * to enable marshalling an instance that is not a JAXB element.
142  * One method is to wrap the instance as a value of a {@link JAXBElement},
143  * and pass the wrapper element as the first parameter to
144  * a <tt>Marshaller.marshal</tt> method. For java to schema binding, it
145  * is also possible to simply annotate the instance's class with
146  * &#64;{@link XmlRootElement}.
147  * </blockquote>
148  *
149  * <p>
150  * <b>Encoding</b><br>
151  * <blockquote>
152  * By default, the Marshaller will use UTF-8 encoding when generating XML data
153  * to a <tt>java.io.OutputStream</tt>, or a <tt>java.io.Writer</tt>. Use the
154  * {@link #setProperty(String,Object) setProperty} API to change the output
155  * encoding used during these marshal operations. Client applications are
156  * expected to supply a valid character encoding name as defined in the
157  * <a HREF="http://www.w3.org/TR/2000/REC-xml-20001006#charencoding">W3C XML 1.0
158  * Recommendation</a> and supported by your
159  * <a HREF="http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc">
160  * Java Platform</a>.
161  * </blockquote>
162  *
163  * <p>
164  * <b>Validation and Well-Formedness</b><br>
165  * <blockquote>
166  * <p>
167  * Client applications are not required to validate the Java content tree prior
168  * to calling any of the marshal API's. Furthermore, there is no requirement
169  * that the Java content tree be valid with respect to its original schema in
170  * order to marshal it back into XML data. Different JAXB Providers will
171  * support marshalling invalid Java content trees at varying levels, however
172  * all JAXB Providers must be able to marshal a valid content tree back to
173  * XML data. A JAXB Provider must throw a <tt>MarshalException</tt> when it
174  * is unable to complete the marshal operation due to invalid content. Some
175  * JAXB Providers will fully allow marshalling invalid content, others will fail
176  * on the first validation error.
177  * <p>
178  * Even when schema validation is not explictly enabled for the marshal operation,
179  * it is possible that certain types of validation events will be detected
180  * during the operation. Validation events will be reported to the registered
181  * event handler. If the client application has not registered an event handler
182  * prior to invoking one of the marshal API's, then events will be delivered to
183  * a default event handler which will terminate the marshal operation after
184  * encountering the first error or fatal error. Note that for JAXB 2.0 and
185  * later versions, {@link javax.xml.bind.helpers.DefaultValidationEventHandler} is
186  * no longer used.
187  *
188  * </blockquote>
189  *
190  * <p>
191  * <a name="supportedProps"></a>
192  * <b>Supported Properties</b><br>
193  * <blockquote>
194  * <p>
195  * All JAXB Providers are required to support the following set of properties.
196  * Some providers may support additional properties.
197  * <dl>
198  * <dt><tt>jaxb.encoding</tt> - value must be a java.lang.String</dd>
199  * <dd>The output encoding to use when marshalling the XML data. The
200  * Marshaller will use "UTF-8" by default if this property is not
201  * specified.</dd>
202  * <dt><tt>jaxb.formatted.output</tt> - value must be a java.lang.Boolean</dd>
203  * <dd>This property controls whether or not the Marshaller will format
204  * the resulting XML data with line breaks and indentation. A
205  * true value for this property indicates human readable indented
206  * xml data, while a false value indicates unformatted xml data.
207  * The Marshaller will default to false (unformatted) if this
208  * property is not specified.</dd>
209  * <dt><tt>jaxb.schemaLocation</tt> - value must be a java.lang.String</dd>
210  * <dd>This property allows the client application to specify an
211  * xsi:schemaLocation attribute in the generated XML data. The format of
212  * the schemaLocation attribute value is discussed in an easy to
213  * understand, non-normative form in
214  * <a HREF="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
215  * of the W3C XML Schema Part 0: Primer</a> and specified in
216  * <a HREF="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
217  * Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
218  * <dt><tt>jaxb.noNamespaceSchemaLocation</tt> - value must be a java.lang.String</dd>
219  * <dd>This property allows the client application to specify an
220  * xsi:noNamespaceSchemaLocation attribute in the generated XML
221  * data. The format of the schemaLocation attribute value is discussed in
222  * an easy to understand, non-normative form in
223  * <a HREF="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
224  * of the W3C XML Schema Part 0: Primer</a> and specified in
225  * <a HREF="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
226  * Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
227  * <dt><tt>jaxb.fragment</tt> - value must be a java.lang.Boolean</dd>
228  * <dd>This property determines whether or not document level events will be
229  * generated by the Marshaller. If the property is not specified, the
230  * default is <tt>false</tt>. This property has different implications depending
231  * on which marshal api you are using - when this property is set to true:<br>
232  * <ul>
233  * <li>{@link #marshal(Object,org.xml.sax.ContentHandler) marshal(Object,ContentHandler)} - the Marshaller won't
234  * invoke {@link org.xml.sax.ContentHandler#startDocument()} and
235  * {@link org.xml.sax.ContentHandler#endDocument()}.</li>
236  * <li>{@link #marshal(Object,org.w3c.dom.Node) marshal(Object,Node)} - the property has no effect on this
237  * API.</li>
238  * <li>{@link #marshal(Object,java.io.OutputStream) marshal(Object,OutputStream)} - the Marshaller won't
239  * generate an xml declaration.</li>
240  * <li>{@link #marshal(Object,java.io.Writer) marshal(Object,Writer)} - the Marshaller won't
241  * generate an xml declaration.</li>
242  * <li>{@link #marshal(Object,javax.xml.transform.Result) marshal(Object,Result)} - depends on the kind of
243  * Result object, see semantics for Node, ContentHandler, and Stream APIs</li>
244  * <li>{@link #marshal(Object,javax.xml.stream.XMLEventWriter) marshal(Object,XMLEventWriter)} - the
245  * Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and
246  * {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.</li>
247  * <li>{@link #marshal(Object,javax.xml.stream.XMLStreamWriter) marshal(Object,XMLStreamWriter)} - the
248  * Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and
249  * {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.</li>
250  * </ul>
251  * </dd>
252  * </dl>
253  * </blockquote>
254  *
255  * <p>
256  * <a name="marshalEventCallback"></a>
257  * <b>Marshal Event Callbacks</b><br>
258  * <blockquote>
259  * "The {@link Marshaller} provides two styles of callback mechanisms
260  * that allow application specific processing during key points in the
261  * unmarshalling process. In 'class defined' event callbacks, application
262  * specific code placed in JAXB mapped classes is triggered during
263  * marshalling. 'External listeners' allow for centralized processing
264  * of marshal events in one callback method rather than by type event callbacks.
265  *
266  * <p>
267  * Class defined event callback methods allow any JAXB mapped class to specify
268  * its own specific callback methods by defining methods with the following method signatures:
269  * <blockquote>
270  * <pre>
271  * // Invoked by Marshaller after it has created an instance of this object.
272  * boolean beforeMarshal(Marshaller);
273  *
274  * // Invoked by Marshaller after it has marshalled all properties of this object.
275  * void afterMmarshal(Marshaller);
276  * </pre>
277  * </blockquote>
278  * The class defined event callback methods should be used when the callback method requires
279  * access to non-public methods and/or fields of the class.
280  * <p>
281  * The external listener callback mechanism enables the registration of a {@link Listener}
282  * instance with a {@link Marshaller#setListener(Listener)}. The external listener receives all callback events,
283  * allowing for more centralized processing than per class defined callback methods.
284  * <p>
285  * The 'class defined' and external listener event callback methods are independent of each other,
286  * both can be called for one event. The invocation ordering when both listener callback methods exist is
287  * defined in {@link Listener#beforeMarshal(Object)} and {@link Listener#afterMarshal(Object)}.
288  * <p>
289  * An event callback method throwing an exception terminates the current marshal process.
290  * </blockquote>
291  *
292  * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
293  * @version $Revision$ $Date$
294  * @see JAXBContext
295  * @see Validator
296  * @see Unmarshaller
297  * @since JAXB1.0
298  */
299 public interface Marshaller {
300
301     /**
302      * The name of the property used to specify the output encoding in
303      * the marshalled XML data.
304      */
305     public static final String JavaDoc JAXB_ENCODING =
306         "jaxb.encoding";
307
308     /**
309      * The name of the property used to specify whether or not the marshalled
310      * XML data is formatted with linefeeds and indentation.
311      */
312     public static final String JavaDoc JAXB_FORMATTED_OUTPUT =
313         "jaxb.formatted.output";
314
315     /**
316      * The name of the property used to specify the xsi:schemaLocation
317      * attribute value to place in the marshalled XML output.
318      */
319     public static final String JavaDoc JAXB_SCHEMA_LOCATION =
320         "jaxb.schemaLocation";
321
322     /**
323      * The name of the property used to specify the
324      * xsi:noNamespaceSchemaLocation attribute value to place in the marshalled
325      * XML output.
326      */
327     public static final String JavaDoc JAXB_NO_NAMESPACE_SCHEMA_LOCATION =
328         "jaxb.noNamespaceSchemaLocation";
329
330     /**
331      * The name of the property used to specify whether or not the marshaller
332      * will generate document level events (ie calling startDocument or endDocument).
333      */
334     public static final String JavaDoc JAXB_FRAGMENT =
335         "jaxb.fragment";
336
337     /**
338      * Marshal the content tree rooted at <tt>jaxbElement</tt> into the specified
339      * <tt>javax.xml.transform.Result</tt>.
340      *
341      * <p>
342      * All JAXB Providers must at least support
343      * {@link javax.xml.transform.dom.DOMResult},
344      * {@link javax.xml.transform.sax.SAXResult}, and
345      * {@link javax.xml.transform.stream.StreamResult}. It can
346      * support other derived classes of <tt>Result</tt> as well.
347      *
348      * @param jaxbElement
349      * The root of content tree to be marshalled.
350      * @param result
351      * XML will be sent to this Result
352      *
353      * @throws JAXBException
354      * If any unexpected problem occurs during the marshalling.
355      * @throws MarshalException
356      * If the {@link ValidationEventHandler ValidationEventHandler}
357      * returns false from its <tt>handleEvent</tt> method or the
358      * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
359      * object reachable from <tt>obj</tt>). See <a HREF="#elementMarshalling">
360      * Marshalling a JAXB element</a>.
361      * @throws IllegalArgumentException
362      * If any of the method parameters are null
363      */
364     public void marshal( Object JavaDoc jaxbElement, javax.xml.transform.Result JavaDoc result )
365         throws JAXBException;
366
367     /**
368      * Marshal the content tree rooted at <tt>jaxbElement</tt> into an output stream.
369      *
370      * @param jaxbElement
371      * The root of content tree to be marshalled.
372      * @param os
373      * XML will be added to this stream.
374      *
375      * @throws JAXBException
376      * If any unexpected problem occurs during the marshalling.
377      * @throws MarshalException
378      * If the {@link ValidationEventHandler ValidationEventHandler}
379      * returns false from its <tt>handleEvent</tt> method or the
380      * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
381      * object reachable from <tt>obj</tt>). See <a HREF="#elementMarshalling">
382      * Marshalling a JAXB element</a>.
383      * @throws IllegalArgumentException
384      * If any of the method parameters are null
385      */
386     public void marshal( Object JavaDoc jaxbElement, java.io.OutputStream JavaDoc os )
387         throws JAXBException;
388
389     /**
390      * Marshal the content tree rooted at <tt>jaxbElement</tt> into a file.
391      *
392      * @param jaxbElement
393      * The root of content tree to be marshalled.
394      * @param output
395      * File to be written. If this file already exists, it will be overwritten.
396      *
397      * @throws JAXBException
398      * If any unexpected problem occurs during the marshalling.
399      * @throws MarshalException
400      * If the {@link ValidationEventHandler ValidationEventHandler}
401      * returns false from its <tt>handleEvent</tt> method or the
402      * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
403      * object reachable from <tt>obj</tt>). See <a HREF="#elementMarshalling">
404      * Marshalling a JAXB element</a>.
405      * @throws IllegalArgumentException
406      * If any of the method parameters are null
407      * @since JAXB2.1
408      */
409     public void marshal( Object JavaDoc jaxbElement, File JavaDoc output )
410         throws JAXBException;
411
412     /**
413      * Marshal the content tree rooted at <tt>jaxbElement</tt> into a Writer.
414      *
415      * @param jaxbElement
416      * The root of content tree to be marshalled.
417      * @param writer
418      * XML will be sent to this writer.
419      *
420      * @throws JAXBException
421      * If any unexpected problem occurs during the marshalling.
422      * @throws MarshalException
423      * If the {@link ValidationEventHandler ValidationEventHandler}
424      * returns false from its <tt>handleEvent</tt> method or the
425      * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
426      * object reachable from <tt>obj</tt>). See <a HREF="#elementMarshalling">
427      * Marshalling a JAXB element</a>.
428      * @throws IllegalArgumentException
429      * If any of the method parameters are null
430      */
431     public void marshal( Object JavaDoc jaxbElement, java.io.Writer JavaDoc writer )
432         throws JAXBException;
433
434     /**
435      * Marshal the content tree rooted at <tt>jaxbElement</tt> into SAX2 events.
436      *
437      * @param jaxbElement
438      * The root of content tree to be marshalled.
439      * @param handler
440      * XML will be sent to this handler as SAX2 events.
441      *
442      * @throws JAXBException
443      * If any unexpected problem occurs during the marshalling.
444      * @throws MarshalException
445      * If the {@link ValidationEventHandler ValidationEventHandler}
446      * returns false from its <tt>handleEvent</tt> method or the
447      * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
448      * object reachable from <tt>obj</tt>). See <a HREF="#elementMarshalling">
449      * Marshalling a JAXB element</a>.
450      * @throws IllegalArgumentException
451      * If any of the method parameters are null
452      */
453     public void marshal( Object JavaDoc jaxbElement, org.xml.sax.ContentHandler JavaDoc handler )
454         throws JAXBException;
455
456     /**
457      * Marshal the content tree rooted at <tt>jaxbElement</tt> into a DOM tree.
458      *
459      * @param jaxbElement
460      * The content tree to be marshalled.
461      * @param node
462      * DOM nodes will be added as children of this node.
463      * This parameter must be a Node that accepts children
464      * ({@link org.w3c.dom.Document},
465      * {@link org.w3c.dom.DocumentFragment}, or
466      * {@link org.w3c.dom.Element})
467      *
468      * @throws JAXBException
469      * If any unexpected problem occurs during the marshalling.
470      * @throws MarshalException
471      * If the {@link ValidationEventHandler ValidationEventHandler}
472      * returns false from its <tt>handleEvent</tt> method or the
473      * <tt>Marshaller</tt> is unable to marshal <tt>jaxbElement</tt> (or any
474      * object reachable from <tt>jaxbElement</tt>). See <a HREF="#elementMarshalling">
475      * Marshalling a JAXB element</a>.
476      * @throws IllegalArgumentException
477      * If any of the method parameters are null
478      */
479     public void marshal( Object JavaDoc jaxbElement, org.w3c.dom.Node JavaDoc node )
480         throws JAXBException;
481
482     /**
483      * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
484      * {@link javax.xml.stream.XMLStreamWriter}.
485      *
486      * @param jaxbElement
487      * The content tree to be marshalled.
488      * @param writer
489      * XML will be sent to this writer.
490      *
491      * @throws JAXBException
492      * If any unexpected problem occurs during the marshalling.
493      * @throws MarshalException
494      * If the {@link ValidationEventHandler ValidationEventHandler}
495      * returns false from its <tt>handleEvent</tt> method or the
496      * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
497      * object reachable from <tt>obj</tt>). See <a HREF="#elementMarshalling">
498      * Marshalling a JAXB element</a>.
499      * @throws IllegalArgumentException
500      * If any of the method parameters are null
501      * @since JAXB 2.0
502      */
503     public void marshal( Object JavaDoc jaxbElement, javax.xml.stream.XMLStreamWriter writer )
504         throws JAXBException;
505
506     /**
507      * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
508      * {@link javax.xml.stream.XMLEventWriter}.
509      *
510      * @param jaxbElement
511      * The content tree rooted at jaxbElement to be marshalled.
512      * @param writer
513      * XML will be sent to this writer.
514      *
515      * @throws JAXBException
516      * If any unexpected problem occurs during the marshalling.
517      * @throws MarshalException
518      * If the {@link ValidationEventHandler ValidationEventHandler}
519      * returns false from its <tt>handleEvent</tt> method or the
520      * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
521      * object reachable from <tt>obj</tt>). See <a HREF="#elementMarshalling">
522      * Marshalling a JAXB element</a>.
523      * @throws IllegalArgumentException
524      * If any of the method parameters are null
525      * @since JAXB 2.0
526      */
527     public void marshal( Object JavaDoc jaxbElement, javax.xml.stream.XMLEventWriter writer )
528         throws JAXBException;
529
530     /**
531      * Get a DOM tree view of the content tree(Optional).
532      *
533      * If the returned DOM tree is updated, these changes are also
534      * visible in the content tree.
535      * Use {@link #marshal(Object, org.w3c.dom.Node)} to force
536      * a deep copy of the content tree to a DOM representation.
537      *
538      * @param contentTree - JAXB Java representation of XML content
539      *
540      * @return the DOM tree view of the contentTree
541      *
542      * @throws UnsupportedOperationException
543      * If the JAXB provider implementation does not support a
544      * DOM view of the content tree
545      *
546      * @throws IllegalArgumentException
547      * If any of the method parameters are null
548      *
549      * @throws JAXBException
550      * If any unexpected problem occurs
551      *
552      */
553     public org.w3c.dom.Node JavaDoc getNode( java.lang.Object JavaDoc contentTree )
554         throws JAXBException;
555
556     /**
557      * Set the particular property in the underlying implementation of
558      * <tt>Marshaller</tt>. This method can only be used to set one of
559      * the standard JAXB defined properties above or a provider specific
560      * property. Attempting to set an undefined property will result in
561      * a PropertyException being thrown. See <a HREF="#supportedProps">
562      * Supported Properties</a>.
563      *
564      * @param name the name of the property to be set. This value can either
565      * be specified using one of the constant fields or a user
566      * supplied string.
567      * @param value the value of the property to be set
568      *
569      * @throws PropertyException when there is an error processing the given
570      * property or value
571      * @throws IllegalArgumentException
572      * If the name parameter is null
573      */
574     public void setProperty( String JavaDoc name, Object JavaDoc value )
575         throws PropertyException;
576
577     /**
578      * Get the particular property in the underlying implementation of
579      * <tt>Marshaller</tt>. This method can only be used to get one of
580      * the standard JAXB defined properties above or a provider specific
581      * property. Attempting to get an undefined property will result in
582      * a PropertyException being thrown. See <a HREF="#supportedProps">
583      * Supported Properties</a>.
584      *
585      * @param name the name of the property to retrieve
586      * @return the value of the requested property
587      *
588      * @throws PropertyException
589      * when there is an error retrieving the given property or value
590      * property name
591      * @throws IllegalArgumentException
592      * If the name parameter is null
593      */
594     public Object JavaDoc getProperty( String JavaDoc name ) throws PropertyException;
595
596     /**
597      * Allow an application to register a validation event handler.
598      * <p>
599      * The validation event handler will be called by the JAXB Provider if any
600      * validation errors are encountered during calls to any of the marshal
601      * API's. If the client application does not register a validation event
602      * handler before invoking one of the marshal methods, then validation
603      * events will be handled by the default event handler which will terminate
604      * the marshal operation after the first error or fatal error is encountered.
605      * <p>
606      * Calling this method with a null parameter will cause the Marshaller
607      * to revert back to the default default event handler.
608      *
609      * @param handler the validation event handler
610      * @throws JAXBException if an error was encountered while setting the
611      * event handler
612      */
613     public void setEventHandler( ValidationEventHandler handler )
614         throws JAXBException;
615
616     /**
617      * Return the current event handler or the default event handler if one
618      * hasn't been set.
619      *
620      * @return the current ValidationEventHandler or the default event handler
621      * if it hasn't been set
622      * @throws JAXBException if an error was encountered while getting the
623      * current event handler
624      */
625     public ValidationEventHandler getEventHandler()
626         throws JAXBException;
627
628
629
630     /**
631      * Associates a configured instance of {@link XmlAdapter} with this marshaller.
632      *
633      * <p>
634      * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
635      *
636      * @see #setAdapter(Class,XmlAdapter)
637      * @throws IllegalArgumentException
638      * if the adapter parameter is null.
639      * @throws UnsupportedOperationException
640      * if invoked agains a JAXB 1.0 implementation.
641      * @since JAXB 2.0
642      */
643     public void setAdapter( XmlAdapter adapter );
644
645     /**
646      * Associates a configured instance of {@link XmlAdapter} with this marshaller.
647      *
648      * <p>
649      * Every marshaller internally maintains a
650      * {@link java.util.Map}&lt;{@link Class},{@link XmlAdapter}>,
651      * which it uses for marshalling classes whose fields/methods are annotated
652      * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
653      *
654      * <p>
655      * This method allows applications to use a configured instance of {@link XmlAdapter}.
656      * When an instance of an adapter is not given, a marshaller will create
657      * one by invoking its default constructor.
658      *
659      * @param type
660      * The type of the adapter. The specified instance will be used when
661      * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
662      * refers to this type.
663      * @param adapter
664      * The instance of the adapter to be used. If null, it will un-register
665      * the current adapter set for this type.
666      * @throws IllegalArgumentException
667      * if the type parameter is null.
668      * @throws UnsupportedOperationException
669      * if invoked agains a JAXB 1.0 implementation.
670      * @since JAXB 2.0
671      */
672     public <A extends XmlAdapter> void setAdapter( Class JavaDoc<A> type, A adapter );
673
674     /**
675      * Gets the adapter associated with the specified type.
676      *
677      * This is the reverse operation of the {@link #setAdapter} method.
678      *
679      * @throws IllegalArgumentException
680      * if the type parameter is null.
681      * @throws UnsupportedOperationException
682      * if invoked agains a JAXB 1.0 implementation.
683      * @since JAXB 2.0
684      */
685     public <A extends XmlAdapter> A getAdapter( Class JavaDoc<A> type );
686
687
688     /**
689      * <p>Associate a context that enables binary data within an XML document
690      * to be transmitted as XML-binary optimized attachment.
691      * The attachment is referenced from the XML document content model
692      * by content-id URIs(cid) references stored within the xml document.
693      *
694      * @throws IllegalStateException if attempt to concurrently call this
695      * method during a marshal operation.
696      */
697     void setAttachmentMarshaller(AttachmentMarshaller am);
698
699     AttachmentMarshaller getAttachmentMarshaller();
700
701     /**
702      * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
703      * object that should be used to validate subsequent marshal operations
704      * against. Passing null into this method will disable validation.
705      *
706      * <p>
707      * This method allows the caller to validate the marshalled XML as it's marshalled.
708      *
709      * <p>
710      * Initially this property is set to <tt>null</tt>.
711      *
712      * @param schema Schema object to validate marshal operations against or null to disable validation
713      * @throws UnsupportedOperationException could be thrown if this method is
714      * invoked on an Marshaller created from a JAXBContext referencing
715      * JAXB 1.0 mapped classes
716      * @since JAXB2.0
717      */
718     public void setSchema( Schema JavaDoc schema );
719
720     /**
721      * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
722      * being used to perform marshal-time validation. If there is no
723      * Schema set on the marshaller, then this method will return null
724      * indicating that marshal-time validation will not be performed.
725      *
726      * @return the Schema object being used to perform marshal-time
727      * validation or null if not present.
728      * @throws UnsupportedOperationException could be thrown if this method is
729      * invoked on an Marshaller created from a JAXBContext referencing
730      * JAXB 1.0 mapped classes
731      * @since JAXB2.0
732      */
733     public Schema JavaDoc getSchema();
734
735     /**
736      * <p/>
737      * Register an instance of an implementation of this class with a {@link Marshaller} to externally listen
738      * for marshal events.
739      * <p/>
740      * <p/>
741      * This class enables pre and post processing of each marshalled object.
742      * The event callbacks are called when marshalling from an instance that maps to an xml element or
743      * complex type definition. The event callbacks are not called when marshalling from an instance of a
744      * Java datatype that represents a simple type definition.
745      * <p/>
746      * <p/>
747      * External listener is one of two different mechanisms for defining marshal event callbacks.
748      * See <a HREF="Marshaller.html#marshalEventCallback">Marshal Event Callbacks</a> for an overview.
749      *
750      * @see Marshaller#setListener(Listener)
751      * @see Marshaller#getListener()
752      * @since JAXB2.0
753      */
754     public static abstract class Listener {
755         /**
756          * <p/>
757          * Callback method invoked before marshalling from <tt>source</tt> to XML.
758          * <p/>
759          * <p/>
760          * This method is invoked just before marshalling process starts to marshal <tt>source</tt>.
761          * Note that if the class of <tt>source</tt> defines its own <tt>beforeMarshal</tt> method,
762          * the class specific callback method is invoked just before this method is invoked.
763          *
764          * @param source instance of JAXB mapped class prior to marshalling from it.
765          */
766         public void beforeMarshal(Object JavaDoc source) {
767         }
768
769         /**
770          * <p/>
771          * Callback method invoked after marshalling <tt>source</tt> to XML.
772          * <p/>
773          * <p/>
774          * This method is invoked after <tt>source</tt> and all its descendants have been marshalled.
775          * Note that if the class of <tt>source</tt> defines its own <tt>afterMarshal</tt> method,
776          * the class specific callback method is invoked just before this method is invoked.
777          *
778          * @param source instance of JAXB mapped class after marshalling it.
779          */
780         public void afterMarshal(Object JavaDoc source) {
781         }
782     }
783
784     /**
785      * <p>
786      * Register marshal event callback {@link Listener} with this {@link Marshaller}.
787      *
788      * <p>
789      * There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener.
790      * One can unregister current Listener by setting listener to <tt>null</tt>.
791      *
792      * @param listener an instance of a class that implements {@link Listener}
793      * @since JAXB2.0
794      */
795     public void setListener(Listener listener);
796
797     /**
798      * <p>Return {@link Listener} registered with this {@link Marshaller}.
799      *
800      * @return registered {@link Listener} or <code>null</code> if no Listener is registered with this Marshaller.
801      * @since JAXB2.0
802      */
803     public Listener getListener();
804 }
805
806
807
808
809
Popular Tags