package org.docx4j.openpackaging.parts;
import java.util.List;
import javax.xml.bind.Binder;
import javax.xml.bind.JAXBException;
import org.docx4j.jaxb.JAXBAssociation;
import org.docx4j.jaxb.XPathBinderAssociationIsPartialException;
import org.w3c.dom.Node;
public interface XPathEnabled<E> {
/**
* 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<Node> 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<Object> getJAXBNodesViaXPath(String xpathExpr, boolean refreshXmlFirst)
throws 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://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 someJaxbElement
* @param refreshXmlFirst
* @return
* @throws JAXBException
* @throws XPathBinderAssociationIsPartialException
*/
public List<Object> getJAXBNodesViaXPath(String xpathExpr, Object someJaxbElement, boolean refreshXmlFirst)
throws 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://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 binder
* @param jaxbElement
* @param xpathExpr
* @param refreshXmlFirst
* @return
* @throws JAXBException
* @throws XPathBinderAssociationIsPartialException
* @since 3.0.0
*/
public List<JAXBAssociation> getJAXBAssociationsForXPath(
String xpathExpr, boolean refreshXmlFirst)
throws 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.
*
* @param binder
* @param jaxbElement
* @param xpathExpr
* @param refreshXmlFirst
* @return
* @throws JAXBException
* @throws XPathBinderAssociationIsPartialException
* @since 3.0.0
*/
public List<JAXBAssociation> getJAXBAssociationsForXPath(
Object someJaxbElement, String xpathExpr, boolean refreshXmlFirst)
throws JAXBException, XPathBinderAssociationIsPartialException;
}