org.docx4j.openpackaging.parts

Class JaxbXmlPart<E>

java.lang.Object

org.docx4j.openpackaging.Base

org.docx4j.openpackaging.parts.Part

org.docx4j.openpackaging.parts.JaxbXmlPart<E>

Type Parameters:

E - type of the content tree object

Direct Known Subclasses:

ChartColorStylePart, ChartExSpacePart, ChartStylePart, CommentsExtendedPart, CommentsIdsPart, CustomXmlDataStoragePropertiesPart, DocPropsCorePart, DocPropsCustomPart, DocPropsExtendedPart, FontTablePart, InkmlPart, JaxbCustomXmlDataStoragePart, JaxbXmlPartXPathAware, KeyMapCustomizationsPart, PeoplePart, RelationshipsPart, TableStylesPart, TaskpanesPart, VbaDataPart, WebExtensionPart, WebSettingsPart

public abstract class JaxbXmlPart<E>
extends Part

OPC Parts are either XML, or binary (or text) documents. Most are XML documents. docx4j aims to represent XML parts using JAXB. Any XML Part for which we have a JAXB representation (eg the main document part) should extend this Part. This class provides only one of the methods for serializing (marshalling) the Java content tree back into XML data found in javax.xml.bind.Marshaller interface. You can always use any of the others by getting the jaxbElement required by those methods. Insofar as unmarshalling is concerned, at present it doesn't contain all the methods in javax.xml.bind.unmarshaller interface. This is because the content always comes from the same place (ie from a zip file or JCR via org.docx4j.io.*). TODO - what is the best thing to unmarshall from?

Field Summary

Fields

Modifier and Type	Field and Description
protected E	jaxbElement The content tree (ie JAXB representation of the Part)
protected JAXBContext	jc
protected static org.slf4j.Logger	log
protected static long	MAX_BYTES_Unmarshal_Error

Fields inherited from class org.docx4j.openpackaging.parts.Part

pack

Fields inherited from class org.docx4j.openpackaging.Base

contentType, partName, relationships

Constructor Summary

Constructors

Constructor and Description
JaxbXmlPart(PartName partName)
JaxbXmlPart(PartName partName, JAXBContext jc)

Method Summary

