org.adroitlogic.x.feature.xml.api

Interface XMLFeature

All Known Implementing Classes:

XMLFeatureImpl

public interface XMLFeature

This feature API provides features related to XML processing

Since:

17.01

Author:

Ruwan Linton, Udith Gunaratna

Method Summary

Modifier and Type	Method and Description
void	addAttributeToElements(org.adroitlogic.x.api.XMessage msg, String expression, String qName, String nsUri, String value, Map<String,String> ns) Add an attribute to one or more elements selected by an XPath expression e.g.
void	addElementsAsChild(org.adroitlogic.x.api.XMessage msg, String expression, String qualifiedTagName, String namespace, Map<String,String> ns) Inserts Element as a child to the specified elements pointed by an xpath expression
void	addTextElementsAsChild(org.adroitlogic.x.api.XMessage msg, String expression, String qualifiedTagName, String namespace, String elementContent, Map<String,String> ns) Inserts Text Element as a child to the specified elements pointed by an xpath expression
void	convertToDOM(org.adroitlogic.x.api.XMessage m) Convert the current message into a DOMMessage
void	createAndCacheTransformers(URI xsltFileURI) Creates and caches a "minTransformerCount" number of XSLT transformers for the given XSLT file URI
Document	createDOMDocument() Create a new DOM Document object and return
void	deleteAttributes(org.adroitlogic.x.api.XMessage msg, String expression, Map<String,String> ns) Deletes the specified attribute/s e.g.
void	deleteElements(org.adroitlogic.x.api.XMessage msg, String expression, Map<String,String> ns) Delete Elements pointed by an xpath expression
NodeList	extractAsNodeListUsingXPath(Node n, String expression, Map<String,String> ns) Evaluate the given XPath expression against the DOM node, and return result as a NodeList
NodeList	extractAsNodeListUsingXPath(org.adroitlogic.x.api.XMessage m, String expression, Map<String,String> ns) Evaluate the given XPath expression against the XML payload, and return result as a NodeList This method converts the current payload into a DOMMessage
String	extractAsStringUsingXPath(Node n, String expression, Map<String,String> ns) Evaluate the given XPath expression against the DOM node, and return result as a String
String	extractAsStringUsingXPath(String s, String expression, Map<String,String> ns) Evaluate the given XPath expression against the XML payload contained in a String, and return result as a String.
String	extractAsStringUsingXPath(org.adroitlogic.x.api.XMessage m, String expression, Map<String,String> ns) Evaluate the given XPath expression against the XML payload, and return result as a String This method converts the current payload into a DOMMessage
boolean	filter(org.adroitlogic.x.api.XMessage m, String expression, Map<String,String> ns) Evaluate the given boolean XPath expression over the XML payload
boolean	filter(org.adroitlogic.x.api.XMessage m, String expression, String regex, Map<String,String> ns) Evaluate the given XPath expression over the XML payload and compare the resulting String value with the regular expression for a match.
String	getAttribute(org.adroitlogic.x.api.XMessage msg, String expression, Map<String,String> ns) Get attribute value e.g.
Document	getPayloadAsDOM(org.adroitlogic.x.api.XMessage m) Returns payload of the message as a DOM Document
String	getTextElement(org.adroitlogic.x.api.XMessage msg, String expression, Map<String,String> ns) Get text element value for given XPath
void	insertTextElementsAfter(org.adroitlogic.x.api.XMessage msg, String expression, String qualifiedTagName, String namespace, String elementContent, Map<String,String> ns) Inserts an element/elements after the specified element pointed by the XPATH, to the current message.
void	insertTextElementsBefore(org.adroitlogic.x.api.XMessage msg, String expression, String qualifiedTagName, String namespace, String elementContent, Map<String,String> ns) Inserts an element/elements before the specified element pointed by the XPATH, to the current message.
void	mergeXMLAttachmentsUnderElement(org.adroitlogic.x.api.XMessage msg, String rootElemName) Replace the current XML payload with a top level element as specified, and merge the attachments of the message underneath that
void	mergeXMLAttachmentsUnderElement(org.adroitlogic.x.api.XMessage msg, String rootElemName, String rootNS) Replace the current XML payload with a top level element as specified, and merge the attachments of the message underneath that
boolean	remove(org.adroitlogic.x.api.XMessage m, String expression, Map<String,String> ns) Remove the XPath expression specified node from the XML payload.
void	replaceAttributes(org.adroitlogic.x.api.XMessage msg, String expression, String value, Map<String,String> ns) Replaces the specified attribute/s value
void	replaceTextElements(org.adroitlogic.x.api.XMessage msg, String expression, String elementContent, Map<String,String> ns) Replace Text Elements pointed by an xpath expression
void	retainElementAsPayload(org.adroitlogic.x.api.XMessage m, String expression, Map<String,String> ns) Replace the current XML payload with the resulting element from the XPath expression result
void	serialize(Document document, OutputStream os) Serialize the DOM Document into the given OutputStream
void	setPayloadFromDOM(org.adroitlogic.x.api.XMessage m, Document doc) Set the payload of the message with the DOM Document
void	transform(org.adroitlogic.x.api.XMessage msg, URI xsltFileURI) Transform the message payload by XSLT (without any parameters), assuming a non DOM result and assuming that the complete message payload will be used as the source of the transformation, and the result will replace the complete message payload
void	transform(org.adroitlogic.x.api.XMessage msg, URI xsltFileURI, String expression, boolean domResult, Map<String,Object> parameters, Map<String,String> ns) Transform the message payload by XSLT
void	transform(org.adroitlogic.x.api.XMessage msg, URI xsltFileURI, String expression, Map<String,String> ns) Transform the message payload by XSLT (without any parameters), assuming a non DOM result
void	validate(Node n, URI... schemaFileURIs) Validates the given DOM Node against one or more schemas.
void	validate(String s, URI... schemaFileURIs) Validates the given String against one or more schemas.
void	validate(org.adroitlogic.x.api.XMessage m, URI... schemaFileURIs) Validates the given message against one or more schemas.
void	validate(org.adroitlogic.x.api.XMessage m, URI[] schemaFileURIs, String expression, Map<String,String> ns) Validates the current message - or an element of it selected via the provided XPath expression - against one or more schemas.
void	validateAll(org.adroitlogic.x.api.XMessage m, URI[] schemaFileURIs, String expression, Map<String,String> ns) Validate the current message - or all elements of it selected via the provided XPath expression - against one or more schemas.
void	wrapPayload(org.adroitlogic.x.api.XMessage msg, String elementName, String namespace) Wrap the XML payload with an outer element

