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:
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 jakarta.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 jakarta.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 jakarta.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(jakarta.xml.bind.JAXBContext jc)

    • getJAXBContext

      public jakarta.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(jakarta.xml.bind.util.JAXBResult result) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.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 jakarta.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:
      jakarta.xml.bind.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, jakarta.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:
      ParserConfigurationException
      SAXException
      Docx4JException
      IOException
      jakarta.xml.bind.JAXBException

    • pipe

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

    • pipe

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

    • getXMLStreamReader

      public XMLStreamReader getXMLStreamReader(StreamFilter filter) throws FactoryConfigurationError, Docx4JException, XMLStreamException
      Throws:
      FactoryConfigurationError
      Docx4JException
      XMLStreamException

    • replacePartContent

      public void replacePartContent(byte[] bytes) throws jakarta.xml.bind.JAXBException, Docx4JException
      Replace the content of this part. Unless the part has been unmashalled already, this is done at the PartStore level.
      Throws:
      jakarta.xml.bind.JAXBException
      Docx4JException
      Since:
      11.5.3

    • marshal

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

    • marshal

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

    • marshal

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

    • marshal

      public void marshal(OutputStream os, Object namespacePrefixMapper) throws jakarta.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:
      jakarta.xml.bind.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 -

    • getConfiguredUnmarshaller

      protected jakarta.xml.bind.Unmarshaller getConfiguredUnmarshaller(boolean eventHandlerContinue) throws jakarta.xml.bind.JAXBException
      An Unmarshaller configured with our event handler and listener.
      Parameters:
      eventHandlerContinue -
      Returns:
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshal

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

    • preprocess

      protected void preprocess(InputStream is, boolean eventHandlerContinue) throws jakarta.xml.bind.JAXBException
      Transform the content through mcPreprocessorXslt
      Parameters:
      is -
      eventHandlerContinue -
      Throws:
      jakarta.xml.bind.JAXBException

    • transformToDom

      protected Document transformToDom(XMLStreamReader xsr) throws FactoryConfigurationError, jakarta.xml.bind.JAXBException
      Prepare input by transforming via mcPreprocessorXslt, outputting a DOM node, which we can use docx4jUnmarshallerListener on.
      Parameters:
      xsr -
      Returns:
      Throws:
      FactoryConfigurationError
      jakarta.xml.bind.JAXBException

    • inputStreamToXSR

      protected XMLStreamReader inputStreamToXSR(InputStream is) throws XMLStreamException
      Throws:
      XMLStreamException

    • unmarshal

      public E unmarshal(Element el) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • isContentEqual

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