Package org.docx4j.openpackaging.parts

Class JaxbXmlPartXPathAware<E>

java.lang.Object

org.docx4j.openpackaging.Base

org.docx4j.openpackaging.parts.Part

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

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

All Implemented Interfaces:

XPathEnabled<E>

Direct Known Subclasses:

CommentsPart, DocumentSettingsPart, EndnotesPart, FootnotesPart, JaxbDmlPart, JaxbPmlPart, JaxbSmlPart, JaxbXmlPartAltChunkHost, NumberingDefinitionsPart, StyleDefinitionsPart, ThemeOverridePart, ThemePart, VMLPart

public abstract class JaxbXmlPartXPathAware<E>
extends JaxbXmlPart<E>
implements XPathEnabled<E>

Since:

2.8

Author:

jharrop

Field Summary

Fields

Modifier and Type	Field	Description
protected jakarta.xml.bind.Binder<Node>	binder
protected static org.slf4j.Logger	log

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

jaxbElement, jc, 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	Description
JaxbXmlPartXPathAware(PartName partName)

Method Summary

Modifier and Type	Method	Description
E	createBinderAndJaxbElement(E source)	Set the JAXBElement for this part, and a corresponding binder, based on the object provided.
jakarta.xml.bind.Binder<Node>	getBinder()	Enables synchronization between XML infoset nodes and JAXB objects representing same XML document.
List<JAXBAssociation>	getJAXBAssociationsForXPath(Object someJaxbElement, String xpathExpr, boolean refreshXmlFirst)	Fetch DOM node / JAXB object pairs matching an XPath (for example ".//w:p" - note the dot, which is necessary for this sort of relative path).
List<JAXBAssociation>	getJAXBAssociationsForXPath(String xpathExpr, boolean refreshXmlFirst)	Fetch DOM node / JAXB object pairs matching an XPath (for example "//w:p").
List<Object>	getJAXBNodesViaXPath(String xpathExpr, boolean refreshXmlFirst)	Fetch JAXB Nodes matching an XPath (for example "//w:p").
List<Object>	getJAXBNodesViaXPath(String xpathExpr, Object someJaxbElement, boolean refreshXmlFirst)	Fetch JAXB Nodes matching an XPath (for example ".//w:p" - note the dot, which is necessary for this sort of relative path).
void	setJaxbElement(E jaxbElement)	You can't use this override to create/update a binder, since this would set the jaxbElement field to something different to the object being passed in (as a consequence of the process to create a binder).
E	unmarshal(InputStream is)	Unmarshal XML data from the specified InputStream and return the resulting content tree.
E	unmarshal(Element el)

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

addMcChoiceNamespace, getConfiguredUnmarshaller, getContents, getJAXBContext, getJaxbElement, getMcChoiceNamespaces, getMceIgnorable, getXML, inputStreamToXSR, isContentEqual, isUnmarshalled, marshal, marshal, marshal, marshal, pipe, pipe, pipe, preprocess, setContents, setJAXBContext, setJaxbElement, setMceIgnorable, transform, transformToDom, variableReplace

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 Details

log

protected static org.slf4j.Logger log

binder

protected jakarta.xml.bind.Binder<Node> binder

Constructor Details

JaxbXmlPartXPathAware

public JaxbXmlPartXPathAware(PartName partName)
                      throws InvalidFormatException

Throws:

InvalidFormatException

Method Details

getBinder

public jakarta.xml.bind.Binder<Node> getBinder()

Enables synchronization between XML infoset nodes and JAXB objects representing same XML document. An instance of this class maintains the association between XML nodes of an infoset preserving view and a JAXB representation of an XML document. Navigation between the two views is provided by the methods getXMLNode(Object) and getJAXBNode(Object) . In theory, modifications can be made to either the infoset preserving view or the JAXB representation of the document while the other view remains unmodified. The binder ought to be able to synchronize the changes made in the modified view back into the other view using the appropriate Binder update methods, #updateXML(Object, Object) or #updateJAXB(Object). But JAXB doesn't currently work as advertised .. access to this object is offered for advanced users on an experimental basis only.

Specified by:

getBinder in interface XPathEnabled<E>

setJaxbElement

public void setJaxbElement(E jaxbElement)

You can't use this override to create/update a binder, since this would set the jaxbElement field to something different to the object being passed in (as a consequence of the process to create a binder). We don't want that, because calling code may then continue to manipulate the field, without effect.. See instead createBinderAndJaxbElement

Overrides:

setJaxbElement in class JaxbXmlPart<E>

createBinderAndJaxbElement

public E createBinderAndJaxbElement(E source)
                             throws jakarta.xml.bind.JAXBException

