com.aspose.words
Class XmlMapping

java.lang.Object
    extended by com.aspose.words.XmlMapping
All Implemented Interfaces:
java.lang.Cloneable

public class XmlMapping 
extends java.lang.Object

Specifies the information that is used to establish a mapping between the parent structured document tag and an XML element stored within a custom XML data part in the document.

Example:

Shows how to set XML mappings for CustomXmlParts.
Document doc = new Document();

// Construct an XML part that contains data and add it to the document's CustomXmlPart collection
String xmlPartId = UUID.randomUUID().toString();
String xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>";
CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);
System.out.println(xmlPart.getData());

// Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);

// If we set a mapping for our StructuredDocumentTag,
// it will only display a part of the CustomXmlPart that the XPath points to
// This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart
sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[2]", "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

Assert.assertTrue(sdt.getXmlMapping().isMapped());
Assert.assertEquals(sdt.getXmlMapping().getCustomXmlPart(), xmlPart);
Assert.assertEquals(sdt.getXmlMapping().getXPath(), "/root[1]/text[2]");
Assert.assertEquals(sdt.getXmlMapping().getPrefixMappings(), "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

// Add the StructuredDocumentTag to the document to display the content from our CustomXmlPart
doc.getFirstSection().getBody().appendChild(sdt);
doc.save(getArtifactsDir() + "SDT.XmlMapping.docx");

Property Getters/Setters Summary
CustomXmlPartgetCustomXmlPart()
           Returns the custom XML data part to which the parent structured document tag is mapped.
booleanisMapped()
           Returns true if the parent structured document tag is successfully mapped to XML data.
java.lang.StringgetPrefixMappings()
           Returns XML namespace prefix mappings to evaluate the XPath.
java.lang.StringgetStoreItemId()
           Specifies the custom XML data identifier for the custom XML data part which shall be used to evaluate the XPath expression.
java.lang.StringgetXPath()
           Returns the XPath expression, which is evaluated to find the custom XML node that is mapped to the parent structured document tag.
 
Method Summary
voiddelete()
           Deletes mapping of the parent structured document to XML data.
booleansetMapping(CustomXmlPart customXmlPart, java.lang.String xPath, java.lang.String prefixMapping)
           Sets a mapping between the parent structured document tag and an XML node of a custom XML data part.
 

Property Getters/Setters Detail

getCustomXmlPart

public CustomXmlPart getCustomXmlPart()
Returns the custom XML data part to which the parent structured document tag is mapped.

Example:

Shows how to set XML mappings for CustomXmlParts.
Document doc = new Document();

// Construct an XML part that contains data and add it to the document's CustomXmlPart collection
String xmlPartId = UUID.randomUUID().toString();
String xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>";
CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);
System.out.println(xmlPart.getData());

// Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);

// If we set a mapping for our StructuredDocumentTag,
// it will only display a part of the CustomXmlPart that the XPath points to
// This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart
sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[2]", "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

Assert.assertTrue(sdt.getXmlMapping().isMapped());
Assert.assertEquals(sdt.getXmlMapping().getCustomXmlPart(), xmlPart);
Assert.assertEquals(sdt.getXmlMapping().getXPath(), "/root[1]/text[2]");
Assert.assertEquals(sdt.getXmlMapping().getPrefixMappings(), "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

// Add the StructuredDocumentTag to the document to display the content from our CustomXmlPart
doc.getFirstSection().getBody().appendChild(sdt);
doc.save(getArtifactsDir() + "SDT.XmlMapping.docx");

isMapped

public boolean isMapped()
Returns true if the parent structured document tag is successfully mapped to XML data.

Example:

Shows how to set XML mappings for CustomXmlParts.
Document doc = new Document();

// Construct an XML part that contains data and add it to the document's CustomXmlPart collection
String xmlPartId = UUID.randomUUID().toString();
String xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>";
CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);
System.out.println(xmlPart.getData());

// Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);

