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:
- http://tools.ietf.org/html/rfc5261 - describes base of XML Patch Ops. Structures and how patch operations should be applied.
- http://tools.ietf.org/html/rfc5875 - describes XCAP Diff Patch Ops. Is an extension to rfc5261, specific to XCAP resources.
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 source can be accessed via svn at: http://mobicents.googlecode.com/svn/trunk/protocols/xcap-diff/api
- Documentation source can be accessed vis svn at: http://mobicents.googlecode.com/svn/trunk/protocols/xcap-diff/docs
- Binary release can be accessed at: n/a
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 XcapDiffPatchApplier
- 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.
- 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.
- AttributePatchComponentBuilder - defines methods to create XCAP attribute patch operation
- ElementPatchComponentBuilder - defines methods to create XCAP element patch operation
- DocumentPatchComponentBuilder - creates XML diff document from patch operations. Also defines methods to access component implementation which allow creation of XML patch operation
- XmlPatchOperationsBuilder - defines methods to create patch operations for XML nodes. Also declares method to create XML Diff Patch set for two documents
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);
Comments