ohair@286: /* alanb@368: * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.bind; ohair@286: ohair@286: import javax.xml.bind.annotation.XmlRootElement; ohair@286: import javax.xml.bind.annotation.adapters.XmlAdapter; ohair@286: import javax.xml.bind.attachment.AttachmentMarshaller; ohair@286: import javax.xml.validation.Schema; ohair@286: import java.io.File; ohair@286: ohair@286: /** ohair@286: *

ohair@286: * The Marshaller class is responsible for governing the process ohair@286: * of serializing Java content trees back into XML data. It provides the basic ohair@286: * marshalling methods: ohair@286: * ohair@286: *

ohair@286: * Assume the following setup code for all following code fragments: ohair@286: *

ohair@286: * 
ohair@286:  *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
ohair@286:  *       Unmarshaller u = jc.createUnmarshaller();
ohair@286:  *       Object element = u.unmarshal( new File( "foo.xml" ) );
ohair@286:  *       Marshaller m = jc.createMarshaller();
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a File: ohair@286: *

ohair@286: * 
ohair@286:  *       OutputStream os = new FileOutputStream( "nosferatu.xml" );
ohair@286:  *       m.marshal( element, os );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a SAX ContentHandler: ohair@286: *

ohair@286: * 
ohair@286:  *       // assume MyContentHandler instanceof ContentHandler
ohair@286:  *       m.marshal( element, new MyContentHandler() );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a DOM Node: ohair@286: *

ohair@286: * 
ohair@286:  *       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
ohair@286:  *       dbf.setNamespaceAware(true);
ohair@286:  *       DocumentBuilder db = dbf.newDocumentBuilder();
ohair@286:  *       Document doc = db.newDocument();
ohair@286:  *
ohair@286:  *       m.marshal( element, doc );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a java.io.OutputStream: ohair@286: *

ohair@286: * 
ohair@286:  *       m.marshal( element, System.out );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a java.io.Writer: ohair@286: *

ohair@286: * 
ohair@286:  *       m.marshal( element, new PrintWriter( System.out ) );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a javax.xml.transform.SAXResult: ohair@286: *

ohair@286: * 
ohair@286:  *       // assume MyContentHandler instanceof ContentHandler
ohair@286:  *       SAXResult result = new SAXResult( new MyContentHandler() );
ohair@286:  *
ohair@286:  *       m.marshal( element, result );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a javax.xml.transform.DOMResult: ohair@286: *

ohair@286: * 
ohair@286:  *       DOMResult result = new DOMResult();
ohair@286:  *
ohair@286:  *       m.marshal( element, result );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a javax.xml.transform.StreamResult: ohair@286: *

ohair@286: * 
ohair@286:  *       StreamResult result = new StreamResult( System.out );
ohair@286:  *
ohair@286:  *       m.marshal( element, result );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a javax.xml.stream.XMLStreamWriter: ohair@286: *

ohair@286: * 
ohair@286:  *       XMLStreamWriter xmlStreamWriter =
ohair@286:  *           XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
ohair@286:  *
ohair@286:  *       m.marshal( element, xmlStreamWriter );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Marshalling to a javax.xml.stream.XMLEventWriter: ohair@286: *

ohair@286: * 
ohair@286:  *       XMLEventWriter xmlEventWriter =
ohair@286:  *           XMLOutputFactory.newInstance().createXMLEventWriter( ... );
ohair@286:  *
ohair@286:  *       m.marshal( element, xmlEventWriter );
ohair@286:  *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * ohair@286: * Marshalling content tree rooted by a JAXB element
ohair@286: *

ohair@286: * The first parameter of the overloaded ohair@286: * Marshaller.marshal(java.lang.Object, ...) methods must be a ohair@286: * JAXB element as computed by ohair@286: * {@link JAXBIntrospector#isElement(java.lang.Object)}; ohair@286: * otherwise, a Marshaller.marshal method must throw a ohair@286: * {@link MarshalException}. There exist two mechanisms ohair@286: * to enable marshalling an instance that is not a JAXB element. ohair@286: * One method is to wrap the instance as a value of a {@link JAXBElement}, ohair@286: * and pass the wrapper element as the first parameter to ohair@286: * a Marshaller.marshal method. For java to schema binding, it ohair@286: * is also possible to simply annotate the instance's class with ohair@286: * @{@link XmlRootElement}. ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Encoding
ohair@286: *

ohair@286: * By default, the Marshaller will use UTF-8 encoding when generating XML data ohair@286: * to a java.io.OutputStream, or a java.io.Writer. Use the ohair@286: * {@link #setProperty(String,Object) setProperty} API to change the output ohair@286: * encoding used during these marshal operations. Client applications are ohair@286: * expected to supply a valid character encoding name as defined in the ohair@286: * W3C XML 1.0 mkos@408: * Recommendation and supported by your Java Platform. ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * Validation and Well-Formedness
ohair@286: *

ohair@286: *

ohair@286: * Client applications are not required to validate the Java content tree prior ohair@286: * to calling any of the marshal API's. Furthermore, there is no requirement ohair@286: * that the Java content tree be valid with respect to its original schema in ohair@286: * order to marshal it back into XML data. Different JAXB Providers will ohair@286: * support marshalling invalid Java content trees at varying levels, however ohair@286: * all JAXB Providers must be able to marshal a valid content tree back to ohair@286: * XML data. A JAXB Provider must throw a MarshalException when it ohair@286: * is unable to complete the marshal operation due to invalid content. Some ohair@286: * JAXB Providers will fully allow marshalling invalid content, others will fail ohair@286: * on the first validation error. ohair@286: *

ohair@286: * Even when schema validation is not explictly enabled for the marshal operation, ohair@286: * it is possible that certain types of validation events will be detected ohair@286: * during the operation. Validation events will be reported to the registered ohair@286: * event handler. If the client application has not registered an event handler ohair@286: * prior to invoking one of the marshal API's, then events will be delivered to ohair@286: * a default event handler which will terminate the marshal operation after ohair@286: * encountering the first error or fatal error. Note that for JAXB 2.0 and ohair@286: * later versions, {@link javax.xml.bind.helpers.DefaultValidationEventHandler} is ohair@286: * no longer used. ohair@286: * ohair@286: *

ohair@286: * ohair@286: *

ohair@286: * ohair@286: * Supported Properties
ohair@286: *

ohair@286: *

ohair@286: * All JAXB Providers are required to support the following set of properties. ohair@286: * Some providers may support additional properties. ohair@286: *

ohair@286: *
jaxb.encoding - value must be a java.lang.String
ohair@286: *
The output encoding to use when marshalling the XML data. The ohair@286: * Marshaller will use "UTF-8" by default if this property is not ohair@286: * specified.
ohair@286: *
jaxb.formatted.output - value must be a java.lang.Boolean
ohair@286: *
This property controls whether or not the Marshaller will format ohair@286: * the resulting XML data with line breaks and indentation. A ohair@286: * true value for this property indicates human readable indented ohair@286: * xml data, while a false value indicates unformatted xml data. ohair@286: * The Marshaller will default to false (unformatted) if this ohair@286: * property is not specified.
ohair@286: *
jaxb.schemaLocation - value must be a java.lang.String
ohair@286: *
This property allows the client application to specify an ohair@286: * xsi:schemaLocation attribute in the generated XML data. The format of ohair@286: * the schemaLocation attribute value is discussed in an easy to ohair@286: * understand, non-normative form in ohair@286: * Section 5.6 ohair@286: * of the W3C XML Schema Part 0: Primer and specified in ohair@286: * ohair@286: * Section 2.6 of the W3C XML Schema Part 1: Structures.
ohair@286: *
jaxb.noNamespaceSchemaLocation - value must be a java.lang.String
ohair@286: *
This property allows the client application to specify an ohair@286: * xsi:noNamespaceSchemaLocation attribute in the generated XML ohair@286: * data. The format of the schemaLocation attribute value is discussed in ohair@286: * an easy to understand, non-normative form in ohair@286: * Section 5.6 ohair@286: * of the W3C XML Schema Part 0: Primer and specified in ohair@286: * ohair@286: * Section 2.6 of the W3C XML Schema Part 1: Structures.
ohair@286: *
jaxb.fragment - value must be a java.lang.Boolean
ohair@286: *
This property determines whether or not document level events will be ohair@286: * generated by the Marshaller. If the property is not specified, the ohair@286: * default is false. This property has different implications depending ohair@286: * on which marshal api you are using - when this property is set to true:
ohair@286: *
    ohair@286: *
  • {@link #marshal(Object,org.xml.sax.ContentHandler) marshal(Object,ContentHandler)} - the Marshaller won't ohair@286: * invoke {@link org.xml.sax.ContentHandler#startDocument()} and ohair@286: * {@link org.xml.sax.ContentHandler#endDocument()}.
    • ohair@286: *
  • {@link #marshal(Object,org.w3c.dom.Node) marshal(Object,Node)} - the property has no effect on this ohair@286: * API.
    • ohair@286: *
  • {@link #marshal(Object,java.io.OutputStream) marshal(Object,OutputStream)} - the Marshaller won't ohair@286: * generate an xml declaration.
    • ohair@286: *
  • {@link #marshal(Object,java.io.Writer) marshal(Object,Writer)} - the Marshaller won't ohair@286: * generate an xml declaration.
    • ohair@286: *
  • {@link #marshal(Object,javax.xml.transform.Result) marshal(Object,Result)} - depends on the kind of ohair@286: * Result object, see semantics for Node, ContentHandler, and Stream APIs
    • ohair@286: *
  • {@link #marshal(Object,javax.xml.stream.XMLEventWriter) marshal(Object,XMLEventWriter)} - the ohair@286: * Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and ohair@286: * {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.
    • ohair@286: *
  • {@link #marshal(Object,javax.xml.stream.XMLStreamWriter) marshal(Object,XMLStreamWriter)} - the ohair@286: * Marshaller will not generate {@link javax.xml.stream.events.XMLEvent#START_DOCUMENT} and ohair@286: * {@link javax.xml.stream.events.XMLEvent#END_DOCUMENT} events.
    • ohair@286: *
ohair@286: *
ohair@286: *
ohair@286: *
ohair@286: * ohair@286: *

ohair@286: * ohair@286: * Marshal Event Callbacks
ohair@286: *

ohair@286: * "The {@link Marshaller} provides two styles of callback mechanisms ohair@286: * that allow application specific processing during key points in the ohair@286: * unmarshalling process. In 'class defined' event callbacks, application ohair@286: * specific code placed in JAXB mapped classes is triggered during ohair@286: * marshalling. 'External listeners' allow for centralized processing ohair@286: * of marshal events in one callback method rather than by type event callbacks. ohair@286: * ohair@286: *

ohair@286: * Class defined event callback methods allow any JAXB mapped class to specify ohair@286: * its own specific callback methods by defining methods with the following method signatures: ohair@286: *

ohair@286: * 
ohair@286:  *   // Invoked by Marshaller after it has created an instance of this object.
ohair@286:  *   boolean beforeMarshal(Marshaller);
ohair@286:  *
ohair@286:  *   // Invoked by Marshaller after it has marshalled all properties of this object.
mkos@408:  *   void afterMarshal(Marshaller);
ohair@286:  *
ohair@286: *
ohair@286: * The class defined event callback methods should be used when the callback method requires ohair@286: * access to non-public methods and/or fields of the class. ohair@286: *

ohair@286: * The external listener callback mechanism enables the registration of a {@link Listener} ohair@286: * instance with a {@link Marshaller#setListener(Listener)}. The external listener receives all callback events, ohair@286: * allowing for more centralized processing than per class defined callback methods. ohair@286: *

ohair@286: * The 'class defined' and external listener event callback methods are independent of each other, ohair@286: * both can be called for one event. The invocation ordering when both listener callback methods exist is ohair@286: * defined in {@link Listener#beforeMarshal(Object)} and {@link Listener#afterMarshal(Object)}. ohair@286: *

ohair@286: * An event callback method throwing an exception terminates the current marshal process. ohair@286: *

ohair@286: * ohair@286: * @author ohair@286: * @see JAXBContext ohair@286: * @see Validator ohair@286: * @see Unmarshaller ohair@286: * @since JAXB1.0 ohair@286: */ ohair@286: public interface Marshaller { ohair@286: ohair@286: /** ohair@286: * The name of the property used to specify the output encoding in ohair@286: * the marshalled XML data. ohair@286: */ ohair@286: public static final String JAXB_ENCODING = ohair@286: "jaxb.encoding"; ohair@286: ohair@286: /** ohair@286: * The name of the property used to specify whether or not the marshalled ohair@286: * XML data is formatted with linefeeds and indentation. ohair@286: */ ohair@286: public static final String JAXB_FORMATTED_OUTPUT = ohair@286: "jaxb.formatted.output"; ohair@286: ohair@286: /** ohair@286: * The name of the property used to specify the xsi:schemaLocation ohair@286: * attribute value to place in the marshalled XML output. ohair@286: */ ohair@286: public static final String JAXB_SCHEMA_LOCATION = ohair@286: "jaxb.schemaLocation"; ohair@286: ohair@286: /** ohair@286: * The name of the property used to specify the ohair@286: * xsi:noNamespaceSchemaLocation attribute value to place in the marshalled ohair@286: * XML output. ohair@286: */ ohair@286: public static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION = ohair@286: "jaxb.noNamespaceSchemaLocation"; ohair@286: ohair@286: /** ohair@286: * The name of the property used to specify whether or not the marshaller ohair@286: * will generate document level events (ie calling startDocument or endDocument). ohair@286: */ ohair@286: public static final String JAXB_FRAGMENT = ohair@286: "jaxb.fragment"; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into the specified ohair@286: * javax.xml.transform.Result. ohair@286: * ohair@286: *

ohair@286: * All JAXB Providers must at least support ohair@286: * {@link javax.xml.transform.dom.DOMResult}, ohair@286: * {@link javax.xml.transform.sax.SAXResult}, and ohair@286: * {@link javax.xml.transform.stream.StreamResult}. It can ohair@286: * support other derived classes of Result as well. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The root of content tree to be marshalled. ohair@286: * @param result ohair@286: * XML will be sent to this Result ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal obj (or any ohair@286: * object reachable from obj). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: */ ohair@286: public void marshal( Object jaxbElement, javax.xml.transform.Result result ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into an output stream. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The root of content tree to be marshalled. ohair@286: * @param os ohair@286: * XML will be added to this stream. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal obj (or any ohair@286: * object reachable from obj). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: */ ohair@286: public void marshal( Object jaxbElement, java.io.OutputStream os ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into a file. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The root of content tree to be marshalled. ohair@286: * @param output ohair@286: * File to be written. If this file already exists, it will be overwritten. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal obj (or any ohair@286: * object reachable from obj). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: * @since JAXB2.1 ohair@286: */ ohair@286: public void marshal( Object jaxbElement, File output ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into a Writer. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The root of content tree to be marshalled. ohair@286: * @param writer ohair@286: * XML will be sent to this writer. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal obj (or any ohair@286: * object reachable from obj). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: */ ohair@286: public void marshal( Object jaxbElement, java.io.Writer writer ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into SAX2 events. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The root of content tree to be marshalled. ohair@286: * @param handler ohair@286: * XML will be sent to this handler as SAX2 events. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal obj (or any ohair@286: * object reachable from obj). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: */ ohair@286: public void marshal( Object jaxbElement, org.xml.sax.ContentHandler handler ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into a DOM tree. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The content tree to be marshalled. ohair@286: * @param node ohair@286: * DOM nodes will be added as children of this node. ohair@286: * This parameter must be a Node that accepts children ohair@286: * ({@link org.w3c.dom.Document}, ohair@286: * {@link org.w3c.dom.DocumentFragment}, or ohair@286: * {@link org.w3c.dom.Element}) ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal jaxbElement (or any ohair@286: * object reachable from jaxbElement). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: */ ohair@286: public void marshal( Object jaxbElement, org.w3c.dom.Node node ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into a ohair@286: * {@link javax.xml.stream.XMLStreamWriter}. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The content tree to be marshalled. ohair@286: * @param writer ohair@286: * XML will be sent to this writer. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal obj (or any ohair@286: * object reachable from obj). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: * @since JAXB 2.0 ohair@286: */ ohair@286: public void marshal( Object jaxbElement, javax.xml.stream.XMLStreamWriter writer ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Marshal the content tree rooted at jaxbElement into a ohair@286: * {@link javax.xml.stream.XMLEventWriter}. ohair@286: * ohair@286: * @param jaxbElement ohair@286: * The content tree rooted at jaxbElement to be marshalled. ohair@286: * @param writer ohair@286: * XML will be sent to this writer. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs during the marshalling. ohair@286: * @throws MarshalException ohair@286: * If the {@link ValidationEventHandler ValidationEventHandler} ohair@286: * returns false from its handleEvent method or the ohair@286: * Marshaller is unable to marshal obj (or any ohair@286: * object reachable from obj). See ohair@286: * Marshalling a JAXB element. ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: * @since JAXB 2.0 ohair@286: */ ohair@286: public void marshal( Object jaxbElement, javax.xml.stream.XMLEventWriter writer ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Get a DOM tree view of the content tree(Optional). ohair@286: * ohair@286: * If the returned DOM tree is updated, these changes are also ohair@286: * visible in the content tree. ohair@286: * Use {@link #marshal(Object, org.w3c.dom.Node)} to force ohair@286: * a deep copy of the content tree to a DOM representation. ohair@286: * ohair@286: * @param contentTree - JAXB Java representation of XML content ohair@286: * ohair@286: * @return the DOM tree view of the contentTree ohair@286: * ohair@286: * @throws UnsupportedOperationException ohair@286: * If the JAXB provider implementation does not support a ohair@286: * DOM view of the content tree ohair@286: * ohair@286: * @throws IllegalArgumentException ohair@286: * If any of the method parameters are null ohair@286: * ohair@286: * @throws JAXBException ohair@286: * If any unexpected problem occurs ohair@286: * ohair@286: */ ohair@286: public org.w3c.dom.Node getNode( java.lang.Object contentTree ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Set the particular property in the underlying implementation of ohair@286: * Marshaller. This method can only be used to set one of ohair@286: * the standard JAXB defined properties above or a provider specific ohair@286: * property. Attempting to set an undefined property will result in ohair@286: * a PropertyException being thrown. See ohair@286: * Supported Properties. ohair@286: * ohair@286: * @param name the name of the property to be set. This value can either ohair@286: * be specified using one of the constant fields or a user ohair@286: * supplied string. ohair@286: * @param value the value of the property to be set ohair@286: * ohair@286: * @throws PropertyException when there is an error processing the given ohair@286: * property or value ohair@286: * @throws IllegalArgumentException ohair@286: * If the name parameter is null ohair@286: */ ohair@286: public void setProperty( String name, Object value ) ohair@286: throws PropertyException; ohair@286: ohair@286: /** ohair@286: * Get the particular property in the underlying implementation of ohair@286: * Marshaller. This method can only be used to get one of ohair@286: * the standard JAXB defined properties above or a provider specific ohair@286: * property. Attempting to get an undefined property will result in ohair@286: * a PropertyException being thrown. See ohair@286: * Supported Properties. ohair@286: * ohair@286: * @param name the name of the property to retrieve ohair@286: * @return the value of the requested property ohair@286: * ohair@286: * @throws PropertyException ohair@286: * when there is an error retrieving the given property or value ohair@286: * property name ohair@286: * @throws IllegalArgumentException ohair@286: * If the name parameter is null ohair@286: */ ohair@286: public Object getProperty( String name ) throws PropertyException; ohair@286: ohair@286: /** ohair@286: * Allow an application to register a validation event handler. ohair@286: *

ohair@286: * The validation event handler will be called by the JAXB Provider if any ohair@286: * validation errors are encountered during calls to any of the marshal ohair@286: * API's. If the client application does not register a validation event ohair@286: * handler before invoking one of the marshal methods, then validation ohair@286: * events will be handled by the default event handler which will terminate ohair@286: * the marshal operation after the first error or fatal error is encountered. ohair@286: *

ohair@286: * Calling this method with a null parameter will cause the Marshaller ohair@286: * to revert back to the default default event handler. ohair@286: * ohair@286: * @param handler the validation event handler ohair@286: * @throws JAXBException if an error was encountered while setting the ohair@286: * event handler ohair@286: */ ohair@286: public void setEventHandler( ValidationEventHandler handler ) ohair@286: throws JAXBException; ohair@286: ohair@286: /** ohair@286: * Return the current event handler or the default event handler if one ohair@286: * hasn't been set. ohair@286: * ohair@286: * @return the current ValidationEventHandler or the default event handler ohair@286: * if it hasn't been set ohair@286: * @throws JAXBException if an error was encountered while getting the ohair@286: * current event handler ohair@286: */ ohair@286: public ValidationEventHandler getEventHandler() ohair@286: throws JAXBException; ohair@286: ohair@286: ohair@286: ohair@286: /** ohair@286: * Associates a configured instance of {@link XmlAdapter} with this marshaller. ohair@286: * ohair@286: *

ohair@286: * This is a convenience method that invokes setAdapter(adapter.getClass(),adapter);. ohair@286: * ohair@286: * @see #setAdapter(Class,XmlAdapter) ohair@286: * @throws IllegalArgumentException ohair@286: * if the adapter parameter is null. ohair@286: * @throws UnsupportedOperationException ohair@286: * if invoked agains a JAXB 1.0 implementation. ohair@286: * @since JAXB 2.0 ohair@286: */ ohair@286: public void setAdapter( XmlAdapter adapter ); ohair@286: ohair@286: /** ohair@286: * Associates a configured instance of {@link XmlAdapter} with this marshaller. ohair@286: * ohair@286: *

ohair@286: * Every marshaller internally maintains a ohair@286: * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>, ohair@286: * which it uses for marshalling classes whose fields/methods are annotated ohair@286: * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}. ohair@286: * ohair@286: *

ohair@286: * This method allows applications to use a configured instance of {@link XmlAdapter}. ohair@286: * When an instance of an adapter is not given, a marshaller will create ohair@286: * one by invoking its default constructor. ohair@286: * ohair@286: * @param type ohair@286: * The type of the adapter. The specified instance will be used when ohair@286: * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()} ohair@286: * refers to this type. ohair@286: * @param adapter ohair@286: * The instance of the adapter to be used. If null, it will un-register ohair@286: * the current adapter set for this type. ohair@286: * @throws IllegalArgumentException ohair@286: * if the type parameter is null. ohair@286: * @throws UnsupportedOperationException ohair@286: * if invoked agains a JAXB 1.0 implementation. ohair@286: * @since JAXB 2.0 ohair@286: */ ohair@286: public void setAdapter( Class type, A adapter ); ohair@286: ohair@286: /** ohair@286: * Gets the adapter associated with the specified type. ohair@286: * ohair@286: * This is the reverse operation of the {@link #setAdapter} method. ohair@286: * ohair@286: * @throws IllegalArgumentException ohair@286: * if the type parameter is null. ohair@286: * @throws UnsupportedOperationException ohair@286: * if invoked agains a JAXB 1.0 implementation. ohair@286: * @since JAXB 2.0 ohair@286: */ ohair@286: public A getAdapter( Class type ); ohair@286: ohair@286: ohair@286: /** ohair@286: *

Associate a context that enables binary data within an XML document ohair@286: * to be transmitted as XML-binary optimized attachment. ohair@286: * The attachment is referenced from the XML document content model ohair@286: * by content-id URIs(cid) references stored within the xml document. ohair@286: * ohair@286: * @throws IllegalStateException if attempt to concurrently call this ohair@286: * method during a marshal operation. ohair@286: */ ohair@286: void setAttachmentMarshaller(AttachmentMarshaller am); ohair@286: ohair@286: AttachmentMarshaller getAttachmentMarshaller(); ohair@286: ohair@286: /** ohair@286: * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema} ohair@286: * object that should be used to validate subsequent marshal operations ohair@286: * against. Passing null into this method will disable validation. ohair@286: * ohair@286: *

ohair@286: * This method allows the caller to validate the marshalled XML as it's marshalled. ohair@286: * ohair@286: *

ohair@286: * Initially this property is set to null. ohair@286: * ohair@286: * @param schema Schema object to validate marshal operations against or null to disable validation ohair@286: * @throws UnsupportedOperationException could be thrown if this method is ohair@286: * invoked on an Marshaller created from a JAXBContext referencing ohair@286: * JAXB 1.0 mapped classes ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: public void setSchema( Schema schema ); ohair@286: ohair@286: /** ohair@286: * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object ohair@286: * being used to perform marshal-time validation. If there is no ohair@286: * Schema set on the marshaller, then this method will return null ohair@286: * indicating that marshal-time validation will not be performed. ohair@286: * ohair@286: * @return the Schema object being used to perform marshal-time ohair@286: * validation or null if not present. ohair@286: * @throws UnsupportedOperationException could be thrown if this method is ohair@286: * invoked on an Marshaller created from a JAXBContext referencing ohair@286: * JAXB 1.0 mapped classes ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: public Schema getSchema(); ohair@286: ohair@286: /** ohair@286: *

ohair@286: * Register an instance of an implementation of this class with a {@link Marshaller} to externally listen ohair@286: * for marshal events. ohair@286: *

ohair@286: *

ohair@286: * This class enables pre and post processing of each marshalled object. ohair@286: * The event callbacks are called when marshalling from an instance that maps to an xml element or ohair@286: * complex type definition. The event callbacks are not called when marshalling from an instance of a ohair@286: * Java datatype that represents a simple type definition. ohair@286: *

ohair@286: *

ohair@286: * External listener is one of two different mechanisms for defining marshal event callbacks. ohair@286: * See Marshal Event Callbacks for an overview. ohair@286: * ohair@286: * @see Marshaller#setListener(Listener) ohair@286: * @see Marshaller#getListener() ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: public static abstract class Listener { ohair@286: /** ohair@286: *

ohair@286: * Callback method invoked before marshalling from source to XML. ohair@286: *

ohair@286: *

ohair@286: * This method is invoked just before marshalling process starts to marshal source. ohair@286: * Note that if the class of source defines its own beforeMarshal method, ohair@286: * the class specific callback method is invoked just before this method is invoked. ohair@286: * ohair@286: * @param source instance of JAXB mapped class prior to marshalling from it. ohair@286: */ ohair@286: public void beforeMarshal(Object source) { ohair@286: } ohair@286: ohair@286: /** ohair@286: *

ohair@286: * Callback method invoked after marshalling source to XML. ohair@286: *

ohair@286: *

ohair@286: * This method is invoked after source and all its descendants have been marshalled. ohair@286: * Note that if the class of source defines its own afterMarshal method, ohair@286: * the class specific callback method is invoked just before this method is invoked. ohair@286: * ohair@286: * @param source instance of JAXB mapped class after marshalling it. ohair@286: */ ohair@286: public void afterMarshal(Object source) { ohair@286: } ohair@286: } ohair@286: ohair@286: /** ohair@286: *

ohair@286: * Register marshal event callback {@link Listener} with this {@link Marshaller}. ohair@286: * ohair@286: *

ohair@286: * There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener. ohair@286: * One can unregister current Listener by setting listener to null. ohair@286: * ohair@286: * @param listener an instance of a class that implements {@link Listener} ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: public void setListener(Listener listener); ohair@286: ohair@286: /** ohair@286: *

Return {@link Listener} registered with this {@link Marshaller}. ohair@286: * ohair@286: * @return registered {@link Listener} or null if no Listener is registered with this Marshaller. ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: public Listener getListener(); ohair@286: }