XML Manager

EMDK For Android - 4.0

Overview

The XmlMgr specifies the Error Handling Mode the MXMS will use when processing a Request XML document.

The MXMS processes a Request XML document that contains one or more Features as defined in the CSP. Each Feature is represented by a top-level characteristic tag in the Request XML document, whose type matches that CSP Feature. For example, a Feature of "XmlMgr" CSP in XML would begin with:


<characteristic type="XmlMgr" ...

The MXMS executes Features, by passing them to the corresponding CSPs, in the order they appear in the Request XML document, by passing the characteristic to the corresponding CSP. When a Feature is executed by a CSP, the CSP returns Result XML. A characteristic tag is returned by the CSP to indicate that the Feature succeeded. A characteristic-error tag is returned by the CSP to indicate that the Feature failed. The MXMS aggregates the Result XML returned by the CSPs in the order the Features are executed, to create the final Result XML.

For the purposes of discussing MXMS Error-Handling, any Feature that can be executed at all is considered a success and any Feature that cannot be executed at all is considered a failure. Errors are handled by the MXMS based on the Error Handling Mode that is in effect. The MXMS has a Default Error Handling Mode that is always in effect at the beginning of each new Request XML document that is processed. The Error Handling Mode can be left as the default or can be changed one or more times within a single Request XML document.

When the Default Error-Handling Mode, "Execute all to end", is in effect, the MXMS executes all Features, whether they succeed or fail, until the end of the XML is reached. The MXMS then returns the Result XML which will contain the same number of characteristic tags plus characteristic-errors tags as there were characteristic tags in the Request XML document. This Error-Handling Mode basically tries to execute everything and reports what happens at the end. This mode is the default because it is good for most general situations. But if one Feature depends on another, this mode can cause a "domino effect" where one failure causes a whole sequence of failures.

The MXMS supports an additional Error-Handling Mode, "Execute until error, then stop", where it stops executing Features on the first failure and returns Result XML that contains only the characteristic tags for the Features that succeeded plus the characteristic-error tag for the Feature that failed. This mode can be beneficial when Features are dependent on each other since it avoids the "domino effect" where one failure causes a whole sequence of failures and also allows execution to be terminating sooner, without attempting Features that are doomed to fail.

The XmlMgr allows you to specify the Error Handling Mode the MXMS should use when processing a Request XML document. If no XmlMgr Features are present in a Request XML document, then the entire document is processed using the Default Error Handling Mode. If an XmlMgr Feature is present in a Request XML document, then the Error Handling Mode specified by that XmlMgr Feature will be used by the MXMS when executing subsequent Features up until the next XmlMgr Feature or the end of the Request XML document, whichever comes first.

Main Functionality

  • Specify the XML processing mode to use
    • Execute all Features and return all successes and failures
    • Execute Features until first error, then stop and return all successes and first failure
    • Execute Features until first error, then skip to next "Catch" or end
    • Stop skipping and resume execution of Features

XML Processing Mode

This parm allows you to specify the Error Handling Mode the MXMS should use when processing a Request XML document.

Parm Name: ProcessingMode

Option Name Description Requires
1 Execute all to end This value will set the Error Handling Mode such that the MXMS will attempt to execute all Features that appear in the Request XML document, in the order they appear without respect to success or failure of each Feature. The Result XML will then return all successes and all failures, in the order the execution of the Features were attempted.

MX: 4.2+

2 Execute until error, then stop This value will set the Error Handling Mode such that the MXMS will attempt to execute Features that appear in the Request XML document, in the order they appear so long as those Features succeed, but will stop on the first failure and ignore the remaining Features in the Request XML. The Result XML will then return all successes and the first failure, in the order the execution of the Features were attempted.

MX: 4.2+

3 Try until error, then Skip to Catch This value will set the Error Handling Mode such that the MXMS will attempt to execute Features that appear in the Request XML document, in the order they appear so long as those Features succeed, but will stop on the first failure and begin skipping Features. Features will be skipped until an XmlMgr Feature is encountered where parm ProcessingMode has the value "4" ("Catch error, Execute remainder") or the end of the Request XML document is reached. If a "Catch" is reached, then the MXMS will continue execution of subsequent Features with the Error Handling Mode set to "1" ("Execute all to end"). The Result XML will then return all successes and the first failure, in the order the execution of the Features were attempted.

MX: 4.2+

4 Catch error, Execute remainder This value indicates the location of a "Catch" point as described above.

MX: +