2LC comments on DCI

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

2LC comments on DCI

waters Keith
Hi Robin,

thank you for you comments: 

referencing the 2nd last call of Delivery Context Interfaces (DCI) Accessing Static and Dynamic Properties:

The groups responses have been broken-down (below) into sections for clarity.  The edits will be reflected in:

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=2ÿ