2LC comments on DCI

Hi Robin,

thank you for you comments:
http://lists.w3.org/Archives/Public/www-di/2006Sep/0000.html

referencing the 2nd last call of Delivery Context Interfaces (DCI)  
Accessing Static and Dynamic Properties:
http://www.w3.org/TR/2005/WD-DPF-20051111/

The groups responses have been broken-down (below) into sections for  
clarity.  The edits will be reflected in:
http://www.w3.org/2001/di/Group/di-dpf/DCI-CR.html

Cheers,

-Keith Waters


Berjon 1

Comment: Why have the nodeValue be the string "NULL" and not simply  
have the null value as is usually the case for Nodes that don't have  
a value? This breaks some assumptions that implementations can make  
and might increase footprint for no obvious (from reading the draft)  
gain.

Response: yes, this is an error and it has been corrected

Berjon 2a

Comment: The valueType attribute is open-ended in what it can contain  
but you don't describe how vendors should name their types, which in  
turn may lead to type name clashes. You should probably recommend  
that vendors name their extensions using IRIs (this doesn't mean you  
have to use IRIs yourselves, you can claim that you are the only  
source allowed to use plain strings).

Response: We recognize the need to for metadata ontology's and  
datatyping and the DIWG will cover this in detail in a future  
specification. In addition, Section 5.1.1 the text has been modified  
as follows:

To avoid name clashes the values for valueType should be a URI.

Berjon-2b

Comment: Also, why is this NULL (or null) for DCIComponents?

Response: DCIComponent doesn't have any of these and hence they are  
NULL.

Berjon-3

Comment: Same comments for propertyType and DCIMetaDataInterfaceType  
(for the latter, unless it is always a media type, in which case this  
should be specified).

Response: this cannot be done because DCI implementation cannot know  
what the metadata structure is.

Comment: While the "any" type *might* make sense for a value since it  
could be a simple value (e.g. an int) just as well as an object, is  
that the case for DCIMetaDataInterface? Wouldn't it always something  
more structured than a simple value, say at least a string?

Response: This cannot be done because DCI implementation cannot know  
what the metadata structure is.

Berjon-4

Comment: *Please* don't use null to indicate a wildcard for  
namespaceURI or propertyName. This is different from the way the DOM  
does it, and can cause confusion as to what describes properties in  
no namespace. Use the star instead ('*') as the other specificiations  
do.

Response: comment accepted and error corrected.

Berjon-5

Comment: Is there really a need to have both searchProperty and  
hasProperty when they are so close? Experience shows that as soon as  
you add a convenience method to an API, users will clamour for a  
zillion others such as searchForDogFoodProperty and  
getAnArmForAHandProperty. If convenience methods are needed, they are  
best introduced in a second version based on experience from what  
users find difficult to do (or what is inefficient to implement), as  
for instance DOM 3's textContent.

Response: The feeling in the group is that there is sufficient  
difference between the methods. The main reason is that hasProperty  
can terminate as soon as the first match is found. Search has to  
continue to find all possible occurrences. In addition there are use  
cases where knowing that a property exists is sufficient and the  
exhaustive search can be avoided.

Berjon-6b

Comment: There is confusion regarding what exceptions are to be  
raised, DOMException or DCIException. You can't reuse DOMException to  
add your own exception codes because that is highly likely to clash  
with future extensions to the DOM, therefore DOMExceptions must only  
be raised when an existing exception as specified in the DOM is  
raised, for all other uses a DCIException (which could wrap a  
DOMException) has to be used. It's unclear from the draft which is  
which. The IDL only ever mentions DOMException with values it doesn't  
have (and using the strange "raises(DOMException::FOO_ERR)" instead  
of just "raises(DOMException)" with the prose saying which codes may  
apply) and doesn't define DCIException (!) while other parts talk of  
DCIException. Please change the draft to define the latter and to use  
it when DOMExceptions don't apply.

Response: comment accepted. The specification has been amended so  
that a DCIException is defined and used by other methods.

Berjon-7

