JBoss.orgCommunity Documentation
The
xcap-diff
is defined in
http://tools.ietf.org/html/rfc5875
.
However to understand it fully you need to have understanding of following:
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.
Minimal knowledge how
XCAP
interaction looks like is required. This protocol is defined in
http://tools.ietf.org/html/rfc4825
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
The
xcap-diff
has been divided into following components:
component which is capable of creating patching instructions consistent with
rfc5261
.
component which is capable of creating
xcap-diff
attribute patching instructions
component which is capable of creating
xcap-diff
element patching instructions
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:
the document type, defines what is the concrete type of XML documents used
the patching instruction type
the element type
the node type
Creates patch operation to add new attribute into document.
Creates patch operation to add new element into document.
Creates patch operation to add new node into document.
Creates patch operation to insert new namespace into document.
Creates patch operation to replace existing attribute.
Creates patch operation to replace exisiting element in document.
Creates patch operation to replace existing node in document.
Creates patch operation to replace exisiting namespace.
Creates patch operation to remove exisiting attribute from document.
Creates patch operation to remove existing element from document.
Creates patch operation to remove existing node from document.
Creates patch operation to remove existing namespace from document.
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:
the patching instruction type
Creates patch operation which indicates value of certain attribute in document.
Creates patch operation to indicate certain attribute does not exist in document.
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:
the patching instruction type
Creates patch operation which indicates value of certain element in document.
Creates patch operation to indicate if certain element exists in document.
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:
the document patching instruction type
the patching instructions used as elements which build component created
the element type, defines what is the concrete type of XML elements used
the xml patch ops node type, defines what is the concrete type of XML patch ops node params used by {@link XmlPatchOperationsBuilder}
Creates patch instruction for changes in particular document.
Creates patch instruction indicating that document body has not changed. It is used to indicate tag changes.
Returns
XML
Patch instructions builder. Instance of this interface should be used to create instructions to fed to above methods.
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:
the patch type, defines what is the concrete type of finalized XCAP DIFF patch
the component type, defines what is the concrete type of each patch component, to be aggregated in a XCAP DIFF patch
the document type, defines what is the concrete type of XML documents used
the element type, defines what is the concrete type of XML elements used
the xml patch ops node type, defines what is the concrete type of XML patch ops node params used by {@link XmlPatchOperationsBuilder}
Creates patch instruction from component passes. Components passed to this method are genereated by interfaces retrieved by getter methods explaioned below.
Retrieves Attribute Patch builder: Section 2.2, “XCAP Attribute Patch Builder”
Retrieves Element Patch builder: Section 2.3, “XCAP Element Patch Builder”
Retrieves Document Patch builder: Section 2.4, “XCAP Document Patch Builder”
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:
the patch type, defines what is the concrete type of finalized XCAP DIFF patch
the document type, defines what is the concrete type of XML documents used
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:
the patch type, defines what is the concrete type of finalized XCAP DIFF patch
the component type, defines what is the concrete type of each patch component, to be aggregated in a XCAP DIFF patch
the document type, defines what is the concrete type of XML documents used
the element type, defines what is the concrete type of XML elements used
the xml patch ops node type, defines what is the concrete type of XML patch ops node params used by {@link XmlPatchOperationsBuilder}