Package org.docx4j.openpackaging.parts

Class CustomXmlDataStoragePart

java.lang.Object
org.docx4j.openpackaging.Base
org.docx4j.openpackaging.parts.Part
org.docx4j.openpackaging.parts.CustomXmlDataStoragePart
All Implemented Interfaces:
CustomXmlPart
public final class CustomXmlDataStoragePart
extends Part
implements CustomXmlPart
CustomXmlDataStoragePart contains user custom xml, to which content control bindings can point. This is the modern best practice approach for injecting text/data into a docx. See the Getting Started guide for a general overview, and additional references, or use the docx4j website to search for "custom xml binding". Once you have included this part, and bound content controls to it, nothing further needs to be done for Word to display your data (unless you are using conditional|repeat - see below). However, if you want your data to show up in docx4j PDF|HTML output, you need to run the BindingHandler.applyBindings method first. (TODO: do this automatically) The actual XML data is stored in a CustomXmlDataStorage object, for which accessor is get|setData. (Ths is useful if you want to generate n docx documents, each with different XML.) If this contains XML which is bound in an sdt via w:sdtPr/w:dataBinding, then its rels will point to CustomXmlDataStoragePropertiesPart which gives its datastore itemID. (The datastore itemID is used in the w:dataBinding) The Package contains a hashmap to make it easy to get the part to which we apply the XPath. The part is registered as the document is loaded. This class supports content control extensions (ie od:condition, od:repeat). Use the OpenDoPEHandler class to process these.
Author:
jharrop

  • Constructor Details

  • Method Details

    • init

      public void init()

    • getData

      public CustomXmlDataStorage getData()
      Returns:
      the data

    • setData

      public void setData​(CustomXmlDataStorage data)
      Parameters:
      data - the data to set

    • isContentEqual

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

    • xpathGetString

      public java.lang.String xpathGetString​(java.lang.String xpath, java.lang.String prefixMappings) throws Docx4JException
      Specified by:
      xpathGetString in interface CustomXmlPart
      Throws:
      Docx4JException

    • cachedXPathGetString

      public java.lang.String cachedXPathGetString​(java.lang.String xpath, java.lang.String prefixMappings) throws Docx4JException
      Description copied from interface: CustomXmlPart
      Use org.apache.xpath.CachedXPathAPI, since this is much quicker than default javax.xml.xpath.XPath implementations (Apache's anyway) for large XML files. This is because Apache's old XPathAPI class instantiated a new XPathContext (and thus building a new DTMManager, and new DTMs) each time it was called. XPathAPIObject instead retains its context as long as the object persists, reusing the DTMs. There was the question of whether to declare it here or just implement it in CustomXmlDataStoragePart (since this is mostly of value in binding the user's XML data file). It is here since otherwise BindingHandler would fail on DocPropsCoverPagePart and StandardisedAnswersPart (both of which extend JaxbCustomXmlDataStoragePart).
      Specified by:
      cachedXPathGetString in interface CustomXmlPart
      Returns:
      Throws:
      Docx4JException
      Since:
      3.3.1
      See Also:
      CustomXmlPart.discardCacheXPathObject()

    • discardCacheXPathObject

      public void discardCacheXPathObject()
      Description copied from interface: CustomXmlPart
      Use this to null out the org.apache.xpath.CachedXPathAPI object, which you should do if you've changed your source document, or want to reclaim memory.
      Specified by:
      discardCacheXPathObject in interface CustomXmlPart

    • xpathGetNodes

      public java.util.List<org.w3c.dom.Node> xpathGetNodes​(java.lang.String xpathString, java.lang.String prefixMappings) throws Docx4JException
      Specified by:
      xpathGetNodes in interface CustomXmlPart
      Throws:
      Docx4JException

    • setNodeValueAtXPath

      public boolean setNodeValueAtXPath​(java.lang.String xpath, java.lang.String value, java.lang.String prefixMappings) throws Docx4JException
      Specified by:
      setNodeValueAtXPath in interface CustomXmlPart
      Throws:
      Docx4JException

    • getXML

      public java.lang.String getXML() throws Docx4JException
      Get the XML as a String.
      Specified by:
      getXML in interface CustomXmlPart
      Throws:
      Docx4JException
      Since:
      3.0.1

    • setXML

      public void setXML​(org.w3c.dom.Document xmlDocument) throws Docx4JException
      Set the XML
      Specified by:
      setXML in interface CustomXmlPart
      Throws:
      Docx4JException
      Since:
      6.0.0

    • getItemId

      public java.lang.String getItemId()
      Specified by:
      getItemId in interface CustomXmlPart
      Since:
      3.0.2

    • remove

      public void remove()
      Remove this part from the pkg. Beware: it is up to you to make sure your content doesn't rely on this part being present! A symptom of that would be that Office now reports your file to be corrupt or in need of repair.
      Overrides:
      remove in class Part
      Since:
      3.0.2