// If we set a mapping for our StructuredDocumentTag,
// it will only display a part of the CustomXmlPart that the XPath points to
// This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart
sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[2]", "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

Assert.assertTrue(sdt.getXmlMapping().isMapped());
Assert.assertEquals(sdt.getXmlMapping().getCustomXmlPart(), xmlPart);
Assert.assertEquals(sdt.getXmlMapping().getXPath(), "/root[1]/text[2]");
Assert.assertEquals(sdt.getXmlMapping().getPrefixMappings(), "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

// Add the StructuredDocumentTag to the document to display the content from our CustomXmlPart
doc.getFirstSection().getBody().appendChild(sdt);
doc.save(getArtifactsDir() + "SDT.XmlMapping.docx");

getPrefixMappings

public java.lang.String getPrefixMappings()
Returns XML namespace prefix mappings to evaluate the XPath. Specifies the set of prefix mappings, which shall be used to interpret the XPath expression when the XPath expression is evaluated against the custom XML data parts in the document.

Example:

Shows how to set XML mappings for CustomXmlParts.
Document doc = new Document();

// Construct an XML part that contains data and add it to the document's CustomXmlPart collection
String xmlPartId = UUID.randomUUID().toString();
String xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>";
CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);
System.out.println(xmlPart.getData());

// Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);

// If we set a mapping for our StructuredDocumentTag,
// it will only display a part of the CustomXmlPart that the XPath points to
// This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart
sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[2]", "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

Assert.assertTrue(sdt.getXmlMapping().isMapped());
Assert.assertEquals(sdt.getXmlMapping().getCustomXmlPart(), xmlPart);
Assert.assertEquals(sdt.getXmlMapping().getXPath(), "/root[1]/text[2]");
Assert.assertEquals(sdt.getXmlMapping().getPrefixMappings(), "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

// Add the StructuredDocumentTag to the document to display the content from our CustomXmlPart
doc.getFirstSection().getBody().appendChild(sdt);
doc.save(getArtifactsDir() + "SDT.XmlMapping.docx");

getStoreItemId

public java.lang.String getStoreItemId()
Specifies the custom XML data identifier for the custom XML data part which shall be used to evaluate the XPath expression.

Example:

Shows how to get special id of your xml part.
Document doc = new Document(getMyDir() + "SDT.CustomXml.docx");

StructuredDocumentTag sdt = (StructuredDocumentTag) doc.getChild(NodeType.STRUCTURED_DOCUMENT_TAG, 0, true);
System.out.println("The Id of your custom xml part is: " + sdt.getXmlMapping().getStoreItemId());

getXPath

public java.lang.String getXPath()
Returns the XPath expression, which is evaluated to find the custom XML node that is mapped to the parent structured document tag.

Example:

Shows how to set XML mappings for CustomXmlParts.
Document doc = new Document();

// Construct an XML part that contains data and add it to the document's CustomXmlPart collection
String xmlPartId = UUID.randomUUID().toString();
String xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>";
CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);
System.out.println(xmlPart.getData());

// Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);

// If we set a mapping for our StructuredDocumentTag,
// it will only display a part of the CustomXmlPart that the XPath points to
// This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart
sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[2]", "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

Assert.assertTrue(sdt.getXmlMapping().isMapped());
Assert.assertEquals(sdt.getXmlMapping().getCustomXmlPart(), xmlPart);
Assert.assertEquals(sdt.getXmlMapping().getXPath(), "/root[1]/text[2]");
Assert.assertEquals(sdt.getXmlMapping().getPrefixMappings(), "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

// Add the StructuredDocumentTag to the document to display the content from our CustomXmlPart
doc.getFirstSection().getBody().appendChild(sdt);
doc.save(getArtifactsDir() + "SDT.XmlMapping.docx");

Method Detail

delete

public void delete()
Deletes mapping of the parent structured document to XML data.

Example:

Shows how to set XML mappings for CustomXmlParts.
Document doc = new Document();

// Construct an XML part that contains data and add it to the document's CustomXmlPart collection
String xmlPartId = UUID.randomUUID().toString();
String xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>";
CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);
System.out.println(xmlPart.getData());

// Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);

// If we set a mapping for our StructuredDocumentTag,
// it will only display a part of the CustomXmlPart that the XPath points to
// This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart
sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[2]", "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

Assert.assertTrue(sdt.getXmlMapping().isMapped());
Assert.assertEquals(sdt.getXmlMapping().getCustomXmlPart(), xmlPart);
Assert.assertEquals(sdt.getXmlMapping().getXPath(), "/root[1]/text[2]");
Assert.assertEquals(sdt.getXmlMapping().getPrefixMappings(), "xmlns:ns='http://www.w3.org/2001/XMLSchema'");

// Add the StructuredDocumentTag to the document to display the content from our CustomXmlPart
doc.getFirstSection().getBody().appendChild(sdt);
doc.save(getArtifactsDir() + "SDT.XmlMapping.docx");

setMapping

public boolean setMapping(CustomXmlPart customXmlPart, java.lang.String xPath, java.lang.String prefixMapping)
                  throws java.lang.Exception
Sets a mapping between the parent structured document tag and an XML node of a custom XML data part.
Parameters:
customXmlPart - A custom XML data part to map to.
xPath - An XPath expression to find the XML node.
prefixMapping - XML namespace prefix mappings to evaluate the XPath.
Returns:
A flag indicating whether the parent structured document tag is successfully mapped to the XML node.

Example:

Shows how to create structured document tag with a custom XML data.
Document doc = new Document();

// Construct an XML part that contains data and add it to the document's collection
// Once the "Developer" tab in Mircosoft Word is enabled,
// we can find elements from this collection as well as a couple defaults in the "XML Mapping Pane"
String xmlPartId = UUID.randomUUID().toString();
String xmlPartContent = "<root><text>Hello, World!</text></root>";
CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);

// The data we entered resides in these variables
Assert.assertEquals(xmlPart.getData(), xmlPartContent.getBytes());
Assert.assertEquals(xmlPart.getId(), xmlPartId);

// XML parts can be referenced by collection index or GUID
Assert.assertEquals(doc.getCustomXmlParts().get(0), xmlPart);
Assert.assertEquals(doc.getCustomXmlParts().getById(xmlPartId), xmlPart);

// Once the part is created, we can add XML schema associations like this
xmlPart.getSchemas().add("http://www.w3.org/2001/XMLSchema");

// We can also clone parts and insert them into the collection directly
CustomXmlPart xmlPartClone = xmlPart.deepClone();
xmlPartClone.setId(UUID.randomUUID().toString());
doc.getCustomXmlParts().add(xmlPartClone);

Assert.assertEquals(doc.getCustomXmlParts().getCount(), 2);

// Iterate through collection with an enumerator and print the contents of each part
Iterator<CustomXmlPart> enumerator = doc.getCustomXmlParts().iterator();
int index = 0;
while (enumerator.hasNext()) {
    CustomXmlPart customXmlPart = enumerator.next();
    System.out.println(MessageFormat.format("XML part index {0}, ID: {1}", index, customXmlPart.getId()));
    System.out.println(MessageFormat.format("\tContent: {0}", customXmlPart.getData()));
    index++;
}

// XML parts can be removed by index
doc.getCustomXmlParts().removeAt(1);

Assert.assertEquals(doc.getCustomXmlParts().getCount(), 1);

// The XML part collection itself can be cloned also
CustomXmlPartCollection customXmlParts = doc.getCustomXmlParts().deepClone();

// And all elements can be cleared like this
customXmlParts.clear();

// Create a StructuredDocumentTag that will display the contents of our part,
// insert it into the document and save the document
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);
sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[1]", "");

doc.getFirstSection().getBody().appendChild(sdt);

doc.save(getArtifactsDir() + "SDT.CustomXml.docx");

See Also:
          Aspose.Words Documentation - the home page for the Aspose.Words Product Documentation.
          Aspose.Words Support Forum - our preferred method of support.