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

Field Summary

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
CustomXmlDataStoragePart()
CustomXmlDataStoragePart(PartName partName)
CustomXmlDataStoragePart(Parts parts) Deprecated.

Method Summary

Modifier and Type	Method and Description
String	cachedXPathGetString(String xpath, String prefixMappings) Use org.apache.xpath.CachedXPathAPI, since this is much quicker than default javax.xml.xpath.XPath implementations (Apache's anyway) for large XML files.
void	discardCacheXPathObject() 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.
CustomXmlDataStorage	getData()
String	getItemId()
String	getXML() Get the XML as a String.
void	init()
boolean	isContentEqual(Part other)
void	remove() Remove this part from the pkg.
void	setData(CustomXmlDataStorage data)
boolean	setNodeValueAtXPath(String xpath, String value, String prefixMappings)
void	setXML(Document xmlDocument) Set the XML
List<Node>	xpathGetNodes(String xpathString, String prefixMappings)
String	xpathGetString(String xpath, String prefixMappings)

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

getContentLengthAsLoaded, getOwningRelationshipPart, getPackage, getRelationshipType, getSourceRelationship, getSourceRelationships, getVersion, 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

Constructor Detail

CustomXmlDataStoragePart

public CustomXmlDataStoragePart(PartName partName)
                         throws InvalidFormatException

Throws:

InvalidFormatException

CustomXmlDataStoragePart

public CustomXmlDataStoragePart()
                         throws InvalidFormatException

Throws:

InvalidFormatException

CustomXmlDataStoragePart

@Deprecated
public CustomXmlDataStoragePart(Parts parts)
                                     throws InvalidFormatException

Deprecated.

Parameters:

parts - The parts present in the package to which this will be added. If for example /customXml/item1.xml already exists, this allows the name /customXml/item2.xml to be generated.

Throws:

InvalidFormatException

Method Detail

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 String xpathGetString(String xpath,
                             String prefixMappings)
                      throws Docx4JException

Specified by:

xpathGetString in interface CustomXmlPart

Throws:

Docx4JException

cachedXPathGetString

public String cachedXPathGetString(String xpath,
                                   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:

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 List<Node> xpathGetNodes(String xpathString,
                                String prefixMappings)
                         throws Docx4JException

Specified by:

xpathGetNodes in interface CustomXmlPart

Throws:

Docx4JException

setNodeValueAtXPath

public boolean setNodeValueAtXPath(String xpath,
                                   String value,
                                   String prefixMappings)
                            throws Docx4JException

Specified by:

setNodeValueAtXPath in interface CustomXmlPart

Throws:

Docx4JException

getXML

public 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(Document xmlDocument)
            throws Docx4JException

Set the XML

Specified by:

setXML in interface CustomXmlPart

Throws:

Docx4JException

Since:

6.0.0

getItemId

public 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