001: /*
002: * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.bind;
007:
008: import javax.xml.bind.annotation.XmlRootElement;
009: import javax.xml.bind.annotation.adapters.XmlAdapter;
010: import javax.xml.bind.attachment.AttachmentMarshaller;
011: import javax.xml.validation.Schema;
012: import java.io.File;
013:
014: /**
015: * <p>
016: * The <tt>Marshaller</tt> class is responsible for governing the process
017: * of serializing Java content trees back into XML data. It provides the basic
018: * marshalling methods:
019: *
020: * <p>
021: * <i>Assume the following setup code for all following code fragments:</i>
022: * <blockquote>
023: * <pre>
024: * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
025: * Unmarshaller u = jc.createUnmarshaller();
026: * Object element = u.unmarshal( new File( "foo.xml" ) );
027: * Marshaller m = jc.createMarshaller();
028: * </pre>
029: * </blockquote>
030: *
031: * <p>
032: * Marshalling to a File:
033: * <blockquote>
034: * <pre>
035: * OutputStream os = new FileOutputStream( "nosferatu.xml" );
036: * m.marshal( element, os );
037: * </pre>
038: * </blockquote>
039: *
040: * <p>
041: * Marshalling to a SAX ContentHandler:
042: * <blockquote>
043: * <pre>
044: * // assume MyContentHandler instanceof ContentHandler
045: * m.marshal( element, new MyContentHandler() );
046: * </pre>
047: * </blockquote>
048: *
049: * <p>
050: * Marshalling to a DOM Node:
051: * <blockquote>
052: * <pre>
053: * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
054: * dbf.setNamespaceAware(true);
055: * DocumentBuilder db = dbf.newDocumentBuilder();
056: * Document doc = db.newDocument();
057: *
058: * m.marshal( element, doc );
059: * </pre>
060: * </blockquote>
061: *
062: * <p>
063: * Marshalling to a java.io.OutputStream:
064: * <blockquote>
065: * <pre>
066: * m.marshal( element, System.out );
067: * </pre>
068: * </blockquote>
069: *
070: * <p>
071: * Marshalling to a java.io.Writer:
072: * <blockquote>
073: * <pre>
074: * m.marshal( element, new PrintWriter( System.out ) );
075: * </pre>
076: * </blockquote>
077: *
078: * <p>
079: * Marshalling to a javax.xml.transform.SAXResult:
080: * <blockquote>
081: * <pre>
082: * // assume MyContentHandler instanceof ContentHandler
083: * SAXResult result = new SAXResult( new MyContentHandler() );
084: *
085: * m.marshal( element, result );
086: * </pre>
087: * </blockquote>
088: *
089: * <p>
090: * Marshalling to a javax.xml.transform.DOMResult:
091: * <blockquote>
092: * <pre>
093: * DOMResult result = new DOMResult();
094: *
095: * m.marshal( element, result );
096: * </pre>
097: * </blockquote>
098: *
099: * <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: * @{@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: 1.21 $ $Date: 2006/08/28 17:56:41 $
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 JAXB_ENCODING = "jaxb.encoding";
306:
307: /**
308: * The name of the property used to specify whether or not the marshalled
309: * XML data is formatted with linefeeds and indentation.
310: */
311: public static final String JAXB_FORMATTED_OUTPUT = "jaxb.formatted.output";
312:
313: /**
314: * The name of the property used to specify the xsi:schemaLocation
315: * attribute value to place in the marshalled XML output.
316: */
317: public static final String JAXB_SCHEMA_LOCATION = "jaxb.schemaLocation";
318:
319: /**
320: * The name of the property used to specify the
321: * xsi:noNamespaceSchemaLocation attribute value to place in the marshalled
322: * XML output.
323: */
324: public static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION = "jaxb.noNamespaceSchemaLocation";
325:
326: /**
327: * The name of the property used to specify whether or not the marshaller
328: * will generate document level events (ie calling startDocument or endDocument).
329: */
330: public static final String JAXB_FRAGMENT = "jaxb.fragment";
331:
332: /**
333: * Marshal the content tree rooted at <tt>jaxbElement</tt> into the specified
334: * <tt>javax.xml.transform.Result</tt>.
335: *
336: * <p>
337: * All JAXB Providers must at least support
338: * {@link javax.xml.transform.dom.DOMResult},
339: * {@link javax.xml.transform.sax.SAXResult}, and
340: * {@link javax.xml.transform.stream.StreamResult}. It can
341: * support other derived classes of <tt>Result</tt> as well.
342: *
343: * @param jaxbElement
344: * The root of content tree to be marshalled.
345: * @param result
346: * XML will be sent to this Result
347: *
348: * @throws JAXBException
349: * If any unexpected problem occurs during the marshalling.
350: * @throws MarshalException
351: * If the {@link ValidationEventHandler ValidationEventHandler}
352: * returns false from its <tt>handleEvent</tt> method or the
353: * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
354: * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
355: * Marshalling a JAXB element</a>.
356: * @throws IllegalArgumentException
357: * If any of the method parameters are null
358: */
359: public void marshal(Object jaxbElement,
360: javax.xml.transform.Result result) throws JAXBException;
361:
362: /**
363: * Marshal the content tree rooted at <tt>jaxbElement</tt> into an output stream.
364: *
365: * @param jaxbElement
366: * The root of content tree to be marshalled.
367: * @param os
368: * XML will be added to this stream.
369: *
370: * @throws JAXBException
371: * If any unexpected problem occurs during the marshalling.
372: * @throws MarshalException
373: * If the {@link ValidationEventHandler ValidationEventHandler}
374: * returns false from its <tt>handleEvent</tt> method or the
375: * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
376: * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
377: * Marshalling a JAXB element</a>.
378: * @throws IllegalArgumentException
379: * If any of the method parameters are null
380: */
381: public void marshal(Object jaxbElement, java.io.OutputStream os)
382: throws JAXBException;
383:
384: /**
385: * Marshal the content tree rooted at <tt>jaxbElement</tt> into a file.
386: *
387: * @param jaxbElement
388: * The root of content tree to be marshalled.
389: * @param output
390: * File to be written. If this file already exists, it will be overwritten.
391: *
392: * @throws JAXBException
393: * If any unexpected problem occurs during the marshalling.
394: * @throws MarshalException
395: * If the {@link ValidationEventHandler ValidationEventHandler}
396: * returns false from its <tt>handleEvent</tt> method or the
397: * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
398: * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
399: * Marshalling a JAXB element</a>.
400: * @throws IllegalArgumentException
401: * If any of the method parameters are null
402: * @since JAXB2.1
403: */
404: public void marshal(Object jaxbElement, File output)
405: throws JAXBException;
406:
407: /**
408: * Marshal the content tree rooted at <tt>jaxbElement</tt> into a Writer.
409: *
410: * @param jaxbElement
411: * The root of content tree to be marshalled.
412: * @param writer
413: * XML will be sent to this writer.
414: *
415: * @throws JAXBException
416: * If any unexpected problem occurs during the marshalling.
417: * @throws MarshalException
418: * If the {@link ValidationEventHandler ValidationEventHandler}
419: * returns false from its <tt>handleEvent</tt> method or the
420: * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
421: * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
422: * Marshalling a JAXB element</a>.
423: * @throws IllegalArgumentException
424: * If any of the method parameters are null
425: */
426: public void marshal(Object jaxbElement, java.io.Writer writer)
427: throws JAXBException;
428:
429: /**
430: * Marshal the content tree rooted at <tt>jaxbElement</tt> into SAX2 events.
431: *
432: * @param jaxbElement
433: * The root of content tree to be marshalled.
434: * @param handler
435: * XML will be sent to this handler as SAX2 events.
436: *
437: * @throws JAXBException
438: * If any unexpected problem occurs during the marshalling.
439: * @throws MarshalException
440: * If the {@link ValidationEventHandler ValidationEventHandler}
441: * returns false from its <tt>handleEvent</tt> method or the
442: * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
443: * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
444: * Marshalling a JAXB element</a>.
445: * @throws IllegalArgumentException
446: * If any of the method parameters are null
447: */
448: public void marshal(Object jaxbElement,
449: org.xml.sax.ContentHandler handler) throws JAXBException;
450:
451: /**
452: * Marshal the content tree rooted at <tt>jaxbElement</tt> into a DOM tree.
453: *
454: * @param jaxbElement
455: * The content tree to be marshalled.
456: * @param node
457: * DOM nodes will be added as children of this node.
458: * This parameter must be a Node that accepts children
459: * ({@link org.w3c.dom.Document},
460: * {@link org.w3c.dom.DocumentFragment}, or
461: * {@link org.w3c.dom.Element})
462: *
463: * @throws JAXBException
464: * If any unexpected problem occurs during the marshalling.
465: * @throws MarshalException
466: * If the {@link ValidationEventHandler ValidationEventHandler}
467: * returns false from its <tt>handleEvent</tt> method or the
468: * <tt>Marshaller</tt> is unable to marshal <tt>jaxbElement</tt> (or any
469: * object reachable from <tt>jaxbElement</tt>). See <a href="#elementMarshalling">
470: * Marshalling a JAXB element</a>.
471: * @throws IllegalArgumentException
472: * If any of the method parameters are null
473: */
474: public void marshal(Object jaxbElement, org.w3c.dom.Node node)
475: throws JAXBException;
476:
477: /**
478: * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
479: * {@link javax.xml.stream.XMLStreamWriter}.
480: *
481: * @param jaxbElement
482: * The content tree to be marshalled.
483: * @param writer
484: * XML will be sent to this writer.
485: *
486: * @throws JAXBException
487: * If any unexpected problem occurs during the marshalling.
488: * @throws MarshalException
489: * If the {@link ValidationEventHandler ValidationEventHandler}
490: * returns false from its <tt>handleEvent</tt> method or the
491: * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
492: * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
493: * Marshalling a JAXB element</a>.
494: * @throws IllegalArgumentException
495: * If any of the method parameters are null
496: * @since JAXB 2.0
497: */
498: public void marshal(Object jaxbElement,
499: javax.xml.stream.XMLStreamWriter writer)
500: throws JAXBException;
501:
502: /**
503: * Marshal the content tree rooted at <tt>jaxbElement</tt> into a
504: * {@link javax.xml.stream.XMLEventWriter}.
505: *
506: * @param jaxbElement
507: * The content tree rooted at jaxbElement to be marshalled.
508: * @param writer
509: * XML will be sent to this writer.
510: *
511: * @throws JAXBException
512: * If any unexpected problem occurs during the marshalling.
513: * @throws MarshalException
514: * If the {@link ValidationEventHandler ValidationEventHandler}
515: * returns false from its <tt>handleEvent</tt> method or the
516: * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
517: * object reachable from <tt>obj</tt>). See <a href="#elementMarshalling">
518: * Marshalling a JAXB element</a>.
519: * @throws IllegalArgumentException
520: * If any of the method parameters are null
521: * @since JAXB 2.0
522: */
523: public void marshal(Object jaxbElement,
524: javax.xml.stream.XMLEventWriter writer)
525: throws JAXBException;
526:
527: /**
528: * Get a DOM tree view of the content tree(Optional).
529: *
530: * If the returned DOM tree is updated, these changes are also
531: * visible in the content tree.
532: * Use {@link #marshal(Object, org.w3c.dom.Node)} to force
533: * a deep copy of the content tree to a DOM representation.
534: *
535: * @param contentTree - JAXB Java representation of XML content
536: *
537: * @return the DOM tree view of the contentTree
538: *
539: * @throws UnsupportedOperationException
540: * If the JAXB provider implementation does not support a
541: * DOM view of the content tree
542: *
543: * @throws IllegalArgumentException
544: * If any of the method parameters are null
545: *
546: * @throws JAXBException
547: * If any unexpected problem occurs
548: *
549: */
550: public org.w3c.dom.Node getNode(java.lang.Object contentTree)
551: throws JAXBException;
552:
553: /**
554: * Set the particular property in the underlying implementation of
555: * <tt>Marshaller</tt>. This method can only be used to set one of
556: * the standard JAXB defined properties above or a provider specific
557: * property. Attempting to set an undefined property will result in
558: * a PropertyException being thrown. See <a href="#supportedProps">
559: * Supported Properties</a>.
560: *
561: * @param name the name of the property to be set. This value can either
562: * be specified using one of the constant fields or a user
563: * supplied string.
564: * @param value the value of the property to be set
565: *
566: * @throws PropertyException when there is an error processing the given
567: * property or value
568: * @throws IllegalArgumentException
569: * If the name parameter is null
570: */
571: public void setProperty(String name, Object value)
572: throws PropertyException;
573:
574: /**
575: * Get the particular property in the underlying implementation of
576: * <tt>Marshaller</tt>. This method can only be used to get one of
577: * the standard JAXB defined properties above or a provider specific
578: * property. Attempting to get an undefined property will result in
579: * a PropertyException being thrown. See <a href="#supportedProps">
580: * Supported Properties</a>.
581: *
582: * @param name the name of the property to retrieve
583: * @return the value of the requested property
584: *
585: * @throws PropertyException
586: * when there is an error retrieving the given property or value
587: * property name
588: * @throws IllegalArgumentException
589: * If the name parameter is null
590: */
591: public Object getProperty(String name) throws PropertyException;
592:
593: /**
594: * Allow an application to register a validation event handler.
595: * <p>
596: * The validation event handler will be called by the JAXB Provider if any
597: * validation errors are encountered during calls to any of the marshal
598: * API's. If the client application does not register a validation event
599: * handler before invoking one of the marshal methods, then validation
600: * events will be handled by the default event handler which will terminate
601: * the marshal operation after the first error or fatal error is encountered.
602: * <p>
603: * Calling this method with a null parameter will cause the Marshaller
604: * to revert back to the default default event handler.
605: *
606: * @param handler the validation event handler
607: * @throws JAXBException if an error was encountered while setting the
608: * event handler
609: */
610: public void setEventHandler(ValidationEventHandler handler)
611: throws JAXBException;
612:
613: /**
614: * Return the current event handler or the default event handler if one
615: * hasn't been set.
616: *
617: * @return the current ValidationEventHandler or the default event handler
618: * if it hasn't been set
619: * @throws JAXBException if an error was encountered while getting the
620: * current event handler
621: */
622: public ValidationEventHandler getEventHandler()
623: throws JAXBException;
624:
625: /**
626: * Associates a configured instance of {@link XmlAdapter} with this marshaller.
627: *
628: * <p>
629: * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
630: *
631: * @see #setAdapter(Class,XmlAdapter)
632: * @throws IllegalArgumentException
633: * if the adapter parameter is null.
634: * @throws UnsupportedOperationException
635: * if invoked agains a JAXB 1.0 implementation.
636: * @since JAXB 2.0
637: */
638: public void setAdapter(XmlAdapter adapter);
639:
640: /**
641: * Associates a configured instance of {@link XmlAdapter} with this marshaller.
642: *
643: * <p>
644: * Every marshaller internally maintains a
645: * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
646: * which it uses for marshalling classes whose fields/methods are annotated
647: * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
648: *
649: * <p>
650: * This method allows applications to use a configured instance of {@link XmlAdapter}.
651: * When an instance of an adapter is not given, a marshaller will create
652: * one by invoking its default constructor.
653: *
654: * @param type
655: * The type of the adapter. The specified instance will be used when
656: * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
657: * refers to this type.
658: * @param adapter
659: * The instance of the adapter to be used. If null, it will un-register
660: * the current adapter set for this type.
661: * @throws IllegalArgumentException
662: * if the type parameter is null.
663: * @throws UnsupportedOperationException
664: * if invoked agains a JAXB 1.0 implementation.
665: * @since JAXB 2.0
666: */
667: public <A extends XmlAdapter> void setAdapter(Class<A> type,
668: A adapter);
669:
670: /**
671: * Gets the adapter associated with the specified type.
672: *
673: * This is the reverse operation of the {@link #setAdapter} method.
674: *
675: * @throws IllegalArgumentException
676: * if the type parameter is null.
677: * @throws UnsupportedOperationException
678: * if invoked agains a JAXB 1.0 implementation.
679: * @since JAXB 2.0
680: */
681: public <A extends XmlAdapter> A getAdapter(Class<A> type);
682:
683: /**
684: * <p>Associate a context that enables binary data within an XML document
685: * to be transmitted as XML-binary optimized attachment.
686: * The attachment is referenced from the XML document content model
687: * by content-id URIs(cid) references stored within the xml document.
688: *
689: * @throws IllegalStateException if attempt to concurrently call this
690: * method during a marshal operation.
691: */
692: void setAttachmentMarshaller(AttachmentMarshaller am);
693:
694: AttachmentMarshaller getAttachmentMarshaller();
695:
696: /**
697: * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
698: * object that should be used to validate subsequent marshal operations
699: * against. Passing null into this method will disable validation.
700: *
701: * <p>
702: * This method allows the caller to validate the marshalled XML as it's marshalled.
703: *
704: * <p>
705: * Initially this property is set to <tt>null</tt>.
706: *
707: * @param schema Schema object to validate marshal operations against or null to disable validation
708: * @throws UnsupportedOperationException could be thrown if this method is
709: * invoked on an Marshaller created from a JAXBContext referencing
710: * JAXB 1.0 mapped classes
711: * @since JAXB2.0
712: */
713: public void setSchema(Schema schema);
714:
715: /**
716: * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
717: * being used to perform marshal-time validation. If there is no
718: * Schema set on the marshaller, then this method will return null
719: * indicating that marshal-time validation will not be performed.
720: *
721: * @return the Schema object being used to perform marshal-time
722: * validation or null if not present.
723: * @throws UnsupportedOperationException could be thrown if this method is
724: * invoked on an Marshaller created from a JAXBContext referencing
725: * JAXB 1.0 mapped classes
726: * @since JAXB2.0
727: */
728: public Schema getSchema();
729:
730: /**
731: * <p/>
732: * Register an instance of an implementation of this class with a {@link Marshaller} to externally listen
733: * for marshal events.
734: * <p/>
735: * <p/>
736: * This class enables pre and post processing of each marshalled object.
737: * The event callbacks are called when marshalling from an instance that maps to an xml element or
738: * complex type definition. The event callbacks are not called when marshalling from an instance of a
739: * Java datatype that represents a simple type definition.
740: * <p/>
741: * <p/>
742: * External listener is one of two different mechanisms for defining marshal event callbacks.
743: * See <a href="Marshaller.html#marshalEventCallback">Marshal Event Callbacks</a> for an overview.
744: *
745: * @see Marshaller#setListener(Listener)
746: * @see Marshaller#getListener()
747: * @since JAXB2.0
748: */
749: public static abstract class Listener {
750: /**
751: * <p/>
752: * Callback method invoked before marshalling from <tt>source</tt> to XML.
753: * <p/>
754: * <p/>
755: * This method is invoked just before marshalling process starts to marshal <tt>source</tt>.
756: * Note that if the class of <tt>source</tt> defines its own <tt>beforeMarshal</tt> method,
757: * the class specific callback method is invoked just before this method is invoked.
758: *
759: * @param source instance of JAXB mapped class prior to marshalling from it.
760: */
761: public void beforeMarshal(Object source) {
762: }
763:
764: /**
765: * <p/>
766: * Callback method invoked after marshalling <tt>source</tt> to XML.
767: * <p/>
768: * <p/>
769: * This method is invoked after <tt>source</tt> and all its descendants have been marshalled.
770: * Note that if the class of <tt>source</tt> defines its own <tt>afterMarshal</tt> method,
771: * the class specific callback method is invoked just before this method is invoked.
772: *
773: * @param source instance of JAXB mapped class after marshalling it.
774: */
775: public void afterMarshal(Object source) {
776: }
777: }
778:
779: /**
780: * <p>
781: * Register marshal event callback {@link Listener} with this {@link Marshaller}.
782: *
783: * <p>
784: * There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener.
785: * One can unregister current Listener by setting listener to <tt>null</tt>.
786: *
787: * @param listener an instance of a class that implements {@link Listener}
788: * @since JAXB2.0
789: */
790: public void setListener(Listener listener);
791:
792: /**
793: * <p>Return {@link Listener} registered with this {@link Marshaller}.
794: *
795: * @return registered {@link Listener} or <code>null</code> if no Listener is registered with this Marshaller.
796: * @since JAXB2.0
797: */
798: public Listener getListener();
799: }
|