Package com.sun.xml.bind.v2.runtime

Class XMLSerializer

  • All Implemented Interfaces:
    javax.xml.bind.ValidationEventHandler, org.xml.sax.ErrorHandler
    public final class XMLSerializer
extends Coordinator
    Receives XML serialization event and writes to XmlOutput.

    This object coordinates the overall marshalling efforts across different content-tree objects and different target formats.

    The following CFG gives the proper sequence of method invocation. 

     MARSHALLING  :=  ELEMENT
 ELEMENT      :=  "startElement" NSDECL* "endNamespaceDecls"
                        ATTRIBUTE* "endAttributes" BODY "endElement"
 
 NSDECL       :=  "declareNamespace"
 
 ATTRIBUTE    :=  "attribute"
 ATTVALUES    :=  "text"*
 
 
 BODY         :=  ( "text" | ELEMENT )*

    A marshalling of one element consists of two stages. The first stage is for marshalling attributes and collecting namespace declarations. The second stage is for marshalling characters/child elements of that element.

    Observe that multiple invocation of "text" is allowed.

    Also observe that the namespace declarations are allowed only between "startElement" and "endAttributes".

    Exceptions in marshaller

    IOException, SAXException, and XMLStreamException are thrown from XmlOutput. They are always considered fatal, and therefore caught only by MarshallerImpl.

    AccessorException can be thrown when an access to a property/field fails, and this is considered as a recoverable error, so it's caught everywhere.

    Author:
    Kohsuke Kawaguchi

    • Field Detail

      • nameList

        public final NameList nameList

      • knownUri2prefixIndexMap

        public final int[] knownUri2prefixIndexMap

      • attachmentMarshaller

        public javax.xml.bind.attachment.AttachmentMarshaller attachmentMarshaller

    • Method Detail

      • getCachedBase64DataInstance

        public Base64Data getCachedBase64DataInstance()
        Deprecated.
        Base64Data is no longer cached, so that XMLStreamWriterEx impl can retain the data, like JAX-WS does.
        Gets the cached instance of Base64Data.

      • reportError

        public void reportError​(javax.xml.bind.ValidationEvent ve)
                 throws org.xml.sax.SAXException
        Throws:
        org.xml.sax.SAXException

      • reportError

        public final void reportError​(java.lang.String fieldName,
                              java.lang.Throwable t)
                       throws org.xml.sax.SAXException
        Report an error found as an exception.
        Parameters:
        fieldName - the name of the property being processed when an error is found.
        Throws:
        org.xml.sax.SAXException

      • startElement

        public void startElement​(Name tagName,
                         java.lang.Object outerPeer)

      • startElement

        public void startElement​(java.lang.String nsUri,
                         java.lang.String localName,
                         java.lang.String preferredPrefix,
                         java.lang.Object outerPeer)

      • startElementForce

        public void startElementForce​(java.lang.String nsUri,
                              java.lang.String localName,
                              java.lang.String forcedPrefix,
                              java.lang.Object outerPeer)
        Variation of startElement(String, String, String, Object) that forces a specific prefix. Needed to preserve the prefix when marshalling DOM.

      • endNamespaceDecls

        public void endNamespaceDecls​(java.lang.Object innerPeer)
                       throws java.io.IOException,
                              javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • endAttributes

        public void endAttributes()
                   throws org.xml.sax.SAXException,
                          java.io.IOException,
                          javax.xml.stream.XMLStreamException
        Switches to the "marshal child texts/elements" mode. This method has to be called after the 1st pass is completed.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • endElement

        public void endElement()
                throws org.xml.sax.SAXException,
                       java.io.IOException,
                       javax.xml.stream.XMLStreamException
        Ends marshalling of an element. Pops the internal stack.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • leafElement

        public void leafElement​(Name tagName,
                        java.lang.String data,
                        java.lang.String fieldName)
                 throws org.xml.sax.SAXException,
                        java.io.IOException,
                        javax.xml.stream.XMLStreamException
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • leafElement

        public void leafElement​(Name tagName,
                        Pcdata data,
                        java.lang.String fieldName)
                 throws org.xml.sax.SAXException,
                        java.io.IOException,
                        javax.xml.stream.XMLStreamException
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • leafElement

        public void leafElement​(Name tagName,
                        int data,
                        java.lang.String fieldName)
                 throws org.xml.sax.SAXException,
                        java.io.IOException,
                        javax.xml.stream.XMLStreamException
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • text

        public void text​(java.lang.String text,
                 java.lang.String fieldName)
          throws org.xml.sax.SAXException,
                 java.io.IOException,
                 javax.xml.stream.XMLStreamException
        Marshalls text.

        This method can be called after the endAttributes() method to marshal texts inside elements. If the method is called more than once, those texts are considered as separated by whitespaces. For example, 

         c.startElement("","foo");
 c.endAttributes();
 c.text("abc");
 c.text("def");
   c.startElement("","bar");
   c.endAttributes();
   c.endElement();
 c.text("ghi");
 c.endElement();
        will generate <foo>abc def<bar/>ghi</foo>.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • text

        public void text​(Pcdata text,
                 java.lang.String fieldName)
          throws org.xml.sax.SAXException,
                 java.io.IOException,
                 javax.xml.stream.XMLStreamException
        The text(String, String) method that takes Pcdata.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • attribute

        public void attribute​(java.lang.String uri,
                      java.lang.String local,
                      java.lang.String value)
               throws org.xml.sax.SAXException
        Throws:
        org.xml.sax.SAXException

      • attribute

        public void attribute​(Name name,
                      java.lang.CharSequence value)
               throws java.io.IOException,
                      javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • onID

        public java.lang.String onID​(java.lang.Object owner,
                             java.lang.String value)

      • onIDREF

        public java.lang.String onIDREF​(java.lang.Object obj)
                         throws org.xml.sax.SAXException
        Throws:
        org.xml.sax.SAXException

      • childAsRoot

        public void childAsRoot​(java.lang.Object obj)
                 throws javax.xml.bind.JAXBException,
                        java.io.IOException,
                        org.xml.sax.SAXException,
                        javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.bind.JAXBException
        java.io.IOException
        org.xml.sax.SAXException
        javax.xml.stream.XMLStreamException

      • childAsSoleContent

        public final void childAsSoleContent​(java.lang.Object child,
                                     java.lang.String fieldName)
                              throws org.xml.sax.SAXException,
                                     java.io.IOException,
                                     javax.xml.stream.XMLStreamException
        The equivalent of: 
         childAsURIs(child, fieldName);
 endNamespaceDecls();
 childAsAttributes(child, fieldName);
 endAttributes();
 childAsBody(child, fieldName);
        This produces the given child object as the sole content of an element. Used to reduce the code size in the generated marshaller.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • childAsXsiType

        public final void childAsXsiType​(java.lang.Object child,
                                 java.lang.String fieldName,
                                 JaxBeanInfo expected,
                                 boolean nillable)
                          throws org.xml.sax.SAXException,
                                 java.io.IOException,
                                 javax.xml.stream.XMLStreamException
        This method is called when a type child object is found.

        This method produces events of the following form: 

         NSDECL* "endNamespaceDecls" ATTRIBUTE* "endAttributes" BODY
        optionally including @xsi:type if necessary.
        Parameters:
        child - Object to be marshalled. The JaxBeanInfo for this object must return a type name.
        expected - Expected type of the object.
        fieldName - property name of the parent objeect from which 'o' comes. Used as a part of the error message in case anything goes wrong with 'o'.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • attWildcardAsURIs

        public void attWildcardAsURIs​(java.util.Map<javax.xml.namespace.QName,​java.lang.String> attributes,
                              java.lang.String fieldName)

      • attWildcardAsAttributes

        public void attWildcardAsAttributes​(java.util.Map<javax.xml.namespace.QName,​java.lang.String> attributes,
                                    java.lang.String fieldName)
                             throws org.xml.sax.SAXException
        Throws:
        org.xml.sax.SAXException

      • writeXsiNilTrue

        public final void writeXsiNilTrue()
                           throws org.xml.sax.SAXException,
                                  java.io.IOException,
                                  javax.xml.stream.XMLStreamException
        Short for the following call sequence: 
                 getNamespaceContext().declareNamespace(WellKnownNamespace.XML_SCHEMA_INSTANCE,"xsi",true);
         endNamespaceDecls();
         attribute(WellKnownNamespace.XML_SCHEMA_INSTANCE,"nil","true");
         endAttributes();
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.stream.XMLStreamException

      • writeDom

        public <E> void writeDom​(E element,
                         javax.xml.bind.annotation.DomHandler<E,​?> domHandler,
                         java.lang.Object parentBean,
                         java.lang.String fieldName)
                  throws org.xml.sax.SAXException
        Throws:
        org.xml.sax.SAXException

      • getIdentityTransformer

        public javax.xml.transform.Transformer getIdentityTransformer()

      • startDocument

        public void startDocument​(XmlOutput out,
                          boolean fragment,
                          java.lang.String schemaLocation,
                          java.lang.String noNsSchemaLocation)
                   throws java.io.IOException,
                          org.xml.sax.SAXException,
                          javax.xml.stream.XMLStreamException
        Reset this object to write to the specified output.
        Parameters:
        schemaLocation - if non-null, this value is printed on the root element as xsi:schemaLocation
        noNsSchemaLocation - Similar to 'schemaLocation' but this one works for xsi:noNamespaceSchemaLocation
        Throws:
        java.io.IOException
        org.xml.sax.SAXException
        javax.xml.stream.XMLStreamException

      • endDocument

        public void endDocument()
                 throws java.io.IOException,
                        org.xml.sax.SAXException,
                        javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        org.xml.sax.SAXException
        javax.xml.stream.XMLStreamException

      • close

        public void close()

      • setExpectedMimeType

        public javax.activation.MimeType setExpectedMimeType​(javax.activation.MimeType expectedMimeType)
        This method is used by MimeTypedTransducer to set the expected MIME type for the encapsulated Transducer.

      • setInlineBinaryFlag

        public boolean setInlineBinaryFlag​(boolean value)

      • getInlineBinaryFlag

        public boolean getInlineBinaryFlag()

      • setSchemaType

        public javax.xml.namespace.QName setSchemaType​(javax.xml.namespace.QName st)

      • getSchemaType

        public javax.xml.namespace.QName getSchemaType()

      • setObjectIdentityCycleDetection

        public void setObjectIdentityCycleDetection​(boolean val)

      • getObjectIdentityCycleDetection

        public boolean getObjectIdentityCycleDetection()

      • handleError

        public boolean handleError​(java.lang.Exception e)

      • handleError

        public boolean handleError​(java.lang.Exception e,
                           java.lang.Object source,
                           java.lang.String fieldName)

      • handleEvent

        public boolean handleEvent​(javax.xml.bind.ValidationEvent event)

      • errorMissingId

        public void errorMissingId​(java.lang.Object obj)
                    throws org.xml.sax.SAXException
        Called when a referenced object doesn't have an ID.
        Throws:
        org.xml.sax.SAXException

      • getCurrentLocation

        public javax.xml.bind.ValidationEventLocator getCurrentLocation​(java.lang.String fieldName)

      • getLocation

        protected javax.xml.bind.ValidationEventLocator getLocation()
        Description copied from class: Coordinator
        Gets the current location. Used for reporting the error source location.
        Specified by:
        getLocation in class Coordinator

      • getCurrentProperty

        public Property getCurrentProperty()
        May return null when the property hasn't been set. Introduced based on Jersey requirements.

      • clearCurrentProperty

        public void clearCurrentProperty()
        Takes care of cleaning the currentProperty. Must be called from the same thread that created the XMLSerializer.

      • getInstance

        public static XMLSerializer getInstance()
        When called from within the realm of the marshaller, this method returns the current XMLSerializer in charge.