Set the JAXBElement for this part, and a corresponding binder, based on the object provided. Returns the new JAXBElement, so calling code can manipulate it. Beware that this object is different to the one passed in!

Specified by:

createBinderAndJaxbElement in interface XPathEnabled<E>

Parameters:

source -

Returns:

Throws:

jakarta.xml.bind.JAXBException

Since:

3.0.0

getJAXBNodesViaXPath

public List<Object> getJAXBNodesViaXPath(String xpathExpr,
 boolean refreshXmlFirst)
                                  throws jakarta.xml.bind.JAXBException,
XPathBinderAssociationIsPartialException

Fetch JAXB Nodes matching an XPath (for example "//w:p"). If you have modified your JAXB objects (eg added or changed a w:p paragraph), you need to update the association. The problem is that this can only be done ONCE, owing to a bug in JAXB: see https://github.com/javaee/jaxb-v2/issues/459 So this is left for you to choose to do via the refreshXmlFirst parameter.

Specified by:

getJAXBNodesViaXPath in interface XPathEnabled<E>

Parameters:

xpathExpr -

refreshXmlFirst -

Returns:

Throws:

jakarta.xml.bind.JAXBException

XPathBinderAssociationIsPartialException

getJAXBNodesViaXPath

public List<Object> getJAXBNodesViaXPath(String xpathExpr,
 Object someJaxbElement,
 boolean refreshXmlFirst)
                                  throws jakarta.xml.bind.JAXBException,
XPathBinderAssociationIsPartialException

Fetch JAXB Nodes matching an XPath (for example ".//w:p" - note the dot, which is necessary for this sort of relative path). If you have modified your JAXB objects (eg added or changed a w:p paragraph), you need to update the association. The problem is that this can only be done ONCE, owing to a bug in JAXB: see https://github.com/javaee/jaxb-v2/issues/459 So this is left for you to choose to do via the refreshXmlFirst parameter.

Specified by:

getJAXBNodesViaXPath in interface XPathEnabled<E>

Parameters:

xpathExpr -

someJaxbElement -

refreshXmlFirst -

Returns:

Throws:

jakarta.xml.bind.JAXBException

XPathBinderAssociationIsPartialException

getJAXBAssociationsForXPath

public List<JAXBAssociation> getJAXBAssociationsForXPath(String xpathExpr,
 boolean refreshXmlFirst)
                                                  throws jakarta.xml.bind.JAXBException,
XPathBinderAssociationIsPartialException

Fetch DOM node / JAXB object pairs matching an XPath (for example "//w:p"). In JAXB, this association is partial; not all XML elements have associated JAXB objects, and not all JAXB objects have associated XML elements. If the XPath returns an element which isn't associated with a JAXB object, the element's pair will be null. If you have modified your JAXB objects (eg added or changed a w:p paragraph), you need to update the association. The problem is that this can only be done ONCE, owing to a bug in JAXB: see https://github.com/javaee/jaxb-v2/issues/459 So this is left for you to choose to do via the refreshXmlFirst parameter.

Specified by:

getJAXBAssociationsForXPath in interface XPathEnabled<E>

Parameters:

binder -

jaxbElement -

xpathExpr -

refreshXmlFirst -

Returns:

Throws:

jakarta.xml.bind.JAXBException

XPathBinderAssociationIsPartialException

Since:

3.0.0

getJAXBAssociationsForXPath

public List<JAXBAssociation> getJAXBAssociationsForXPath(Object someJaxbElement,
 String xpathExpr,
 boolean refreshXmlFirst)
                                                  throws jakarta.xml.bind.JAXBException,
XPathBinderAssociationIsPartialException

Fetch DOM node / JAXB object pairs matching an XPath (for example ".//w:p" - note the dot, which is necessary for this sort of relative path). In JAXB, this association is partial; not all XML elements have associated JAXB objects, and not all JAXB objects have associated XML elements. If the XPath returns an element which isn't associated with a JAXB object, the element's pair will be null. If you have modified your JAXB objects (eg added or changed a w:p paragraph), you need to update the association. The problem is that this can only be done ONCE, owing to a bug in JAXB: see https://jaxb.dev.java.net/issues/show_bug.cgi?id=459 So this is left for you to choose to do via the refreshXmlFirst parameter.

Specified by:

getJAXBAssociationsForXPath in interface XPathEnabled<E>

Parameters:

binder -

jaxbElement -

xpathExpr -

refreshXmlFirst -

Returns:

Throws:

jakarta.xml.bind.JAXBException

XPathBinderAssociationIsPartialException

Since:

3.0.0

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.

Overrides:

unmarshal in class JaxbXmlPart<E>

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

unmarshal

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

Overrides:

unmarshal in class JaxbXmlPart<E>

Throws:

jakarta.xml.bind.JAXBException

Since:

2.7.1