org.docx4j

Class XmlUtils

java.lang.Object

org.docx4j.XmlUtils

public class XmlUtils
extends Object

Field Summary

Fields

Modifier and Type	Field and Description
static String	TRANSFORMER_FACTORY_PROCESSOR_XALAN

Constructor Summary

Constructors

Constructor and Description
XmlUtils()

Method Summary

Modifier and Type	Method and Description
static void	appendXmlFragment(Document document, Node parent, String fragment)
static <T> T	deepCopy(T value) Clone this JAXB object, using default JAXBContext.
static <T> T	deepCopy(T value, JAXBContext jc) Clone this JAXB object
static DocumentBuilderFactory	getDocumentBuilderFactory() Deprecated.
static List<JAXBAssociation>	getJAXBAssociationsForXPath(Binder<Node> binder, Object jaxbElement, String xpathExpr, boolean refreshXmlFirst) Fetch DOM node / JAXB object pairs matching an XPath (for example "//w:p").
static List<Object>	getJAXBNodesViaXPath(Binder<Node> binder, Object jaxbElement, String xpathExpr, boolean refreshXmlFirst) Fetch JAXB Nodes matching an XPath (for example "//w:p").
static JAXBElement<?>	getListItemByQName(List<JAXBElement<?>> list, QName name)
static DocumentBuilder	getNewDocumentBuilder() Use the suitably configured DocumentBuilderFactory to provide a new instance of DocumentBuilder.
static TransformerFactory	getTransformerFactory()
static Templates	getTransformerTemplate(Source xsltSource)
static String	JAXBElementDebug(JAXBElement o)
static InputStream	marshaltoInputStream(Object o, boolean suppressDeclaration, JAXBContext jc)
static String	marshaltoString(Object o) Marshal this object to a String, pretty printed, and without an XML declaration.
static String	marshaltoString(Object o, boolean suppressDeclaration) Deprecated.
static String	marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint) Marshal to a String
static String	marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint, JAXBContext jc) Marshal to a String
static String	marshaltoString(Object o, boolean suppressDeclaration, boolean prettyprint, JAXBContext jc, String uri, String local, Class declaredType) Marshal to a String, for object missing an @XmlRootElement annotation.
static String	marshaltoString(Object o, boolean suppressDeclaration, JAXBContext jc) Deprecated.
static String	marshaltoString(Object o, JAXBContext jc) Use the specified JAXBContext to marshal this object to a String, pretty printed, and without an XML declaration.
static Document	marshaltoW3CDomDocument(Object o) Marshal to a W3C document
static Document	marshaltoW3CDomDocument(Object o, JAXBContext jc) Marshal to a W3C document
static Document	marshaltoW3CDomDocument(Object o, JAXBContext jc, String uri, String local, Class declaredType) Marshal to a W3C document, for object missing an @XmlRootElement annotation.
static Document	neww3cDomDocument() Use DocumentBuilderFactory to create and return a new w3c dom Document.
static JAXBResult	prepareJAXBResult(JAXBContext context) Prepare a JAXB transformation result for some given context.
static void	transform(Document doc, Templates template, Map<String,Object> transformParameters, Result result)
static void	transform(Source source, Templates template, Map<String,Object> transformParameters, Result result) Transform an input document using XSLT
static void	treeCopy(NodeList sourceNodes, Node destParent)
static void	treeCopy(Node sourceNode, Node destParent) Copy a node from one DOM document to another.
static byte[]	trimNamespaces(Document doc, String ignorables) Removes superflouous namespaces.
static Object	unmarshal(InputStream is) Unmarshal an InputStream as an object in the package org.docx4j.jaxb.document.
static Object	unmarshal(InputStream is, JAXBContext jc)
static Object	unmarshal(Node n) Unmarshal a node using Context.jc, WITHOUT fallback to pre-processing in case of failure.
static Object	unmarshal(Node n, JAXBContext jc, Class declaredType)
static Object	unmarshallFromTemplate(String wmlTemplateString, Map<String,?> mappings) Give a string of wml containing ${key1}, ${key2}, return a suitable object.
static Object	unmarshallFromTemplate(String wmlTemplateString, Map<String,?> mappings, JAXBContext jc)
static Object	unmarshallFromTemplate(String wmlTemplateString, Map<String,?> mappings, JAXBContext jc, Class<?> declaredType)
static Object	unmarshalString(String str) Unmarshal a String as an object in the package org.docx4j.jaxb.document.
static Object	unmarshalString(String str, JAXBContext jc)
static Object	unmarshalString(String str, JAXBContext jc, Class declaredType)
static Object	unwrap(Object o) If an object is wrapped in a JAXBElement, return the object.
static void	w3CDomNodeToOutputStream(Node n, OutputStream os)
static String	w3CDomNodeToString(Node n)
static List<Node>	xpath(Node node, String xpathExpression)
static List<Node>	xpath(Node node, String xpathExpression, NamespaceContext nsContext)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TRANSFORMER_FACTORY_PROCESSOR_XALAN

