Pipelines and Discovery

The XML Compare REST service is oriented towards discovery and running of comparison pipelines which are specified using DXP and DCP configuration files. The existing (non-REST) command-line driver includes a number of prepared pipelines. By including command-line jar file (e.g. command-10.0.0.jar) in the runtime classpath the REST service makes these pipelines available for discovery and comparison.

DeltaXML's prepared pipelines can be ignored from being loaded by specifying -DignoreDeltaxmlPipelines=true when starting the server.

Additionally, DXP and DCP configuration files can be added to the REST service by placing them in the install directory. When doing so please ensure that any additional pipeline configurations have distinct id and description attributes to any existing or built-in pipelines to avoid overwriting them.

The /pipelines resource provides information about the comparison pipelines that have been discovered by the REST service.

The 'GET /api/xml-compare/v1/pipelines' call provides similar information to the use of the standard XML Compare command line driver without arguments.

Request

XML

GET /api/xml-compare/v1/pipelines

Response

XML

HTTP/1.1 200 OK
<pipelines>
  <pipeline>
    <id>diffreport</id>
    <name>[DXP] XML Compare, output HTML folding report</name>
    <fullDescription>
      [Uses PipelinedComparatorS9] This configuration is used to produce a HTML folding differences report to be viewed in a browser.
    </fullDescription>
    <links>
      <link href="/api/xml-compare/v1/pipelines/diffreport" rel="self"/>
    </links>
    <fileExtension>.html</fileExtension>
  </pipeline>
  <pipeline>
    <id>xhtml</id>
    <name>[DXP] XHTML Compare, output XHTML</name>
    <fullDescription>
      This configuration is used to compare two XHTML input files and produce an XHTML file that displays changes.
    </fullDescription>
    <links>
      <link href="/api/xml-compare/v1/pipelines/xhtml" rel="self"/>
    </links>
    <fileExtension>.html</fileExtension>
  </pipeline>
</pipelines>

The response above is an XML result. An equivalent, similar JSON result could be obtained by using the Accept http header:

Request

CODE

GET /api/xml-compare/v1/pipelines
Accept: application/json

Response

JS

{
    "pipelines": [
        {
            "id": "diffreport",
            "name": "[DXP] XML Compare, output HTML folding report",
            "fullDescription": "\n[Uses PipelinedComparatorS9] This configuration is used to produce a HTML folding differences report to be viewed in a browser.\n  ",
            "links": [
                {
                    "href": "/api/xml-compare/v1/pipelines/diffreport",
                    "rel": "self"
                }
            ],
            "fileExtension": ".html"
        },
        {
            "id": "xhtml",
            "name": "[DXP] XHTML Compare, output XHTML",
            "fullDescription": "\nThis configuration is used to compare two XHTML input files and produce an XHTML file that displays changes.\n  ",
            "links": [
                {
                    "href": "/api/xml-compare/v1/pipelines/xhtml",
                    "rel": "self"
                }
            ],
            "fileExtension": ".html"
        }
    ]
}

Further discovery of the pipeline parameters and their default values is possible by using the specific pipelines resource - i.e. /pipelines/{pipelineId}. This capability is similar to that provided by the 'describe' operation in the standard XML Compare command-line driver.

Request

CODE

GET /api/xml-compare/v1/pipelines/delta

Response (XML)

XML

<pipeline>
    <id>delta</id>
    <name>[DXP] XML Compare, output XML delta</name>
    <configurationParameters>
        <configurationParameter type="boolean">
            <name>Preserve Whitespace</name>
            <description>whether to normalise whitespace before comparison</description>
            <defaultValue>false</defaultValue>
        </configurationParameter>
        <configurationParameter type="boolean">
            <name>Full Context</name>
            <description>whether to include unchanged data in the delta file</description>
            <defaultValue>true</defaultValue>
        </configurationParameter>
        <configurationParameter type="boolean">
            <name>Word By Word</name>
            <description>whether to compare PCDATA in a more detailed way</description>
            <defaultValue>false</defaultValue>
        </configurationParameter>
        <configurationParameter type="boolean">
            <name>Enhanced Match 1</name>
            <description>whether to use the 4.x enhanced matcher that is tailored to comparing documents</description>
            <defaultValue>true</defaultValue>
        </configurationParameter>
        <configurationParameter type="string">
            <name>Indent</name>
            <description>whether to pretty print the output or not. May be set to 'yes' or 'no'</description>
            <defaultValue>yes</defaultValue>
        </configurationParameter>
    </configurationParameters>
    <fullDescription>
This configuration is used to produce an XML delta file representing changes in the input xml.
  </fullDescription>
    <links>
        <link href="/api/xml-compare/v1/pipelines/delta" rel="self"/>
    </links>
    <fileExtension>.xml</fileExtension>
</pipeline>

Response (JSON)

JS

{
    "id": "delta",
    "name": "[DXP] XML Compare, output XML delta",
    "configurationParameters": [
        {
            "type": "boolean",
            "name": "Preserve Whitespace",
            "description": "whether to normalise whitespace before comparison",
            "defaultValue": false
        },
        {
            "type": "boolean",
            "name": "Full Context",
            "description": "whether to include unchanged data in the delta file",
            "defaultValue": true
        },
        {
            "type": "boolean",
            "name": "Word By Word",
            "description": "whether to compare PCDATA in a more detailed way",
            "defaultValue": false
        },
        {
            "type": "boolean",
            "name": "Enhanced Match 1",
            "description": "whether to use the 4.x enhanced matcher that is tailored to comparing documents",
            "defaultValue": true
        },
        {
            "type": "string",
            "name": "Indent",
            "description": "whether to pretty print the output or not. May be set to 'yes' or 'no'",
            "defaultValue": "yes"
        }
    ],
    "fullDescription": "\nThis configuration is used to produce an XML delta file representing changes in the input xml.\n  ",
    "links": [
        {
            "href": "/api/xml-compare/v1/pipelines/delta",
            "rel": "self"
        }
    ],
    "fileExtension": ".xml"
}