Method Detail

createDOMDocument

Document createDOMDocument()

Create a new DOM Document object and return

Returns:

a new DOM Document

serialize

void serialize(Document document,
               OutputStream os)

Serialize the DOM Document into the given OutputStream

Parameters:

document - the Document to serialize

os - the target OutputStream

setPayloadFromDOM

void setPayloadFromDOM(org.adroitlogic.x.api.XMessage m,
                       Document doc)

Set the payload of the message with the DOM Document

Parameters:

m - the current message whose payload will be set with the DOM message

doc - the DOM document to be inserted as the payload

getPayloadAsDOM

Document getPayloadAsDOM(org.adroitlogic.x.api.XMessage m)

Returns payload of the message as a DOM Document

Parameters:

m - the current message to be passed

Returns:

A DOM document consisting content of the current payload

convertToDOM

void convertToDOM(org.adroitlogic.x.api.XMessage m)

Convert the current message into a DOMMessage

Parameters:

m - the current message to be transformed

retainElementAsPayload

void retainElementAsPayload(org.adroitlogic.x.api.XMessage m,
                            String expression,
                            Map<String,String> ns)

Replace the current XML payload with the resulting element from the XPath expression result

Parameters:

m - the current message

expression - XPath expression selecting the node to retain

ns - an optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

mergeXMLAttachmentsUnderElement

void mergeXMLAttachmentsUnderElement(org.adroitlogic.x.api.XMessage msg,
                                     String rootElemName)

Replace the current XML payload with a top level element as specified, and merge the attachments of the message underneath that

Parameters:

msg - the message to transform

rootElemName - the new root element created

mergeXMLAttachmentsUnderElement

void mergeXMLAttachmentsUnderElement(org.adroitlogic.x.api.XMessage msg,
                                     String rootElemName,
                                     String rootNS)

Replace the current XML payload with a top level element as specified, and merge the attachments of the message underneath that

Parameters:

msg - the message to transform

rootElemName - the new root element created

rootNS - optional namespace for the root element, or null

validate

void validate(org.adroitlogic.x.api.XMessage m,
              URI... schemaFileURIs)

