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