Package 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:
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 Details

    • log

      protected static org.slf4j.Logger log

    • jc

      protected javax.xml.bind.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 Details

  • Method Details

    • setJAXBContext

      public void setJAXBContext​(javax.xml.bind.JAXBContext jc)

    • getJAXBContext

      public javax.xml.bind.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​(javax.xml.bind.util.JAXBResult result) throws javax.xml.bind.JAXBException
      Throws:
      javax.xml.bind.JAXBException

    • getXML

      public java.lang.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​(java.util.Map<java.lang.String,​java.lang.String> mappings) throws javax.xml.bind.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:
      javax.xml.bind.JAXBException
      Docx4JException
      Since:
      3.0.0

    • transform

      public void transform​(javax.xml.transform.Templates xslt, java.util.Map<java.lang.String,​java.lang.Object> transformParameters, javax.xml.transform.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:
      java.lang.Exception
      Docx4JException
      Since:
      3.3.6

    • pipe

      public void pipe​(SAXHandler saxHandler) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXException, Docx4JException, java.io.IOException, javax.xml.bind.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:
      javax.xml.parsers.ParserConfigurationException
      org.xml.sax.SAXException
      Docx4JException
      java.io.IOException
      javax.xml.bind.JAXBException

    • pipe

      public void pipe​(StAXHandlerInterface handler) throws javax.xml.stream.XMLStreamException, Docx4JException, javax.xml.bind.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:
      javax.xml.stream.XMLStreamException
      Docx4JException
      javax.xml.bind.JAXBException

    • pipe

      public void pipe​(StAXHandlerInterface handler, javax.xml.stream.StreamFilter filter) throws javax.xml.stream.XMLStreamException, Docx4JException, javax.xml.bind.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:
      javax.xml.stream.XMLStreamException
      Docx4JException
      javax.xml.bind.JAXBException

    • marshal

      public void marshal​(org.w3c.dom.Node node) throws javax.xml.bind.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:
      javax.xml.bind.JAXBException - If any unexpected problem occurs during the marshalling.

    • marshal

      public void marshal​(org.w3c.dom.Node node, java.lang.Object namespacePrefixMapper) throws javax.xml.bind.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:
      javax.xml.bind.JAXBException - If any unexpected problem occurs during the marshalling.

    • marshal

      public void marshal​(java.io.OutputStream os) throws javax.xml.bind.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:
      javax.xml.bind.JAXBException - If any unexpected problem occurs during the marshalling.

    • marshal

      public void marshal​(java.io.OutputStream os, java.lang.Object namespacePrefixMapper) throws javax.xml.bind.JAXBException
      Marshal the content tree rooted at jaxbElement into an output stream
      Parameters:
      os - XML will be added to this stream.
      namespacePrefixMapper - namespacePrefixMapper
      Throws:
      javax.xml.bind.JAXBException - If any unexpected problem occurs during the marshalling.

    • getMceIgnorable

      public java.lang.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 java.lang.String getMcChoiceNamespaces()

    • addMcChoiceNamespace

      public void addMcChoiceNamespace​(java.lang.String mcChoiceNamespace)

    • unmarshal

      public E unmarshal​(java.io.InputStream is) throws javax.xml.bind.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:
      javax.xml.bind.JAXBException - If any unexpected errors occur while unmarshalling

    • unmarshal

      public E unmarshal​(org.w3c.dom.Element el) throws javax.xml.bind.JAXBException
      Throws:
      javax.xml.bind.JAXBException

    • isContentEqual

      public boolean isContentEqual​(Part other) throws Docx4JException
      Specified by:
      isContentEqual in class Part
      Throws:
      Docx4JException