Validates the given message against one or more schemas. If validation failed, this will throw an IntegrationRuntimeException with details of the XSD validation failures

Parameters:

m - the message holding the payload for validation

schemaFileURIs - an array of XSD file URIs to validate against Note: the validator is sensitive to the order in which the Schemas are given. Otherwise it may result in an error such as "SAXParseException: cvc-elt.1: Cannot find the declaration of element.

It is advised to use the AbstractProcessingElement.getResource(String filePath) method to get the URI from a file path

validate

void validate(String s,
              URI... schemaFileURIs)

Validates the given String against one or more schemas. If validation failed, this will throw an IntegrationRuntimeException with details of the XSD validation failures

Parameters:

s - the XML string

schemaFileURIs - an array of XSD file URIs to validate against Note: the validator is sensitive to the order in which the Schemas are given. Otherwise it may result in an error such as "SAXParseException: cvc-elt.1: Cannot find the declaration of element"

It is advised to use the AbstractProcessingElement.getResource(String filePath) method to get the URI from a file path

validate

void validate(Node n,
              URI... schemaFileURIs)

Validates the given DOM Node against one or more schemas. If validation failed, this will throw an IntegrationRuntimeException with details of the XSD validation failures

Parameters:

n - the DOM Node containing the XML to be validated

schemaFileURIs - an array of XSD file URIs to validate against Note: the validator is sensitive to the order in which the Schemas are given. Otherwise it may result in an error such as "SAXParseException: cvc-elt.1: Cannot find the declaration of element"

It is advised to use the AbstractProcessingElement.getResource(String filePath) method to get the URI from a file path

validate

void validate(org.adroitlogic.x.api.XMessage m,
              URI[] schemaFileURIs,
              String expression,
              Map<String,String> ns)

Validates the current message - or an element of it selected via the provided XPath expression - against one or more schemas. If validation failed, this will throw an IntegrationRuntimeException with details of the XSD validation failures

Parameters:

m - the message holding the payload for validation

schemaFileURIs - an array of XSD file URIs to validate against Note: the validator is sensitive to the order in which the Schemas are given. Otherwise it may result in an error such as "SAXParseException: cvc-elt.1: Cannot find the declaration of element"

It is advised to use the AbstractProcessingElement.getResource(String filePath) method to get the URI from a file path

expression - an optional XPath expression selecting the node for validation

ns - an optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

validateAll

void validateAll(org.adroitlogic.x.api.XMessage m,
                 URI[] schemaFileURIs,
                 String expression,
                 Map<String,String> ns)

Validate the current message - or all elements of it selected via the provided XPath expression - against one or more schemas. If validation failed, this will throw a IntegrationRuntimeException with details of the XSD validation failures

Parameters:

m - the message holding the payload for validation

schemaFileURIs - an array of XSD file URIs to validate against Note: the validator is sensitive to the order in which the Schemas are given. Otherwise it may result in an error such as "SAXParseException: cvc-elt.1: Cannot find the declaration of element"

It is advised to use the AbstractProcessingElement.getResource(String filePath) method to get the URI from a file path

expression - an optional XPath expression selecting the nodes for validation

ns - an optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

createAndCacheTransformers

void createAndCacheTransformers(URI xsltFileURI)

Creates and caches a "minTransformerCount" number of XSLT transformers for the given XSLT file URI

Parameters:

xsltFileURI - URI of the XSLT file to be used for the transformation

transform

void transform(org.adroitlogic.x.api.XMessage msg,
               URI xsltFileURI,
               String expression,
               boolean domResult,
               Map<String,Object> parameters,
               Map<String,String> ns)

Transform the message payload by XSLT

Parameters:

msg - current message

xsltFileURI - the XSLT file URI

expression - an optional XPath expression to select the source node for XSLT, and node to replace with the result

domResult - is the result desired as a DOM payload? (useful for further XML processing)

parameters - any XSLT parameters to be passed to the transformation

ns - an optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

transform

void transform(org.adroitlogic.x.api.XMessage msg,
               URI xsltFileURI,
               String expression,
               Map<String,String> ns)

Transform the message payload by XSLT (without any parameters), assuming a non DOM result

Parameters:

msg - current message

xsltFileURI - the XSLT filename

expression - an optional XPath expression to select the source node for XSLT, and node to replace with the result

ns - an optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

transform