Comment: I have trouble understanding the relationship between a DCI  
DOM tree and a DOM tree representing an XML document. You extend Node  
directly, thereby creating new node types (which is a major issue, as  
future versions of the DOM itself may themselves need to add node  
types, in which case you would be clashing with them -- this is *not*  
a theoretical problem, you are already clashing with DOM 3 XPath) but  
you don't clearly define the behaviour of these nodes when other DOM  
operations are applied to them. What happens if someone tries to  
serialise that DOM? What are the nodeName, baseURI, attributes,  
childNodes, first/lastChild, next/previousSibling, ownerDocument,  
prefix, or textContent set to for DCI nodes? What happens if I try to  
append a DCI node as the child of an element or attribute node in the  
DOM, or vice-versa? What happens when I call cloneNode,  
compareDocumentPosition, getFeature, getUserData, isEqualNode,  
lookupPrefix, etc. on them? The DOM defines this for the types which  
inherit from Node, but you don't, which potentially opens the door to  
interoperability issues as much is left to implementations. I would  
recommend either a) clarifying the relationship to the DOM (which may  
constitute major work and is an error-prone process), b) removing the  
inheritance from Node (this requires checking that events would still  
work, but so long as you inherit from EventTarget I think you're  
fine), or c) defining the DCI tree as a tree of elements (which may  
never be serialised as XML), and therefore inheriting from Element  
(this has the advantage that they can be dumped as XML easily, but  
may have issues in that you would have to specify what happens if a  
DCI element is imported into another document). I think that option  
(b) is likely to be the one that will remove the largest set of  
issues with minimal work, especially since you don't seem to be  
making much use of the fact that you inherit from Node, apart from  
reusing a few fields.

Responses:

The DCI group see inheriting from the DOM to be the correct and valid  
approach for DCI. In particular we recongize the need to re-use the  
DOM to simplify the DCI implementations through the inheritance of  
the DOM node. As a result, the DCI interfaces are designed with the  
DOM as a key component and the DOM-tree structure to be familiar,  
minimal and re-usable for implementors.

To clarify we have added the following to the doc in Section  
4.1:Unless specifically stated otherwise the behaviour of DCI is the  
same as DOM.

In Section 7 (after the list of exceptions)The following text has  
been added to the doc:Importing, adopting and cloning DCI nodes is  
platform dependent and in general, authors should be careful when  
using these methods on a DCI property tree.

The degree of support for cloning, import and adopt methods on DCI  
nodes is vendor specific. If these methods are not supported  
implementations must raise the DOM exception 'NOT_SUPPORTED_ERROR'.

For behavior variance with DOM, please see section 7 Conformance  
where DCI behavior conflicts with that of DOM is specified. In all  
other cases, the DCI tree behave the same way as mentioned in DOM  
specification (mentioned in DCI specification - section 7).

Load and save is out of scope for this version of DCI. We anticipate  
addressing this topic in future DIWG work items.

We have added to the assumptions in Section 2: DCI represents the  
delivery context. The delivery context is separate from the document  
markup. The document originates with an author. The delivery context  
originates with the device, the network etc. DCI nodes are not  
intended to appear within document markup.

There is a relationship between markup documents and the delivery  
context. We will investigate this further in the context of DCI in  
future work.


Berjon-Editorial-1

Comment: Section 2 point 5 has "To be discussed 16th Sept f2f". I  
assume you don't want that in your CR document :)

Response: corrected.

Berjon-Editorial-2

Comment: Section 3 is a bit wooly, using terminology like "this will  
build upon the types defined by the W3C DOM working group" (is it not  
done already?) or "some of the common data types in the DOM  
include" (is the list exhaustive or not?). It would be best to make  
the list exhaustive so that implementers immediately know what they  
need to reuse from the DOM, even if the definitions for the types are  
left to another specification.

Response: Agreed. The list has been made exhaustive and the  
conformance section makes clearer the normative dependency to the DOM.
Berjon-Editorial-3

Comment: You define DOMString as "a Unicode string encoded with  
UTF-16". I would drop the "encoded with UTF-16" since while that's  
pretty much what the DOM and the IDL prescribe, it is something that  
language specific bindings typically override as an implementation  
detail (many languages map DOMString to their native string  
constructs, which are often in UTF-8 internally, even though they can  
always produce UTF-16 on request).

Response: document corrected.

Berjon-Editorial-4

Comment: This is unclear: "the DOM NodeList interface when used  
within the DCI context would return a DCIProperty instead of a DOM  
Node". I suppose that you mean that NodeList::item() returns a  
DCIProperty instead of a Node? That's somewhat wrong as in most  
languages that enforce some notion of typing it won't be possible to  
have that method return a type instead of another. I think you'd be  
better off saying that NodeList::item() must return Nodes that can be  
casted to DCIProperties, or something along those lines. Also,  
wherever that's the case it needs to be specified normatively (i.e.  
not in a sentence that starts with "for example").

Response: Agreed. The new sentence would be "Within the DCI context,  
the DOM Node that is returned through the DOM NodeList::item() method  
call should be interpreted as a DCIProperty". As for the example  
statement, we prefer to leave it as it is since the preceding  
statement clearly mandates viewing all DOM calls within DCI context.  
The sentence, even though normative by nature, is meant to highlight  
one of the many scenarios that could occur when using DOM calls  
within DCI context.
Berjon-Editorial-5

