org.docx4j.openpackaging.parts.XPathEnabled Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of docx4j-core Show documentation

docx4j is a library which helps you to work with the Office Open XML file format as used in docx documents, pptx presentations, and xlsx spreadsheets.

There is a newer version: 11.4.11

Show newest version

package org.docx4j.openpackaging.parts;

import java.util.List;

import jakarta.xml.bind.Binder;
import jakarta.xml.bind.JAXBException;

import org.docx4j.jaxb.JAXBAssociation;
import org.docx4j.jaxb.XPathBinderAssociationIsPartialException;
import org.w3c.dom.Node;

public interface XPathEnabled {
	
	/**
	 * 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.
	 */
	public Binder getBinder();

	/* Don't override setJaxbElement(E jaxbElement) to create	  	
	 * binder here, since that would set the
	 * jaxbElement field to something different to
	 * the object being passed in, leading to
	 * calling code doing something different to what it thinks it 
	 * is doing! (ie backwards compatibility would be broken).
	 * 
	 * That's why we have this new method createBinderAndJaxbElement
	 */
	
	/**
	 * 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!
	 * @param source
	 * @return
	 * @throws JAXBException
	 * @since 3.0.0
	 */
	public E createBinderAndJaxbElement(E source) throws JAXBException;
	
	/**
	 * 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://jaxb.dev.java.net/issues/show_bug.cgi?id=459
	 * 
	 * So this is left for you to choose to do via the refreshXmlFirst parameter.   
	 * 
	 * @param xpathExpr
	 * @param refreshXmlFirst
	 * @return
	 * @throws JAXBException
	 * @throws XPathBinderAssociationIsPartialException 
	 */	
	public List