void transform(org.adroitlogic.x.api.XMessage msg,
               URI xsltFileURI)

Transform the message payload by XSLT (without any parameters), assuming a non DOM result and assuming that the complete message payload will be used as the source of the transformation, and the result will replace the complete message payload

Parameters:

msg - current message

xsltFileURI - the XSLT filename

filter

boolean filter(org.adroitlogic.x.api.XMessage m,
               String expression,
               String regex,
               Map<String,String> ns)

Evaluate the given XPath expression over the XML payload and compare the resulting String value with the regular expression for a match. This method converts the current payload into a DOMMessage

Parameters:

m - the current message

expression - the XPath expression to evaluate against the message payload

regex - an optional regular expression to evaluate the XPath results' String value against

ns - an optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

true if the regular expression matches the String result of the XPath expression

filter

boolean filter(org.adroitlogic.x.api.XMessage m,
               String expression,
               Map<String,String> ns)

Evaluate the given boolean XPath expression over the XML payload

Parameters:

m - the current message

expression - the XPath expression to evaluate against the message payload

ns - an optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

true if the XPath expression evaluates to true

addAttributeToElements

void addAttributeToElements(org.adroitlogic.x.api.XMessage msg,
                            String expression,
                            String qName,
                            String nsUri,
                            String value,
                            Map<String,String> ns)

Add an attribute to one or more elements selected by an XPath expression e.g. xmlFeature.addAttributeToElements(msg, "//order/symbol", null, "att1", null, "value1");

Parameters:

msg - the message where the transformation is performed

expression - the xpath expression to select the elements where the attribute should be added

qName - the qualified name for the new attribute. To specify a custom prefix use it here (e.g. "myns:myqname")

nsUri - the namespace URI for the new attribute, or null (to specify a custom prefix, see qName above)

value - the new value of the attribute

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

getAttribute

String getAttribute(org.adroitlogic.x.api.XMessage msg,
                    String expression,
                    Map<String,String> ns)

Get attribute value e.g. xmlFeature.getAttribute(msg, "//order[1]/symbol/@att1", null)

Parameters:

msg - the message to read the attribute from

expression - the xpath expression to the element from where the attribute should be retrieved

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

the value of the attribute

deleteAttributes

void deleteAttributes(org.adroitlogic.x.api.XMessage msg,
                      String expression,
                      Map<String,String> ns)

Deletes the specified attribute/s e.g. xmlFeature.deleteAttributes(msg, "//order/symbol/@s:att2", ns);

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the attributes, which are to be deleted

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

replaceAttributes

void replaceAttributes(org.adroitlogic.x.api.XMessage msg,
                       String expression,
                       String value,
                       Map<String,String> ns)

Replaces the specified attribute/s value

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the attribute, which is to be replaced

value - the new value of the attribute

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

addTextElementsAsChild

void addTextElementsAsChild(org.adroitlogic.x.api.XMessage msg,
                            String expression,
                            String qualifiedTagName,
                            String namespace,
                            String elementContent,
                            Map<String,String> ns)

Inserts Text Element as a child to the specified elements pointed by an xpath expression

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the node/s, which will be the parent for the new node/s

qualifiedTagName - the qualified name of the new element to be added

namespace - an optional String specifying the namespace url of the new element

elementContent - the text content of the new element

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

addElementsAsChild

void addElementsAsChild(org.adroitlogic.x.api.XMessage msg,
                        String expression,
                        String qualifiedTagName,
                        String namespace,
                        Map<String,String> ns)

Inserts Element as a child to the specified elements pointed by an xpath expression

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the node/s, which will be the parent for the new node/s

qualifiedTagName - the qualified name of the new element to be added

namespace - an optional String specifying the namespace url of the new element

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

getTextElement

String getTextElement(org.adroitlogic.x.api.XMessage msg,
                      String expression,
                      Map<String,String> ns)

Get text element value for given XPath

Parameters:

msg - the message to read the attribute from

expression - the xpath expression to the element where the text content should be read

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

the value of the attribute

replaceTextElements

void replaceTextElements(org.adroitlogic.x.api.XMessage msg,
                         String expression,
                         String elementContent,
                         Map<String,String> ns)

Replace Text Elements pointed by an xpath expression

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the text elements to be replaced

elementContent - the text content of the new element/s

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

deleteElements

void deleteElements(org.adroitlogic.x.api.XMessage msg,
                    String expression,
                    Map<String,String> ns)

Delete Elements pointed by an xpath expression

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the text elements to be replaced

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

insertTextElementsBefore

void insertTextElementsBefore(org.adroitlogic.x.api.XMessage msg,
                              String expression,
                              String qualifiedTagName,
                              String namespace,
                              String elementContent,
                              Map<String,String> ns)

Inserts an element/elements before the specified element pointed by the XPATH, to the current message. If the XPath expression points to multiple elements, new element will be added before all the elements pointed by the XPath. The content of the new element should be String. No complex types are allowed.

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the node, where the new element should be added before

qualifiedTagName - the qualified tag name of the new element to be added

namespace - namespace uri for the new tag

elementContent - the content of the new element

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

insertTextElementsAfter

void insertTextElementsAfter(org.adroitlogic.x.api.XMessage msg,
                             String expression,
                             String qualifiedTagName,
                             String namespace,
                             String elementContent,
                             Map<String,String> ns)

Inserts an element/elements after the specified element pointed by the XPATH, to the current message. If the XPath expression points to multiple elements, new element will be added after all the elements pointed by the XPath.The content of the new element should be String. No complex types are allowed.

Parameters:

msg - the current message containing the payload

expression - the xpath expression to the node, where the new element should be added after

qualifiedTagName - the qualified tag name of the new element to be added

namespace - namespace uri for the new tag

elementContent - the content of the new element

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

remove

boolean remove(org.adroitlogic.x.api.XMessage m,
               String expression,
               Map<String,String> ns)

Remove the XPath expression specified node from the XML payload. This method converts the current payload of the message into a DOMMessage

Parameters:

m - the current message

expression - the XPath expression to evaluate against the message payload

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

true if the node was removed, false if not

extractAsStringUsingXPath

String extractAsStringUsingXPath(org.adroitlogic.x.api.XMessage m,
                                 String expression,
                                 Map<String,String> ns)

Evaluate the given XPath expression against the XML payload, and return result as a String This method converts the current payload into a DOMMessage

Parameters:

m - the current message

expression - the XPath expression to evaluate against the message payload

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

the result of the XPath expression as a String, or empty string if there isn't any matching elements

extractAsStringUsingXPath

String extractAsStringUsingXPath(String s,
                                 String expression,
                                 Map<String,String> ns)

Evaluate the given XPath expression against the XML payload contained in a String, and return result as a String. Note that this will convert the given string content into a DOM document and if you by any chance already have access to the equivalent DOM, you should call the extractAsStringUsingXPath(Node, String, Map) instead of this method as that will be much more performance friendly

Parameters:

s - a String containing an XML payload

expression - the XPath expression to evaluate against the XML payload

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

the result of the XPath expression as a String, or empty string if there isn't any matching elements

extractAsStringUsingXPath

String extractAsStringUsingXPath(Node n,
                                 String expression,
                                 Map<String,String> ns)

Evaluate the given XPath expression against the DOM node, and return result as a String

Parameters:

n - DOM node to be subjected to the evaluation

expression - the XPath expression to evaluate against the DOM node

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

the result of the XPath expression evaluation over the given node as a string or empty string if there isn't any matching elements

extractAsNodeListUsingXPath

NodeList extractAsNodeListUsingXPath(org.adroitlogic.x.api.XMessage m,
                                     String expression,
                                     Map<String,String> ns)

Evaluate the given XPath expression against the XML payload, and return result as a NodeList This method converts the current payload into a DOMMessage

Parameters:

m - the current message

expression - the XPath expression to evaluate against the message payload

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

the result of the XPath expression as a NodeList, or null

extractAsNodeListUsingXPath

NodeList extractAsNodeListUsingXPath(Node n,
                                     String expression,
                                     Map<String,String> ns)

Evaluate the given XPath expression against the DOM node, and return result as a NodeList

Parameters:

n - DOM node to be subjected to the evaluation

expression - the XPath expression to evaluate against the message payload

ns - optional map with namespace prefixes (as keys) and namespaces (as values) used within the XPath expression

Returns:

the result of the XPath expression as a NodeList, or null

wrapPayload

void wrapPayload(org.adroitlogic.x.api.XMessage msg,
                 String elementName,
                 String namespace)

Wrap the XML payload with an outer element

Parameters:

msg - the message containing the payload to be wrapped

elementName - name of the wrapper element

namespace - optional namespace or null