Package org.docx4j

Class XmlUtils

java.lang.Object
org.docx4j.XmlUtils
public class XmlUtils extends Object

  • Field Details

    • TRANSFORMER_FACTORY_PROCESSOR_XALAN

      public static String TRANSFORMER_FACTORY_PROCESSOR_XALAN

  • Constructor Details

    • XmlUtils

      public XmlUtils()

  • Method Details

    • getTransformerFactory

      public static TransformerFactory getTransformerFactory()
      Since:
      2.8.1

    • getDocumentBuilderFactory

      @Deprecated public static DocumentBuilderFactory getDocumentBuilderFactory()
      Deprecated.
      Since:
      2.8.1 TODO replace the various DocumentBuilderFactory.newInstance() throughout docx4j with a call to this.

    • getNewDocumentBuilder

      public static DocumentBuilder getNewDocumentBuilder()
      Use the suitably configured DocumentBuilderFactory to provide a new instance of DocumentBuilder. Remember that DocumentBuilder is not thread-safe!
      Returns:
      Since:
      3.2.0

    • unwrap

      public static Object unwrap(Object o)
      If an object is wrapped in a JAXBElement, return the object. Warning: be careful with this. If you are copying objects into your document (rather than just reading them), you'll probably want the object to remain wrapped (JAXB usually wraps them for a reason; without the wrapper, you'll (probably?) need an
      Parameters:
      o -
      Returns:

    • JAXBElementDebug

      public static String JAXBElementDebug(jakarta.xml.bind.JAXBElement o)

    • getListItemByQName

      public static jakarta.xml.bind.JAXBElement<?> getListItemByQName(List<jakarta.xml.bind.JAXBElement<?>> list, QName name)
      Parameters:
      list -
      name -
      Returns:
      Since:
      3.2.0

    • unmarshal

      public static Object unmarshal(InputStream is) throws jakarta.xml.bind.JAXBException
      Unmarshal an InputStream as an object in the package org.docx4j.jaxb.document. Note: you should ensure you include a namespace declaration for w: and any other namespace in the xml string. Also, the object you are attempting to unmarshall to might need to have an @XmlRootElement annotation for things to work.
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshal

      public static Object unmarshal(InputStream is, jakarta.xml.bind.JAXBContext jc) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshalString

      public static Object unmarshalString(String str) throws jakarta.xml.bind.JAXBException
      Unmarshal a String as an object in the package org.docx4j.jaxb.document. Note: you should ensure you include a namespace declaration for w: and any other namespace in the xml string. Also, the object you are attempting to unmarshall to might need to have an @XmlRootElement annotation for things to work.
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshalString

      public static Object unmarshalString(String str, jakarta.xml.bind.JAXBContext jc, Class declaredType) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshalString

      public static Object unmarshalString(String str, jakarta.xml.bind.JAXBContext jc) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • handleUnmarshalException

      public static Object handleUnmarshalException(jakarta.xml.bind.JAXBContext jc, JaxbValidationEventHandler eventHandler, Document document, Exception ue) throws jakarta.xml.bind.UnmarshalException, jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.UnmarshalException
      jakarta.xml.bind.JAXBException

    • unmarshal

      public static Object unmarshal(Node n) throws jakarta.xml.bind.JAXBException
      Unmarshal a node using Context.jc, WITHOUT fallback to pre-processing in case of failure.
      Parameters:
      n -
      Returns:
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshal

      public static Object unmarshal(Node n, jakarta.xml.bind.JAXBContext jc, Class declaredType) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshallFromTemplate

      public static Object unmarshallFromTemplate(String wmlTemplateString, Map<String,?> mappings) throws jakarta.xml.bind.JAXBException
      Give a string of wml containing ${key1}, ${key2}, return a suitable object.
      Parameters:
      wmlTemplateString -
      mappings -
      Returns:
      Throws:
      jakarta.xml.bind.JAXBException
      See Also:
      • which can invoke this more efficiently

    • unmarshallFromTemplate

      public static Object unmarshallFromTemplate(String wmlTemplateString, Map<String,?> mappings, jakarta.xml.bind.JAXBContext jc) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • unmarshallFromTemplate

      public static Object unmarshallFromTemplate(String wmlTemplateString, Map<String,?> mappings, jakarta.xml.bind.JAXBContext jc, Class<?> declaredType) throws jakarta.xml.bind.JAXBException
      Throws:
      jakarta.xml.bind.JAXBException

    • marshaltoString

      public static String marshaltoString(Object o)
      Marshal this object to a String, pretty printed, and without an XML declaration. Useful for debugging.
      Parameters:
      o -
      Returns:
      Since:
      3.0.1

    • marshaltoString

      public static String marshaltoString(Object o, jakarta.xml.bind.JAXBContext jc)
      Use the specified JAXBContext to marshal this object to a String, pretty printed, and without an XML declaration. Useful for debugging.
      Parameters:
      o -
      Returns:
      Since:
      3.0.1

    • marshaltoString

      @Deprecated public static String marshaltoString(Object o, boolean suppressDeclaration)
      Deprecated.
      Marshal to a String

    • marshaltoString

      @Deprecated public static String marshaltoString(Object o, boolean suppressDeclaration, jakarta.xml.bind.JAXBContext jc)
      Deprecated.
      Marshal to a String

    • marshaltoString

      public static String marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint)
      Marshal to a String

    • trimNamespaces

      public static byte[] trimNamespaces(Document doc, String ignorables) throws InvalidCanonicalizerException, CanonicalizationException
      Removes superflouous namespaces. It makes things neater, at the cost of some extra processing.
      Throws:
      InvalidCanonicalizerException
      CanonicalizationException

    • marshaltoString

      public static String marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint, jakarta.xml.bind.JAXBContext jc)
      Marshal to a String

    • marshaltoString

      public static String marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint, jakarta.xml.bind.JAXBContext jc, String mcChoiceNamespace)
      Marshal to a String, declaring mcChoiceNamespace
      Since:
      8.3.2

    • marshaltoString

      public static String marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint, jakarta.xml.bind.JAXBContext jc, String uri, String local, Class declaredType)
      Marshal to a String, for object missing an @XmlRootElement annotation

    • marshaltoString

      public static String marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint, jakarta.xml.bind.JAXBContext jc, String uri, String local, Class declaredType, String mcChoiceNamespace)
      Marshal to a String, for object missing an @XmlRootElement annotation, declaring mcChoiceNamespace
      Since:
      8.3.2

    • marshaltoInputStream

      public static InputStream marshaltoInputStream(Object o, boolean suppressDeclaration, jakarta.xml.bind.JAXBContext jc)
      marshaltoInputStream, declaring mcChoiceNamespace

    • marshaltoInputStream

      public static InputStream marshaltoInputStream(Object o, boolean suppressDeclaration, jakarta.xml.bind.JAXBContext jc, String mcChoiceNamespace)
      marshaltoInputStream, declaring mcChoiceNamespace
      Since:
      8.3.2

    • marshaltoW3CDomDocument

      public static Document marshaltoW3CDomDocument(Object o)
      Marshal to a W3C document

    • marshaltoW3CDomDocument

      public static Document marshaltoW3CDomDocument(Object o, jakarta.xml.bind.JAXBContext jc)
      Marshal to a W3C document, declaring mcChoiceNamespace

    • marshaltoW3CDomDocument

      public static Document marshaltoW3CDomDocument(Object o, jakarta.xml.bind.JAXBContext jc, String mcChoiceNamespace)
      Marshal to a W3C document, declaring mcChoiceNamespace
      Since:
      8.3.2

    • marshaltoW3CDomDocument

      public static Document marshaltoW3CDomDocument(Object o, jakarta.xml.bind.JAXBContext jc, String uri, String local, Class declaredType)
      Marshal to a W3C document, for object missing an @XmlRootElement annotation.

    • marshaltoW3CDomDocument

      public static Document marshaltoW3CDomDocument(Object o, jakarta.xml.bind.JAXBContext jc, String uri, String local, Class declaredType, String mcChoiceNamespace)
      Marshal to a W3C document, for object missing an @XmlRootElement annotation, declaring mcChoiceNamespace
      Since:
      8.3.2

    • deepCopy

      public static <T> T deepCopy(T value)
      Clone this JAXB object, using default JAXBContext.

    • deepCopy

      public static <T> T deepCopy(T value, jakarta.xml.bind.JAXBContext jc)
      Clone this JAXB object
      Parameters:
      value -
      jc -
      Returns:

    • w3CDomNodeToString

      public static String w3CDomNodeToString(Node n)

    • w3CDomNodeToOutputStream

      public static void w3CDomNodeToOutputStream(Node n, OutputStream os) throws Docx4JException
      Parameters:
      n -
      os -
      Throws:
      Docx4JException

    • neww3cDomDocument

      public static Document neww3cDomDocument()
      Use DocumentBuilderFactory to create and return a new w3c dom Document.

    • appendXmlFragment

      public static void appendXmlFragment(Document document, Node parent, String fragment) throws IOException, SAXException, ParserConfigurationException
      Parameters:
      docBuilder - the parser
      parent - node to add fragment to
      fragment - a well formed XML fragment
      Throws:
      ParserConfigurationException
      IOException
      SAXException

    • prepareJAXBResult

      public static jakarta.xml.bind.util.JAXBResult prepareJAXBResult(jakarta.xml.bind.JAXBContext context) throws Docx4JException
      Prepare a JAXB transformation result for some given context.
      Parameters:
      context - The JAXB context.
      Returns:
      The result data structure created.
      Throws:
      Docx4JException - In case of configuration errors.

    • transform

      public static void transform(Document doc, Templates template, Map<String,Object> transformParameters, Result result) throws Docx4JException
      Throws:
      Docx4JException

    • getTransformerTemplate

      public static Templates getTransformerTemplate(Source xsltSource) throws TransformerConfigurationException
      Throws:
      TransformerConfigurationException

    • transform

      public static void transform(Source source, Templates template, Map<String,Object> transformParameters, Result result) throws Docx4JException
      Transform an input document using XSLT
      Parameters:
      doc -
      xslt -
      transformParameters -
      result -
      Throws:
      Docx4JException - In case serious transformation errors occur

    • getJAXBNodesViaXPath

      public static List<Object> getJAXBNodesViaXPath(jakarta.xml.bind.Binder<Node> binder, Object jaxbElement, String xpathExpr, boolean refreshXmlFirst) throws jakarta.xml.bind.JAXBException, XPathBinderAssociationIsPartialException
      Fetch JAXB Nodes 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, since 3.0, this method will throw XPathBinderAssociationIsPartialException, to distinguish from no matching elements. 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.
      Parameters:
      binder -
      jaxbElement -
      refreshXmlFirst -
      xpathExpr -
      Returns:
      Throws:
      jakarta.xml.bind.JAXBException
      XPathBinderAssociationIsPartialException

    • getJAXBAssociationsForXPath

      public static List<JAXBAssociation> getJAXBAssociationsForXPath(jakarta.xml.bind.Binder<Node> binder, Object jaxbElement, 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://jaxb.dev.java.net/issues/show_bug.cgi?id=459 So this is left for you to choose to do via the refreshXmlFirst parameter.
      Parameters:
      binder -
      jaxbElement -
      xpathExpr -
      refreshXmlFirst -
      Returns:
      Throws:
      jakarta.xml.bind.JAXBException
      XPathBinderAssociationIsPartialException
      Since:
      3.0.0

    • xpath

      public static List<Node> xpath(Node node, String xpathExpression)

    • xpath

      public static List<Node> xpath(Node node, String xpathExpression, NamespaceContext nsContext)

    • treeCopy

      public static void treeCopy(NodeList sourceNodes, Node destParent)

    • treeCopy

      public static void treeCopy(Node sourceNode, Node destParent)
      Copy a node from one DOM document to another. Used to avoid relying on an underlying implementation which might not support importNode (eg Xalan's org.apache.xml.dtm.ref.DTMNodeProxy). WARNING: doesn't fully support namespaces!
      Parameters:
      sourceNode -
      destParent -