com.sun.xml.bind.v2.runtime

Class XMLSerializer

java.lang.Object

com.sun.xml.bind.v2.runtime.Coordinator

com.sun.xml.bind.v2.runtime.XMLSerializer

All Implemented Interfaces:

ValidationEventHandler, 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 Summary

Fields

Modifier and Type	Field and Description
AttachmentMarshaller	attachmentMarshaller
JAXBContextImpl	grammar
int[]	knownUri2prefixIndexMap
NameList	nameList

Method Summary

Modifier and Type	Method and Description
void	addInscopeBinding(String nsUri, String prefix) This method can be called after startDocument(com.sun.xml.bind.v2.runtime.output.XmlOutput, boolean, java.lang.String, java.lang.String) is called but before the marshalling begins, to set the currently in-scope namespace bindings.
void	attribute(Name name, CharSequence value)
void	attribute(String uri, String local, String value)
void	attWildcardAsAttributes(Map<QName,String> attributes, String fieldName)
void	attWildcardAsURIs(Map<QName,String> attributes, String fieldName)
void	childAsRoot(Object obj)
void	childAsSoleContent(Object child, String fieldName) The equivalent of:
void	childAsXsiType(Object child, String fieldName, JaxBeanInfo expected, boolean nillable) This method is called when a type child object is found.
void	clearCurrentProperty() Takes care of cleaning the currentProperty.
void	close()
void	endAttributes() Switches to the "marshal child texts/elements" mode.
void	endDocument()
void	endElement() Ends marshalling of an element.
void	endNamespaceDecls(Object innerPeer)
void	errorMissingId(Object obj) Called when a referenced object doesn't have an ID.
Base64Data	getCachedBase64DataInstance() Deprecated. Base64Data is no longer cached, so that XMLStreamWriterEx impl can retain the data, like JAX-WS does.
ValidationEventLocator	getCurrentLocation(String fieldName)
Property	getCurrentProperty() May return null when the property hasn't been set.
Transformer	getIdentityTransformer()
boolean	getInlineBinaryFlag()
static XMLSerializer	getInstance() When called from within the realm of the marshaller, this method returns the current XMLSerializer in charge.
protected ValidationEventLocator	getLocation() Gets the current location.
NamespaceContext2	getNamespaceContext()
boolean	getObjectIdentityCycleDetection()
QName	getSchemaType()
String	getXMIMEContentType() Gets the MIME type with which the binary content shall be printed.
boolean	handleError(Exception e)
boolean	handleError(Exception e, Object source, String fieldName)
boolean	handleEvent(ValidationEvent event) Receive notification of a validation warning or error.
void	leafElement(Name tagName, int data, String fieldName)
void	leafElement(Name tagName, Pcdata data, String fieldName)
void	leafElement(Name tagName, String data, String fieldName)
String	onID(Object owner, String value)
String	onIDREF(Object obj)
void	reportError(String fieldName, Throwable t) Report an error found as an exception.
void	reportError(ValidationEvent ve)
MimeType	setExpectedMimeType(MimeType expectedMimeType) This method is used by MimeTypedTransducer to set the expected MIME type for the encapsulated Transducer.
boolean	setInlineBinaryFlag(boolean value)
void	setObjectIdentityCycleDetection(boolean val)
void	setPrefixMapper(NamespacePrefixMapper prefixMapper)
QName	setSchemaType(QName st)
void	startDocument(XmlOutput out, boolean fragment, String schemaLocation, String noNsSchemaLocation) Reset this object to write to the specified output.
void	startElement(Name tagName, Object outerPeer)
void	startElement(String nsUri, String localName, String preferredPrefix, Object outerPeer)
void	startElementForce(String nsUri, String localName, String forcedPrefix, Object outerPeer) Variation of startElement(String, String, String, Object) that forces a specific prefix.
void	text(Pcdata text, String fieldName) The text(String, String) method that takes Pcdata.
void	text(String text, String fieldName) Marshalls text.
<E> void	writeDom(E element, DomHandler<E,?> domHandler, Object parentBean, String fieldName)
void	writeXsiNilTrue() Short for the following call sequence:

Methods inherited from class com.sun.xml.bind.v2.runtime.Coordinator

_getInstance, containsAdapter, error, fatalError, getAdapter, popCoordinator, pushCoordinator, putAdapter, warning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

grammar

public final JAXBContextImpl grammar

nameList

public final NameList nameList

knownUri2prefixIndexMap

public final int[] knownUri2prefixIndexMap

attachmentMarshaller

public 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(ValidationEvent ve)
                 throws SAXException

Throws:

SAXException

reportError

public final void reportError(String fieldName,
                              Throwable t)
                       throws SAXException

Report an error found as an exception.

Parameters:

fieldName - the name of the property being processed when an error is found.

Throws:

SAXException

startElement

public void startElement(Name tagName,
                         Object outerPeer)

startElement

public void startElement(String nsUri,
                         String localName,
                         String preferredPrefix,
                         Object outerPeer)

startElementForce