Modifier and Type	Method and Description
void	addMcChoiceNamespace(String mcChoiceNamespace) Specify a namespace prefix (used in mc:Choice/@Requires) which docx4j should declare on the top-level element of the part (otherwise Microsoft Office won't be able to open the file).
E	getContents() Get the live contents of this part (the JAXB object model).
JAXBContext	getJAXBContext()
E	getJaxbElement() Get the live contents of this part.
String	getMcChoiceNamespaces()
String	getMceIgnorable()
String	getXML() See your content as XML.
boolean	isContentEqual(Part other)
boolean	isUnmarshalled()
void	marshal(Node node) Marshal the content tree rooted at jaxbElement into a DOM tree.
void	marshal(Node node, Object namespacePrefixMapper) Marshal the content tree rooted at jaxbElement into a DOM tree.
void	marshal(OutputStream os) Marshal the content tree rooted at jaxbElement into an output stream, using org.docx4j.jaxb.NamespacePrefixMapper.
void	marshal(OutputStream os, Object namespacePrefixMapper) Marshal the content tree rooted at jaxbElement into an output stream
void	pipe(SAXHandler saxHandler) Replace the contents of this part with the output of passing it through your SAXHandler.
void	pipe(StAXHandlerInterface handler) Replace the contents of this part with the output of passing it through your StAXHandler.
void	pipe(StAXHandlerInterface handler, StreamFilter filter) Replace the contents of this part with the output of passing it through your StAXHandler.
void	setContents(E jaxbElement) Set the contents of this part.
void	setJAXBContext(JAXBContext jc)
void	setJaxbElement(E jaxbElement)
void	setJaxbElement(JAXBResult result)
protected void	setMceIgnorable(McIgnorableNamespaceDeclarator namespacePrefixMapper) Where the mc:Ignorable attribute is present, ensure its contents matches the ignorable namespaces actually present.
void	transform(Templates xslt, Map<String,Object> transformParameters, Result result) Use an XSLT to alter the contents of this part.
E	unmarshal(Element el)
E	unmarshal(InputStream is) Unmarshal XML data from the specified InputStream and return the resulting content tree.
void	variableReplace(Map<String,String> mappings) unmarshallFromTemplate.

Methods inherited from class org.docx4j.openpackaging.parts.Part

getContentLengthAsLoaded, getOwningRelationshipPart, getPackage, getRelationshipType, getSourceRelationship, getSourceRelationships, getVersion, remove, rename, setContentLengthAsLoaded, setOwningRelationshipPart, setPackage, setPartShortcut, setRelationshipType, setSourceRelationship, setVersion

Methods inherited from class org.docx4j.openpackaging.Base

addTargetPart, addTargetPart, addTargetPart, addTargetPart, getContentType, getPartName, getRelationshipsPart, getRelationshipsPart, getUserData, reset, setContentType, setPartName, setRelationships, setUserData

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static org.slf4j.Logger log

jc

protected JAXBContext jc

MAX_BYTES_Unmarshal_Error

protected static long MAX_BYTES_Unmarshal_Error

jaxbElement

protected E jaxbElement

The content tree (ie JAXB representation of the Part)

Constructor Detail

JaxbXmlPart

public JaxbXmlPart(PartName partName)
            throws InvalidFormatException

Throws:

InvalidFormatException

JaxbXmlPart

public JaxbXmlPart(PartName partName,
                   JAXBContext jc)
            throws InvalidFormatException

Throws:

InvalidFormatException

Method Detail

setJAXBContext

public void setJAXBContext(JAXBContext jc)

getJAXBContext

public JAXBContext getJAXBContext()

Since:

2.7

getContents

public E getContents()
              throws Docx4JException

Get the live contents of this part (the JAXB object model). (An alias/synonym for older getJaxbElement(), but now throws exception)

Returns:

Throws:

Docx4JException

Since:

3.0

getJaxbElement

public E getJaxbElement()

Get the live contents of this part. (getContents() is preferred, this is the older/less friendly method name)

Returns:

setJaxbElement

public void setJaxbElement(E jaxbElement)

setContents

public void setContents(E jaxbElement)

Set the contents of this part. (Just an alias/synonym for setJaxbElement())

Parameters:

jaxbElement -

Since:

3.0

setJaxbElement

public void setJaxbElement(JAXBResult result)
                    throws JAXBException

Throws:

JAXBException

getXML

public String getXML()

See your content as XML. An easy way to invoke XmlUtils.marshaltoString

Returns:

Since:

3.0.0

isUnmarshalled

public boolean isUnmarshalled()

variableReplace

public void variableReplace(Map<String,String> mappings)
                     throws JAXBException,
                            Docx4JException

unmarshallFromTemplate. Where jaxbElement has not been unmarshalled yet, this is more efficient (3 times faster, in some testing) than calling XmlUtils.marshaltoString directly, since it avoids some JAXB processing.

Parameters:

mappings -

Throws:

JAXBException

Docx4JException

Since:

3.0.0

transform

public void transform(Templates xslt,
                      Map<String,Object> transformParameters,
                      Result result)
               throws Docx4JException

Use an XSLT to alter the contents of this part. You can transform to whatever you like (ie it doesn't have to be WordML content), which is why the API design is that you provide the Result object. If you do want to replace the content in this part, convert your result to an element or input stream, then invoke unmarshal on it, then setContents. (Unmarshal takes care of any unexpected content, sidestepping the issue of whether to do that before the transform (where reading the part directly), or after).

Parameters:

xslt -

transformParameters -

Throws:

Exception

Docx4JException

Since:

3.3.6

pipe

public void pipe(SAXHandler saxHandler)
          throws ParserConfigurationException,
                 SAXException,
                 Docx4JException,
                 IOException,
                 JAXBException

Replace the contents of this part with the output of passing it through your SAXHandler. This is offered as an alternative to the similar methods which use StAX. If you are unsure which to use, you should probably use the StAX approach. This is most efficient in the case where there has been no need for JAXB to unmarshal the contents. In this case, it is possible to process then save the contents without incurring JAXB overhead (you may see 1/4 heap usage).

Parameters:

saxHandler -

Throws:

ParserConfigurationException

SAXException

Docx4JException

IOException

JAXBException

pipe

public void pipe(StAXHandlerInterface handler)
          throws XMLStreamException,
                 Docx4JException,
                 JAXBException

Replace the contents of this part with the output of passing it through your StAXHandler. This is most efficient in the case where there has been no need for JAXB to unmarshal the contents. In this case, it is possible to process then save the contents without incurring JAXB overhead (you may see 1/4 heap usage).

Parameters:

handler -

Throws:

XMLStreamException

Docx4JException

JAXBException

pipe

public void pipe(StAXHandlerInterface handler,
                 StreamFilter filter)
          throws XMLStreamException,
                 Docx4JException,
                 JAXBException

Replace the contents of this part with the output of passing it through your StAXHandler. This is most efficient in the case where there has been no need for JAXB to unmarshal the contents. In this case, it is possible to process then save the contents without incurring JAXB overhead (you may see 1/4 heap usage).

Parameters:

handler -

filter -

Throws:

XMLStreamException

Docx4JException

JAXBException

marshal

public void marshal(Node node)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into a DOM tree.

Parameters:

node - DOM nodes will be added as children of this node. This parameter must be a Node that accepts children (Document, DocumentFragment, or Element)

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

marshal

public void marshal(Node node,
                    Object namespacePrefixMapper)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into a DOM tree.

Parameters:

node - DOM nodes will be added as children of this node. This parameter must be a Node that accepts children (Document, DocumentFragment, or Element)

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

marshal

public void marshal(OutputStream os)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into an output stream, using org.docx4j.jaxb.NamespacePrefixMapper.

Parameters:

os - XML will be added to this stream.

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

marshal

public void marshal(OutputStream os,
                    Object namespacePrefixMapper)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into an output stream

Parameters:

os - XML will be added to this stream.

namespacePrefixMapper - namespacePrefixMapper

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

getMceIgnorable

public String getMceIgnorable()

setMceIgnorable

protected void setMceIgnorable(McIgnorableNamespaceDeclarator namespacePrefixMapper)

Where the mc:Ignorable attribute is present, ensure its contents matches the ignorable namespaces actually present.

getMcChoiceNamespaces

public String getMcChoiceNamespaces()

addMcChoiceNamespace

public void addMcChoiceNamespace(String mcChoiceNamespace)

Specify a namespace prefix (used in mc:Choice/@Requires) which docx4j should declare on the top-level element of the part (otherwise Microsoft Office won't be able to open the file). Specify a prefix (eg 'wpg') as opposed to the namespace itself. This is often done automatically (see further McIgnorableNamespaceDeclarator), but where it isn't, you should invoke this method directly from your code.

Parameters:

mcChoiceNamespace -

unmarshal

public E unmarshal(InputStream is)
            throws JAXBException

Unmarshal XML data from the specified InputStream and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API.

Implements Unmarshal Global Root Element.

Parameters:

is - the InputStream to unmarshal XML data from

Returns:

the newly created root object of the java content tree

Throws:

JAXBException - If any unexpected errors occur while unmarshalling

unmarshal

public E unmarshal(Element el)
            throws JAXBException

Throws:

JAXBException

isContentEqual

public boolean isContentEqual(Part other)
                       throws Docx4JException

Specified by:

isContentEqual in class Part

Throws:

Docx4JException