Mobicents XML Patch Ops API

Version 5

    XML Patch Ops

     

    XML documents are currently widely used as contianers for various data. Offten data held in documents is of interest, to third parties, to the system where document/data is stored. Thus there is need to inform third parties that some data has changed in document. However in most cases, said doucments are big entities. Exchanging full document on single XML node change is inefficient. Thus there has been need to minimize size of exchanged data.

     

    This is the reason why XML Patch Ops came to beeing. XML Patch ops define following:

    • format of patch operation - minimal elements describing change in document
    • how patch operation are to be applied in order produce produce document stored in server, from unpatched document.

     

    Currently there are two documents describing XML Patch Operations:

     

     

     

    The Mobicents XLM Patch Ops API has been introduced to standarize manipulation on XML documents. Defined API has been created to honor said documents and ease document manipulation.

     

    Resources

     

     

     

     

    API

     

    Mobicents XLM Patch Ops API has been created to be as flexible as possible. That is, to allow developer to freely choose type of used XML manipulation library. This has been achieved via generics mechanism. Please check java doc for more information.

     

    The key interfaces defined in Mobicents XLM Patch Ops API are as follows:

     

    • XcapDiffFactory - defines methods to access concrete implementation of XcapDiffPatchBuilder and XcapDiffPatchApplierxcapDiffFactory.png
    • XcapDiffPatchApplier - defines methods to apply patch operations to specific document. It allows to apply full XCAP Diff Patch document, single XCAP Diff patch operation or single XML Diff patch operation.

              xcapDiffPatchApplier.png

    • XcapDiffPatchBuilder - creates XCAP Diff document from patch operations. Also defines methods to access implementation of components which allow creation of specific patch operations, XCAP and plain XML.xcapDiffPatchBuilder.png
    • AttributePatchComponentBuilder - defines methods to create XCAP attribute patch operationattributePatchComponentBuilder.png
    • ElementPatchComponentBuilder - defines methods to create XCAP element patch operationelementPatchComponentBuilder.png
    • DocumentPatchComponentBuilder - creates XML diff document from patch operations. Also defines methods to access component implementation which allow creation of XML patch operationdocumentPatchComponentBuilder.png
    • XmlPatchOperationsBuilder - defines methods to create patch operations for XML nodes. Also declares method to create XML Diff Patch set for two documents
    • xmlPatchComponentBuilder.png

     

     

    Example

     

    As mentioned, API makes use of generics to ensure developers have freedom in implementation. To better understand examples bellow, here is a short list:

     

    • P - the patch type, defines what is the concrete type of finalized XCAP DIFF patch
    • C - the component type, defines what is the concrete type of each patch component, to be aggregated in a XCAP DIFF patch, created by AttributePatchComponentBuilder  and ElementPatchComponentBuilder
    • D - the document type, defines what is the concrete type of XML documents used
    • E - the element type, defines what is the concrete type of XML elements used, to be passed to XML patch generating components
    • N - the xml patch ops node type, defines what is the concrete type of XML patch ops node params

     

     

    Below is simple example which depicts basic concept of how API is to be used. Note that it uses generic. If you need fully fledged example check documentation or reference implementation article.

     

     

    String xcapRoot = "http://localhost:8080/default"; //root of server

    String documentSelector = "tests/users/sip:joe@example.com/index";

    String attributeSelector = "house/room[id='main']/switch/@on"; //house status document?

    String attributeNewValue = "true";

     

    String elementSelector = "house/room[id='volatile']";

     

    String oldETag = "3416134yyDFGA$v33@!";

    String newETag = "haha";

     

    D originalDocument = ....

     

    XcapDiffFactory xcapDiffFactory = .....;

    XcapDiffPatchBuilder xcapDiffPatchBuilder = xcapDiffFactory.getPatchBuilder();

    DocumentPatchComponentBuilder documentPatchComponentBuilder = xcapDiffPatchBuilder.getDocumentPatchComponentBuilder();

    XmlPatchOperationsBuilder xmlPatchOperationsBuilder = documentPatchComponentBuilder.getXmlPatchOperationsBuilder();

     

     

    C attributeElement = xmlPatchOperationsBuilder.replaceAttribute(attributeSelector,attributeNewValue,null); //no namespaces

    C documentElement = documentPatchComponentBuilder.buildPatchComponent(documentSelector,oldETag,newETag,new C[]{attributeElement});

    P xcapDiffDocument = xcapDiffPatchBuilder.buildPatch(xcapRoot,new Element[]{documentElement}); //xcap diff patch

     

     

    //apply patch with applier

    xcapDiffFactory.getPatchApplier().applyPatch(xcapDiffDocument,originalDocument);