public void startElementForce(String nsUri,
                              String localName,
                              String forcedPrefix,
                              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(Object innerPeer)
                       throws IOException,
                              XMLStreamException

Throws:

IOException

XMLStreamException

endAttributes

public void endAttributes()
                   throws SAXException,
                          IOException,
                          XMLStreamException

Switches to the "marshal child texts/elements" mode. This method has to be called after the 1st pass is completed.

Throws:

SAXException

IOException

XMLStreamException

endElement

public void endElement()
                throws SAXException,
                       IOException,
                       XMLStreamException

Ends marshalling of an element. Pops the internal stack.

Throws:

SAXException

IOException

XMLStreamException

leafElement

public void leafElement(Name tagName,
                        String data,
                        String fieldName)
                 throws SAXException,
                        IOException,
                        XMLStreamException

Throws:

SAXException

IOException

XMLStreamException

leafElement

public void leafElement(Name tagName,
                        Pcdata data,
                        String fieldName)
                 throws SAXException,
                        IOException,
                        XMLStreamException

Throws:

SAXException

IOException

XMLStreamException

leafElement

public void leafElement(Name tagName,
                        int data,
                        String fieldName)
                 throws SAXException,
                        IOException,
                        XMLStreamException

Throws:

SAXException

IOException

XMLStreamException

text

public void text(String text,
                 String fieldName)
          throws SAXException,
                 IOException,
                 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:

SAXException

IOException

XMLStreamException

text

public void text(Pcdata text,
                 String fieldName)
          throws SAXException,
                 IOException,
                 XMLStreamException

The text(String, String) method that takes Pcdata.

Throws:

SAXException

IOException

XMLStreamException

attribute

public void attribute(String uri,
                      String local,
                      String value)
               throws SAXException

Throws:

SAXException

attribute

public void attribute(Name name,
                      CharSequence value)
               throws IOException,
                      XMLStreamException

Throws:

IOException

XMLStreamException

getNamespaceContext

public NamespaceContext2 getNamespaceContext()

onID

public String onID(Object owner,
                   String value)

onIDREF

public String onIDREF(Object obj)
               throws SAXException

Throws:

SAXException

childAsRoot

public void childAsRoot(Object obj)
                 throws JAXBException,
                        IOException,
                        SAXException,
                        XMLStreamException

Throws:

JAXBException

IOException

SAXException

XMLStreamException

childAsSoleContent

public final void childAsSoleContent(Object child,
                                     String fieldName)
                              throws SAXException,
                                     IOException,
                                     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:

SAXException

IOException

XMLStreamException

childAsXsiType

public final void childAsXsiType(Object child,
                                 String fieldName,
                                 JaxBeanInfo expected,
                                 boolean nillable)
                          throws SAXException,
                                 IOException,
                                 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:

SAXException

IOException

XMLStreamException

attWildcardAsURIs

public void attWildcardAsURIs(Map<QName,String> attributes,
                              String fieldName)

attWildcardAsAttributes

public void attWildcardAsAttributes(Map<QName,String> attributes,
                                    String fieldName)
                             throws SAXException

Throws:

SAXException

writeXsiNilTrue

public final void writeXsiNilTrue()
                           throws SAXException,
                                  IOException,
                                  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:

SAXException

IOException

XMLStreamException

writeDom

public <E> void writeDom(E element,
                         DomHandler<E,?> domHandler,
                         Object parentBean,
                         String fieldName)
                  throws SAXException

Throws:

SAXException

getIdentityTransformer

public Transformer getIdentityTransformer()

setPrefixMapper

public void setPrefixMapper(NamespacePrefixMapper prefixMapper)

startDocument

public void startDocument(XmlOutput out,
                          boolean fragment,
                          String schemaLocation,
                          String noNsSchemaLocation)
                   throws IOException,
                          SAXException,
                          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:

IOException

SAXException

XMLStreamException

endDocument

public void endDocument()
                 throws IOException,
                        SAXException,
                        XMLStreamException

Throws:

IOException

SAXException

XMLStreamException

close

public void close()

addInscopeBinding

public void addInscopeBinding(String nsUri,
                              String prefix)

This method can be called after startDocument(com.sun.xml.bind.v2.runtime.output.XmlOutput, boolean, java.lang.String, java.lang.String) is called but before the marshalling begins, to set the currently in-scope namespace bindings.

This method is useful to avoid redundant namespace declarations when the marshalling is producing a sub-document.

getXMIMEContentType

public String getXMIMEContentType()

Gets the MIME type with which the binary content shall be printed.

This method shall be used from those RuntimeBuiltinLeafInfo that are bound to base64Binary.

See Also:

JAXBContextImpl.getXMIMEContentType(Object)

setExpectedMimeType

public MimeType setExpectedMimeType(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 QName setSchemaType(QName st)

getSchemaType

public QName getSchemaType()

setObjectIdentityCycleDetection

public void setObjectIdentityCycleDetection(boolean val)

getObjectIdentityCycleDetection

public boolean getObjectIdentityCycleDetection()

handleError

public boolean handleError(Exception e)

handleError

public boolean handleError(Exception e,
                           Object source,
                           String fieldName)

handleEvent

public boolean handleEvent(ValidationEvent event)

Description copied from interface: ValidationEventHandler

Receive notification of a validation warning or error. The ValidationEvent will have a ValidationEventLocator embedded in it that indicates where the error or warning occurred.

If an unchecked runtime exception is thrown from this method, the JAXB provider will treat it as if the method returned false and interrupt the current unmarshal, validate, or marshal operation.

Parameters:

event - the encapsulated validation event information. It is a provider error if this parameter is null.

Returns:

true if the JAXB Provider should attempt to continue the current unmarshal, validate, or marshal operation after handling this warning/error, false if the provider should terminate the current operation with the appropriate UnmarshalException, ValidationException, or MarshalException.

errorMissingId

public void errorMissingId(Object obj)
                    throws SAXException

Called when a referenced object doesn't have an ID.

Throws:

SAXException

getCurrentLocation

public ValidationEventLocator getCurrentLocation(String fieldName)

getLocation

protected 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.