public static String TRANSFORMER_FACTORY_PROCESSOR_XALAN

Constructor Detail

XmlUtils

public XmlUtils()

Method Detail

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(JAXBElement o)

getListItemByQName

public static JAXBElement<?> getListItemByQName(List<JAXBElement<?>> list,
                                                QName name)

Parameters:

list -

name -

Returns:

Since:

3.2.0

unmarshal

public static Object unmarshal(InputStream is)
                        throws 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:

JAXBException

unmarshal

public static Object unmarshal(InputStream is,
                               JAXBContext jc)
                        throws JAXBException

Throws:

JAXBException

unmarshalString

public static Object unmarshalString(String str)
                              throws 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:

JAXBException

unmarshalString

public static Object unmarshalString(String str,
                                     JAXBContext jc,
                                     Class declaredType)
                              throws JAXBException

Throws:

JAXBException

unmarshalString

public static Object unmarshalString(String str,
                                     JAXBContext jc)
                              throws JAXBException

Throws:

JAXBException

unmarshal

public static Object unmarshal(Node n)
                        throws JAXBException

Unmarshal a node using Context.jc, WITHOUT fallback to pre-processing in case of failure.

Parameters:

n -

Returns:

Throws:

JAXBException

unmarshal

public static Object unmarshal(Node n,
                               JAXBContext jc,
                               Class declaredType)
                        throws JAXBException

Throws:

JAXBException

unmarshallFromTemplate

public static Object unmarshallFromTemplate(String wmlTemplateString,
                                            Map<String,?> mappings)
                                     throws JAXBException

Give a string of wml containing ${key1}, ${key2}, return a suitable object.

Parameters:

wmlTemplateString -

mappings -

Returns:

Throws:

JAXBException

See Also:

which can invoke this more efficiently

unmarshallFromTemplate

public static Object unmarshallFromTemplate(String wmlTemplateString,
                                            Map<String,?> mappings,
                                            JAXBContext jc)
                                     throws JAXBException

Throws:

JAXBException

unmarshallFromTemplate

public static Object unmarshallFromTemplate(String wmlTemplateString,
                                            Map<String,?> mappings,
                                            JAXBContext jc,
                                            Class<?> declaredType)
                                     throws JAXBException

Throws:

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,
                                     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,
                                                 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,
                                     JAXBContext jc)

Marshal to a String

marshaltoString

public static String marshaltoString(Object o,
                                     boolean suppressDeclaration,
                                     boolean prettyprint,
                                     JAXBContext jc,
                                     String uri,
                                     String local,
                                     Class declaredType)

Marshal to a String, for object missing an @XmlRootElement annotation.

marshaltoInputStream

public static InputStream marshaltoInputStream(Object o,
                                               boolean suppressDeclaration,
                                               JAXBContext jc)

marshaltoW3CDomDocument

public static Document marshaltoW3CDomDocument(Object o)

Marshal to a W3C document

marshaltoW3CDomDocument

public static Document marshaltoW3CDomDocument(Object o,
                                               JAXBContext jc)

Marshal to a W3C document

marshaltoW3CDomDocument

public static Document marshaltoW3CDomDocument(Object o,
                                               JAXBContext jc,
                                               String uri,
                                               String local,
                                               Class declaredType)

Marshal to a W3C document, for object missing an @XmlRootElement annotation.

deepCopy

public static <T> T deepCopy(T value)

Clone this JAXB object, using default JAXBContext.

deepCopy

public static <T> T deepCopy(T value,
                             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 JAXBResult prepareJAXBResult(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(Binder<Node> binder,
                                                Object jaxbElement,
                                                String xpathExpr,
                                                boolean refreshXmlFirst)
                                         throws 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:

JAXBException

XPathBinderAssociationIsPartialException

getJAXBAssociationsForXPath

public static List<JAXBAssociation> getJAXBAssociationsForXPath(Binder<Node> binder,
                                                                Object jaxbElement,
                                                                String xpathExpr,
                                                                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.

Parameters:

binder -

jaxbElement -

xpathExpr -

refreshXmlFirst -

Returns:

Throws:

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 -