JBoss.orgCommunity Documentation

Chapter 2. Design Overview

2.1. XML Patch Instruction Builder
2.2. XCAP Attribute Patch Builder
2.3. XCAP Element Patch Builder
2.4. XCAP Document Patch Builder
2.5. XCAP Patch Builder
2.6. XCAP Patch Applier
2.7. XCAP Diff Factory

The xcap-diff is defined in http://tools.ietf.org/html/rfc5875 . However to understand it fully you need to have understanding of following:

XML

XPath

XPath expression are used to navigate through XML document and identify specific nodes in it. XPath is defined in this http://www.w3.org/TR/xpath20/ document.

XCAP

Minimal knowledge how XCAP interaction looks like is required. This protocol is defined in http://tools.ietf.org/html/rfc4825

XML Diff/XML Patch

XCAP Diff is an extension to XML Diff . Strong knowledge of the latter is required. This protocol is defined in http://tools.ietf.org/html/rfc5261

SIP Notification framework

http://tools.ietf.org/html/rfc3265

XCAP Diff Notification framework

http://tools.ietf.org/html/rfc5875

The xcap-diff has been divided into following components:

XML Patch instructions builder

component which is capable of creating patching instructions consistent with rfc5261 .

Attribute Patch instruction builder

component which is capable of creating xcap-diff attribute patching instructions

Element Patch instruction builder

component which is capable of creating xcap-diff element patching instructions

Document Patch instruction builder

component which is capable of creating xcap-diff document wide patch instructions(in particular aggregate instructions generated by Section 2.1, “XML Patch Instruction Builder” )

XCAP Patch builder

simple component which builds well formed document from patching operations.

XCAP Patch applier

simple component which is capable of applying patching instructions to document.

The API definition for all above components make use of Java generics. Reason for this is to make this library agnostic to specific implementation of XML manipulation library.

XML Patch instruction builder is defined as follows:



public interface XmlPatchOperationsBuilder<D,P, E, N> {
    public static final String XML_PATCH_OPS_NAMESPACE = "urn:ietf:params:xml:schema:patch-ops";
    public enum Pos {
        prepend, before, after
    }
    public enum Ws {
        before, after, both
    }
    public P addAttribute(String sel, String attrName, String attrValue,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P addElement(String sel, E element,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P addNode(String sel, Pos pos, N node,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P addPrefixNamespaceDeclaration(String sel, String namespacePrefix,
            String namespaceValue, Map<String, String> namespaceBindings)
            throws BuildPatchException;
    public P replaceAttribute(String sel, String attributeValue,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P replaceElement(String sel, E element,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P replaceNode(String sel, N node,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P replacePrefixNamespaceDeclaration(String sel,
            String namespaceValue, Map<String, String> namespaceBindings)
            throws BuildPatchException;
    public P removeAttribute(String sel, Map<String, String> namespaceBindings)
            throws BuildPatchException;
    public P removeElement(String sel, Ws ws,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P removeNode(String sel, Map<String, String> namespaceBindings)
            throws BuildPatchException;
    public P removePrefixNamespaceDeclaration(String sel,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P[] buildPatchInstructions(D originalDocument, D patchedDocument)
            throws BuildPatchException;
}
        

Above code uses following generics:

public P addAttribute(String sel, String attrName, String attrValue, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to add new attribute into document.

public P addElement(String sel, E element, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to add new element into document.

public P addNode(String sel, N node, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to add new node into document.

public P addPrefixNamespaceDeclaration(String sel, String namespacePrefix, String namespaceValue, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to insert new namespace into document.

public P replaceAttribute(String sel, String attributeValue, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to replace existing attribute.

public P replaceElement(String sel, E element, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to replace exisiting element in document.

public P replaceNode(String sel, N node, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to replace existing node in document.

public P replacePrefixNamespaceDeclaration(String sel, String namespaceValue, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to replace exisiting namespace.

public P removeAttribute(String sel, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to remove exisiting attribute from document.

public P removeElement(String sel, Ws ws, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to remove existing element from document.

public P removeNode(String sel, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to remove existing node from document.

public P removePrefixNamespaceDeclaration(String sel, Map<String, String> namespaceBindings) throws BuildPatchException;

Creates patch operation to remove existing namespace from document.

public P[] buildPatchInstructions(D originalDocument, D patchedDocument) throws BuildPatchException;

Compares two documents and creates set of patching operations that need to be applied to first document to be equal to patched one.

XCAP Attribute Patch instruction builder is defined as follows



public interface AttributePatchComponentBuilder<P> {
    public P buildPatchComponent(String sel, String attributeValue,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P buildPatchComponent(String sel,
            Map<String, String> namespaceBindings) throws BuildPatchException;
}
        
        

Above code uses following generics:

XCAP Element Patch instruction builder is defined in very similar manner as Attribute one:



public interface ElementPatchComponentBuilder<C, E> {
    public P buildPatchComponent(String sel, E element,
            Map<String, String> namespaceBindings) throws BuildPatchException;
    public P buildPatchComponent(String sel, boolean exists,
            Map<String, String> namespaceBindings) throws BuildPatchException;
}
        
        

Above code uses following generics:

XCAP Document Patch instruction builder is defined as follows:



public interface DocumentPatchComponentBuilder<P, D, E, N> {
    public P buildPatchComponent(String sel, String previousETag,
            String newETag, C[] patchingInstructions)
            throws BuildPatchException;
    public P getBodyNotChangedPatchingInstruction() throws BuildPatchException;
    public XmlPatchOperationsBuilder<D,P, E, N> getXmlPatchOperationsBuilder();
}
        
        

Above code uses following generics:

XCAP Patch instruction builder is defined as follows:



public interface XcapDiffPatchBuilder<P, C, D, E, N> {
    public P buildPatch(String xcapRoot, C[] components)
            throws BuildPatchException;
    public AttributePatchComponentBuilder<C> getAttributePatchComponentBuilder();
    public ElementPatchComponentBuilder<C, E> getElementPatchComponentBuilder();
    public DocumentPatchComponentBuilder<C, D, E, N> getDocumentPatchComponentBuilder();
}
        
        

Above code uses following generics:

XCAP Patch instruction applier is defined as follows:



public interface XcapDiffPatchApplier<P, D> {
    public void applyPatch(P patch, D document) throws ApplyPatchException;
}
        
        

Above code uses following generics:

Applier has single method which applies patch generated to local copy of document to update its content.

Last element defined by xcap-diff library is XCAP Diff factory. Simple component which takes care of initialization of all above elements. It is defined as follows:



public interface XcapDiffFactory<P, C, D, E, N> {
    public static final String XCAP_DIFF_NAMESPACE_URI = "urn:ietf:params:xml:ns:xcap-diff";
    public XcapDiffPatchApplier<P, D> getPatchApplier();
    public XcapDiffPatchBuilder<P, C, D, E, N> getPatchBuilder();
}
        
        

Above code uses following generics: