com.sun.xml.bind.v2.runtime

Class XMLSerializer

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.

Field Summary
AttachmentMarshallerattachmentMarshaller
ThreadLocal<Property>currentProperty
JAXBContextImplgrammar
int[]knownUri2prefixIndexMap
NameListnameList
Constructor Summary
XMLSerializer(MarshallerImpl _owner)
Method Summary
voidaddInscopeBinding(String nsUri, String prefix)
This method can be called after XMLSerializer is called but before the marshalling begins, to set the currently in-scope namespace bindings.
voidattribute(String uri, String local, String value)
voidattribute(Name name, CharSequence value)
voidattWildcardAsAttributes(Map<QName,String> attributes, String fieldName)
voidattWildcardAsURIs(Map<QName,String> attributes, String fieldName)
voidchildAsRoot(Object obj)
voidchildAsSoleContent(Object child, String fieldName)
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.
voidchildAsXsiType(Object child, String fieldName, JaxBeanInfo expected, boolean nillable)
This method is called when a type child object is found.
voidclose()
voidendAttributes()
Switches to the "marshal child texts/elements" mode.
voidendDocument()
voidendElement()
Ends marshalling of an element.
voidendNamespaceDecls(Object innerPeer)
voiderrorMissingId(Object obj)
Called when a referenced object doesn't have an ID.
Base64DatagetCachedBase64DataInstance()
Gets the cached instance of Base64Data.
ValidationEventLocatorgetCurrentLocation(String fieldName)
PropertygetCurrentProperty()
May return null when the property hasn't been set.
TransformergetIdentityTransformer()
booleangetInlineBinaryFlag()
static XMLSerializergetInstance()
When called from within the realm of the marshaller, this method returns the current XMLSerializer in charge.
protected ValidationEventLocatorgetLocation()
NamespaceContext2getNamespaceContext()
booleangetObjectIdentityCycleDetection()
QNamegetSchemaType()
StringgetXMIMEContentType()
Gets the MIME type with which the binary content shall be printed.
booleanhandleError(Exception e)
booleanhandleError(Exception e, Object source, String fieldName)
booleanhandleEvent(ValidationEvent event)
voidleafElement(Name tagName, String data, String fieldName)
voidleafElement(Name tagName, Pcdata data, String fieldName)
voidleafElement(Name tagName, int data, String fieldName)
StringonID(Object owner, String value)
StringonIDREF(Object obj)
voidreconcileID()
voidreportError(ValidationEvent ve)
voidreportError(String fieldName, Throwable t)
Report an error found as an exception.
MimeTypesetExpectedMimeType(MimeType expectedMimeType)
This method is used by MimeTypedTransducer to set the expected MIME type for the encapsulated Transducer.
booleansetInlineBinaryFlag(boolean value)
voidsetObjectIdentityCycleDetection(boolean val)
voidsetPrefixMapper(NamespacePrefixMapper prefixMapper)
QNamesetSchemaType(QName st)
voidstartDocument(XmlOutput out, boolean fragment, String schemaLocation, String noNsSchemaLocation)
Reset this object to write to the specified output.
voidstartElement(Name tagName, Object outerPeer)
voidstartElement(String nsUri, String localName, String preferredPrefix, Object outerPeer)
voidstartElementForce(String nsUri, String localName, String forcedPrefix, Object outerPeer)
Variation of XMLSerializer that forces a specific prefix.
voidtext(String text, String fieldName)
Marshalls text.
voidtext(Pcdata text, String fieldName)
The XMLSerializer method that takes Pcdata.
<E> voidwriteDom(E element, DomHandler<E,?> domHandler, Object parentBean, String fieldName)
voidwriteXsiNilTrue()
Short for the following call sequence:
         getNamespaceContext().declareNamespace(WellKnownNamespace.XML_SCHEMA_INSTANCE,"xsi",true);
         endNamespaceDecls();
         attribute(WellKnownNamespace.XML_SCHEMA_INSTANCE,"nil","true");
         endAttributes();
 

Field Detail

attachmentMarshaller

public AttachmentMarshaller attachmentMarshaller

currentProperty

ThreadLocal<Property> currentProperty

grammar

public final JAXBContextImpl grammar

knownUri2prefixIndexMap

public final int[] knownUri2prefixIndexMap

nameList

public final NameList nameList

Constructor Detail

XMLSerializer

XMLSerializer(MarshallerImpl _owner)

Method Detail

addInscopeBinding

public void addInscopeBinding(String nsUri, String prefix)
This method can be called after XMLSerializer 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.

attribute

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

attribute

public void attribute(Name name, CharSequence value)

attWildcardAsAttributes

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

attWildcardAsURIs

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

childAsRoot

public void childAsRoot(Object obj)

childAsSoleContent

public final void childAsSoleContent(Object child, String fieldName)
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.

childAsXsiType

public final void childAsXsiType(Object child, String fieldName, JaxBeanInfo expected, boolean nillable)
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'.

close

public void close()

endAttributes

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

endDocument

public void endDocument()

endElement

public void endElement()
Ends marshalling of an element. Pops the internal stack.

endNamespaceDecls

public void endNamespaceDecls(Object innerPeer)

errorMissingId

public void errorMissingId(Object obj)
Called when a referenced object doesn't have an ID.

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.

getCurrentLocation

public ValidationEventLocator getCurrentLocation(String fieldName)

getCurrentProperty

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

getIdentityTransformer

public Transformer getIdentityTransformer()

getInlineBinaryFlag

public boolean getInlineBinaryFlag()

getInstance

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

getLocation

protected ValidationEventLocator getLocation()

getNamespaceContext

public NamespaceContext2 getNamespaceContext()

getObjectIdentityCycleDetection

public boolean getObjectIdentityCycleDetection()

getSchemaType

public QName getSchemaType()

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: getXMIMEContentType

handleError

public boolean handleError(Exception e)

handleError

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

handleEvent

public boolean handleEvent(ValidationEvent event)

leafElement

public void leafElement(Name tagName, String data, String fieldName)

leafElement

public void leafElement(Name tagName, Pcdata data, String fieldName)

leafElement

public void leafElement(Name tagName, int data, String fieldName)

onID

public String onID(Object owner, String value)

onIDREF

public String onIDREF(Object obj)

reconcileID

void reconcileID()

reportError

public void reportError(ValidationEvent ve)

reportError

public final void reportError(String fieldName, Throwable t)
Report an error found as an exception.

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

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)

setObjectIdentityCycleDetection

public void setObjectIdentityCycleDetection(boolean val)

setPrefixMapper

public void setPrefixMapper(NamespacePrefixMapper prefixMapper)

setSchemaType

public QName setSchemaType(QName st)

startDocument

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

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 XMLSerializer that forces a specific prefix. Needed to preserve the prefix when marshalling DOM.

text

public void text(String text, String fieldName)
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>.

text

public void text(Pcdata text, String fieldName)
The XMLSerializer method that takes Pcdata.

writeDom

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

writeXsiNilTrue

public final void writeXsiNilTrue()
Short for the following call sequence:
         getNamespaceContext().declareNamespace(WellKnownNamespace.XML_SCHEMA_INSTANCE,"xsi",true);
         endNamespaceDecls();
         attribute(WellKnownNamespace.XML_SCHEMA_INSTANCE,"nil","true");
         endAttributes();