| CLUE | C. Groves, Ed. |
| Internet-Draft | W. Yang |
| Intended status: Informational | R. Even |
| Expires: March 19, 2015 | Huawei |
| September 15, 2014 |
CLUE Partial Updates
draft-groves-clue-partial-update-00
This document proposes a method for using partial updates in CLUE Advertisements to update the CLUE data model. It uses the XML patch operations defined in [RFC5261]
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 19, 2015.
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
As commonly recognised, a large conference using CLUE with many participants and captures will result in large CLUE Advertisement messages. Participants may come and go in conferences which require updates to the CLUE information. Sending large CLUE messages to remove a single capture or scene results in unnecessary bandwidth and processing to compare the existing CLUE description with the updated description. It has been recognised that a method that allows partial updates to the CLUE description is desirable.
This document describes procedures for Partial CLUE Advertisements. It does not consider CLUE Configure messages as these are significantly smaller than Advertisement messages.
This document defines a "full Advertisement" as one that does not use the partial advertisement syntax and represents a complete description of a Media Provider's media sending capabilities at that point in time. A "partial Advertisement" is one that uses the syntax defined in this document to represent a sub-set of the complete description.
As noted in clause 4.3/ [I-D.ietf-clue-protocol], an approach using a "delta" mechanism for advertising changes is suggested. It proposed to leverage the mechanism defined in [RFC5261]. It effectively defines an API for manipulating XML nodes (see clause 6/[http://www.w3.org/TR/xpath-datamodel/#Node]) in an XML document. It utilises XPATH to identify the XML nodes. A basic tutorial on XPATH can be found at: http://www.w3schools.com/XPath/default.asp
The procedures are based around the use of XPATH path expressions (see: clause 3.2/[ http://www.w3.org/TR/xpath20/]) to identify a node/s in a CLUE XML document. Several operations are defined that can be used on those nodes. The "add" operation allows the insertion of new XML elements and attributes to the existing XML nodes. The "replace" operation allows the modification of existing XML nodes. The "remove" operation allows the removal of existing XML nodes.
This document is based on updates to version 5 of the CLUE Data Model Schema [I-D.ietf-clue-data-model-schema].
The following functions are defined:
Partial updates are implemented using the existing CLUE Advertisement (ADV) message. The difference being that the ADV message for partial updates will not contain a full clue-info description containing all the relevant media provider information but will instead contain a partial update syntax. A Re-Advertisement request (READV/ACK) will result in the media provider's full clue-info being sent. Thus no changes to the protocol message state model are envisaged.
This document does not perform a numerical analysis on how many bytes will be saved using an Advertisement with a partial update versus a full Advertisement. The amount of bytes saved will be dependent on the desired operation. The examples in this document show potential partial updates against the examples in [I-D.ietf-clue-data-model-schema]. The basic example in the data model draft is ~6300 characters. It can be seen that the size of the partial updates is considerably less than a full CLUE info description.
This document also does not perform an analysis nor give guidelines on how a media provider would determine when to send a partial update versus a full update. It is assumed that the media provider provides an initial full clue-info description and that any subsequent Advertisements contain partial updates. A media provider MAY provide a full Advertisement at any time.
Furthermore this document does not describe how the media provider determines the "diff" between an old Advertisement and a new one. This functionality is internal to the media provider.
The format of the partial updates in based on the XML scheme "patch-ops" defined in [RFC5261]. The partial update XML is defined in a new element "clue-info-diff".
The content of the <clue-info-diff> element is an unordered sequence of <add>, <replace>, and <remove> elements followed by elements from other namespaces for the purposes of extensibility. Any such unknown elements MUST be ignored by the client. The <add>, <replace>, and <remove> elements can contain other extension attributes than what are defined in the corresponding base types of [RFC6502].
Author's Note: The introduction of the possibility for extension is consistent with [RFC6502]. This aspect may be removed to simplify the implementation.
The elements may appear any number of times and in any order in <clue-info-diff>. However the partial update MUST contain at least one <add>, <replace> or <remove> element. Any changes are with respect to the base CLUEinfo description. The "base" CLUEinfo description is the result of a previously sent Advertisement with a full CLUEinfo description and any subsequently sent partial updates. Then sending of a full CLUEinfo description will have the effect of resetting the "base" CLUEinfo description.
It is not possible for one operation (add/replace/remove) to affect another element in the same clue-info-diff. E.g. an operation may not use an XPATH to reference a previous operation in a clue-info-diff. However attribute values may be referenced across operations. E.g. a Capture Scene ID may be used to add a capture scene and also used in a media capture to reference the scene.
If the XPATH cannot be resolved to a single node by the receiver an error response should be generated.
Author's Note: XPATH allows quite advanced methods of identifying XML nodes. To simplify implementations it may be advantageous to limit the selector values for specifying nodes. E.g. nodes must be fully specified by name rather than using wildcarding.
This is the XML proposed for inclusion into the CLUE protocol. It includes the schema for XML patching from [RFC5261] (using [RFC6205] as the basis for the syntax) and defines the add, remove and replacement operations. It is used in CLUE Advertisement messages.
<!-- include patch-ops type definitions -->
<xs:include
schemaLocation="urn:ietf:params:xml:schema:patch-ops"/>
<!-- partial updates -->
<xs:element name="clue-info-diff">
<xs:complexType>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:choice>
<!-- add some content -->
<xs:element name="add">
<xs:complexType mixed="true">
<xs:complexContent>
<xs:extension base="add">
<xs:anyAttribute processContents="lax"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<!-- remove some content -->
<xs:element name="remove">
<xs:complexType>
<xs:complexContent>
<xs:extension base="remove">
<xs:anyAttribute processContents="lax"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<!-- replace some content -->
<xs:element name="replace">
<xs:complexType mixed="true">
<xs:complexContent>
<xs:extension base="replace">
<xs:anyAttribute processContents="lax"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<!-- allow extension elements from other namespaces -->
<xs:any namespace="##other" processContents="lax"/>
</xs:choice>
</xs:sequence>
<xs:attribute name="entity" type="xs:anyURI" use="required"/>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
</xs:element>
</xs:schema>
The XML below is also proposed for inclusion into the CLUE protocol. It includes the schema for XML patch operation errors from [RFC5261]. It is used in CLUE Advertisement ACK messages.
<!-- include patch-ops-error type definitions -->
<xs:include
schemaLocation="urn:ietf:params:xml:schema:patch-ops-error"/>
<!-- partial updates errors -->
<xs:element name="clue-info-diff-error">
<xs:complexType>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:choice>
<!-- add some content -->
<xs:element name="patch-ops-error">
<xs:complexType mixed="true">
<xs:complexContent>
<xs:extension base="patch-ops-error">
<xs:anyAttribute processContents="lax"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:attribute name="entity" type="xs:anyURI" use="required"/>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
</xs:element>
</xs:schema>
The use of the <add> element is as per section 4.3/[RFC5261] with the exception that the addition of attributes and namespaces is not supported. Thus the 'type' attribute is not supported.
Author's Note: Given the nature of the CLUE XML there doesn't seem to be a use case to update namespaces or attributes.
When inserting elements, the new nodes are described as they should appear in the CLUEinfo document with respect to the "sel" and any "pos" attribute.
The use of the <replace> element is as per section 4.4/[RFC5261].
When modifying elements the modified nodes must be specified as they should appear info the CLUE info document. The content-to-modify must include the element referenced by the xpath and any child elements. It will have the effect of completely replacing the previous setting of the element. Any child element present in the base document will be removed if not present in the content-to-modify. Any child element, not present in the base document but present in the content-to-modify will be added. XML attributes follow the same behaviour.
The use of the <remove> element is as per section 4.5/[RFC5261].
When parsing an Advertisement containing a partial update, the Media Consumer may detect an error in the partial update or may not be able to unambiguously apply the update. This may result in an error. In order to support error handling the <patch-ops-error> element should be included in the Advertisement Acknowledgement message.
This section describes the rules associated with partial updates to a CLUE Advertisement. Due to the structure of the CLUE data model there are dependencies between the different elements in the CLUE info document. These procedures are from a syntactic perspective and cover interactions between CLUEinfo elements. Various combinations of operations may or may not make sense from an application perspective, however the application perspective is out of scope of these procedures.
Firstly general rules are described that apply to all elements in the CLUEInfo. Procedures specific to the following top level elements are then described:
When adding a new element, any mandatory child elements must be included. For example: when adding a new media capture the <capturedMedia>, <captureSceneIDREF> and <encGroupIDREF> elements must be included in the partial update.
See the specific procedures for replacement in the clauses below.
The deletion of an element will have the effect of deleting all child elements.
A partial update may add additional <captureScene> elements to the <captureScenes> element. Additional <sceneEntry> elements may be added to the <sceneEntries> element. Additional media captures (<captureIDREF>) may be added to the <sceneEntry> element.
A partial update may modify the child elements of the <captureSceneType>. If the <sceneID> element is changed then any elements that reference the sceneID (e.g. by captureSceneIDREF in <mediaCaptureType> element) must also be changed in the partial update.
A partial update may remove a capture scene from an existing CLUEInfo description. If the sceneID of the deleted capture scene is used in other elements (e.g. by captureSceneIDREF in <mediaCaptureType>) then these elements must either be removed or the captureSceneIDRef must be changed to another existing capture scene identity in the partial update.
A partial update may delete a <sceneEntry> element. If the sceneEntryID is used in other elements (e.g. by sceneEntryIDREF in <globalCaptureEntryType> and <simultaneousSetType> then these elements must either be requested to be removed or the sceneEntryIDREF must be changed to another existing capture scene entry identity in the partial update.
A partial update may add additional captures may by specifying additional <mediaCaptureType> structures. The partial update must include the mandatory elements of the structure. Therefore the <captureSceneIDREF> elements must reference existing Capture Scenes or reference Capture Scenes being added in the partial update.
The addition of a new media capture may also require that the captureID is added to elements that reference media captures. For example: captureIDREF in the <contentType> (for multiple content captures), mediaCaptureIDs in the <sceneEntryType> element, captureIDREF in the <simultaneousSetType> element and IDREF in the <relatedTo> element. The addition of a mediaCapture may also result in a new <sceneEntry> element (see clause 3.2.1) and possibily an update of the <globalCaptureEntries> element being needed in the partial update.
If the new media capture contains a <capturedPeople> element containing <personIDREF> elements, the referenced <personID> must also be added to the <people> element if it has previously not been included.
Additional capture attributes may be added to existing media captures.
A partial update may modify the child elements of the <mediaCaptureType>. If the <captureID> element is changed then any elements that reference the captureID (e.g. by captureIDREF) must also be changed in the partial update.
If the partial update modifies the <capturedPeople> element then the <people> element may need to be updated. See clauses 6.3.1 and 6.3.3.
A partial update may remove a <mediaCapture> element. The captureID of the removed mediaCapture must also be removed from any elements that reference the captureID in the partial update. For example: captureIDREF in the <contentType> (for multiple content captures), mediaCaptureIDs in the <sceneEntryType> element, captureIDREF in the <simultaneousSetType> element and IDREF in the <relatedTo> element.
If the removed media capture contains a <capturedPeople> element containing <personIDREF> elements and the referenced <personID>s are not referenced by any other media capture, the referenced persons may removed from the <people> element.
An <encodingGroup> element may be added to without requiring modification to other top level elements. However if the encoding group is to be used by media captures, the encGroupIDREF of the added encoding group must be added to at least one media capture. Child elements of <encodingGroup> may be added without impact to other top level elements.
Note: The change of an encID may result an SDP Offer/Answer exchange modifying an encoding.
If the <encodingGroupID> attribute is modified then any media captures that reference the encodingGroupID (through the encGroupIDREF) must also be modified.
Note: The change of an encID may result an SDP Offer/Answer exchange modifying an encoding.
If an encodingGroup element is removed any media captures that reference the removed encodingGroup (through the encGroupIDREF element) must be modified to reference a new encoding group ID or the encoding group must be removed in the partial update.
Note: The removal of an encID may result an SDP Offer/Answer exchange removing an encoding.
Operations (Add, Replace, Remove) may be applied the <simultaneousSets> element without any impacts on other top level elements. Any referenced media captures or capture scene entries must exist.
Operations (Add, Replace, Remove) may be applied the <globalSceneEntries> element without any impacts on other top level elements. Any referenced capture scene entries must exist.
A new <people> element may be added without affecting other top level elements. However for the new element to be used by the receiver of the CLUE description the <personID> of the people defined in that element must be referenced by one or more media captures or capture scenes.
If the <personID> element is modified then any media captures that reference the participant (through the <capturedPeople> element) must also be modified.
If a <person> element or any instances of the <personType> element are removed then any media captures that reference the removed people (through the <capturedPeople> element) must be modified to remove the personID in question.
The following examples are based on partial updates to the sample XML file in clause 22/[I-D.ietf-clue-data-model-schema]. The changes are against the sample XML file. The changes are not cumulative across the examples.
A presentation video capture (VC5) is added to the conference for a document camera. As this doesn't share a co-ordinate space a new Capture scene (CS2) is added. The clue-info-diff indicates to add the new capture after media capture VC4. An existing encoding group is used. The new capture is also added to the simultaneous sets SS1 and SS2 as it may be used in conjunction with the other captures. The following shows the additions:
<clue-info-diff xmlns="urn:ietf:params:xml:ns:clue-info">
<add sel="clueInfo/captureScenes/captureScene[1]" pos="after">
<captureScene scale="unknown" sceneID="CS2">
<sceneEntries>
<sceneEntry mediaType="video" sceneEntryID="SE5">
<mediaCaptureIDs>
<captureIDREF>VC5</captureIDREF>
</mediaCaptureIDs>
</sceneEntry>
</sceneEntries>
</captureScene>
</add>
<add sel="clueInfo/simultaneousSets/simultaneousSet[1]/captureIDREF[1]"
pos="after">
<captureIDREF>VC5</captureIDREF>
</add>
<add sel="clueInfo/simultaneousSets/simultaneousSet[2]/captureIDREF[4]"
pos="after">
<captureIDREF>VC5</captureIDREF>
</add>
<add sel="clueInfo/mediaCaptures/mediaCapture[6]" pos="after">
<mediaCapture xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="videoCaptureType" captureID="VC5">
<capturedMedia>video</capturedMedia>
<captureSceneIDREF>CS2</captureSceneIDREF>
<encGroupIDREF>EG0</encGroupIDREF>
<individual>true</individual>
<description lang="en">document camera</description>
<presentation>image</presentation>
</mediaCapture>
</add>
</clue-info-diff>
The video captures VC3 and VC4 are no longer available. As a result the following must be removed from the CLUE information:
The following shows the partial update with the removal:
<clue-info-diff xmlns="urn:ietf:params:xml:ns:clue-info">
<remove sel="clueInfo/mediaCaptures/mediaCapture[5]">
<remove sel="clueInfo/mediaCaptures/mediaCapture[6]">
<remove sel="clueInfo/captureScene/sceneEntries/sceneEntry[2]">
<remove sel="clueInfo/captureScene/sceneEntries/sceneEntry[3]">
<remove
sel="clueInfo/simultaneousSets/simultaneousSet[1]/captureIDREF[1]">
<remove
sel= "clueInfo/simultaneousSets/simultaneousSet[2]/captureIDREF[3]">
<remove
sel="clueInfo/simultaneousSets/simultaneousSet[2]/captureIDREF[4]">
</clue-info-diff>
The video capture VC4 zooms in on a particular participant and no longer represents a zoomed out view. As a result the description of VC4 and the participants are changed.
The following shows the partial update with the change:
<clue-info-diff xmlns="urn:ietf:params:xml:ns:clue-info">
<replace sel="clueInfo/mediaCaptures/mediaCapture[6]/description">
<description lang="en">zoomed in view on ciccio</description>
</replace>
<replace sel= "clueInfo/mediaCaptures/mediaCapture[6]/capturedPeople">
<capturedPeople>
<personIDREF>ciccio</participantIDREF>
</capturedPeople>
</replace>
</clue-info-diff>
The authors believe that the use of partial updates is an efficient way of updating CLUE information minimising the amount of data that needs to be sent in an Advertisement. It is proposed to introduce partial Advertisements into the CLUE protocol.
This template was derived from an initial version written by Pekka Savola and contributed by him to the xml2rfc project.
It is not expected that the proposed changes present the need for any IANA registrations.
It is not expected that the proposed changes present any addition security issues to the current framework.
| [I-D.ietf-clue-data-model-schema] | Presta, R. and S. Romano, "An XML Schema for the CLUE data model", Internet-Draft draft-ietf-clue-data-model-schema-06, June 2014. |
| [I-D.ietf-clue-protocol] | Presta, R. and S. Romano, "CLUE protocol", Internet-Draft draft-ietf-clue-protocol-01, June 2014. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC5261] | Urpalainen, J., "An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors", RFC 5261, September 2008. |
| [RFC6502] | Camarillo, G., Srinivasan, S., Even, R. and J. Urpalainen, "Conference Event Package Data Format Extension for Centralized Conferencing (XCON)", RFC 6502, March 2012. |
| [RFC2629] | Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. |