Comment: Unclear as well (in 4.1): "This is independent of the event  
propagation model in the host environment." I think you mean that if  
the host environment dispatches events through carrier pigeons and  
therefore only supports the "flying/cooing event propagation model"  
it still needs to support bubble/capture for DCI, but it could be  
expressed more clearly. Also, have you considered making the capture  
phase optional? Some other DOMs already do that (for instance the SVG  
MicroDOM). The capture phase adds implementation overhead for no  
obvious value (IMHO).

Response: What is meant through that sentence is that DCI has an  
independent event system that is not tied to the host platform i.e a  
the DOM document (xHTML for instance) would have its own event  
propagation system that is independent of DCI eventing. The DCI  
eventing is taken care of by the DCI platform.

Capture allows a listener to listen for property change events before  
the event hits the target node. If there are any problems with that  
then we can make it optional, but I don't see why we need to special  
case it if we have no problems. The more compliant we are the the DOM  
event propagation algorithm the better it is.

Berjon-Editorial-6a

Comment: You consistently use the word "metadata" (which seems fine  
to me) yet you called the corresponding interface  
"DCIMetaDataInterface", capitalising the 'D' which suggests that it's  
really "DCI Meta Data Interface". CamelCase is already somewhat hard  
to guess, especially for non native speakers, so being consistent and  
calling it "DCIMetadataInterface" is probably best.

Response: aggreed. document corrected.

Berjon-Editorial-6b

Comment: In some places you state that some attributes need to have  
the value NULL, where it's unclear whether that's the string  
"NULL" (as for nodeValue) or the null value. If the former then  
please consider using the latter instead, and if the latter then the  
normal way of flagging it in W3C specifications is to use null  
(lowercase).

Response: aggreed. document corrected.

Berjon-Editorial-7

Comment: 5.1.2.1 "This method is used to determine whether this  
property has a given named property". I find this quite hard to  
parse, maybe you should tag "in its descendants" at the end?

Response: aggreed. document corrected.

Berjon-Editorial-8

Comment: In 5.3, you seem to indicate that the version is a string  
that has to be "1.0" (for this version), entailing that "1", "1.0.0",  
etc. are invalid and compare differently. Experience shows that if  
you don't state this in excruciating detail people *will* get it  
wrong and perform numeric comparisons.

Response: aggreed. document corrected.
Berjon-Editorial-9

- In B.2 you use the text/javascript media type which is deprecated  
in favour of application/ecmascript. Also, there is no NULL object,  
just null (though since it hasn't been declared it'll resolve to  
null, but it's still bad practice). If the document intends to be  
XHTML (which it looks to be from the XMLDecl and the namespace) then  
it MUST include the relevant DOCTYPE (yes I know that's terrible, but  
complain to the HTML WG :). The second script element seems to add a  
listener to the head element, it's unclear to me that this element  
ever sees that event.

Response:

     * We left application/javascript in the example. The new media  
type is very new and browser implementations don't support it yet.
     * We changed NULL to null
     * We added the DOCTYPE
     * second script element: We have removed the appendix B.2

Berjon-Editorial-10

Comment: The ob-RFC2119 reference "In this document the key words  
must..." is placed in the introduction, which I assume to be  
informative. It might be best to place it in the conformance chapter.  
- You mention "cell phones", AFAIK this is an americanism to which  
the more generic "mobile phone" (or device) is generally preferred. -  
You talk of "URIs". The terminology this week is "IRIs". - When  
including a diagram, it's nice to also provide an SVG version. - "a  
NodeList with length attribute value of Zero": no need to capitalise  
Zero. - "If the return value is true, the node is included otherwise,  
the node is rejected" should be "If the return value is true the node  
is included, otherwise it is rejected."

Response:

     * The RFC2119 paragraph has been moved to the conformance section
     * instances of "cell phones" have been changed to "mobile phones"
     * The WG retained the use of URI. IRI is still recent and  
readers might not be familiar with the concept
     * SVG diagram: the WG doesn't feel that providing an SVG version  
is a necessity.
     * "Zero" has been uncapitalized.
     * The comma has been moved to before "otherwise"

Berjon-Q1

Comment: Do you plan on defining a metadata interface more completely  
in the future, or is that completely left up to other specifications?

Response: defining a metadata interface is outside DCI scope, we  
expect some other specification, or vendors to publish their metadata  
structures.
Berjon-Q2

Comment: It seems to me that using the IDL "any" type may cause  
compatibility issues with some languages, do you have a rationale for  
not using DOMObject there?

Response: we use "any" because DOMObject is only available in DOM  
Level 3. Therefore we kept "any", which we mapped to String or  
DOMObject, for DOM level 2 and 3 respectively.







______________________________________________________________________
This email has been scanned by the MessageLabs Email Security System.
For more information please visit http://www.messagelabs.com/email 
______________________________________________________________________