W3C

Disposition of comments for the Mobile Web Device Description Working Group

paged view

Not all comments have been marked as replied to. The disposition of comments is not complete.

In the table below, red is in the WG decision column indicates that the Working Group didn't agree with the comment, green indicates that a it agreed with it, and yellow reflects an in-between situation.

In the "Commentor reply" column, red indicates the commenter objected to the WG resolution, green indicates approval, and yellow means the commenter didn't respond to the request for feedback.

CommentorCommentWorking Group decisionCommentor reply
LC-1971 José Alberto Fernandez <alberto@cellectivity.com> on behalf of Cellectivity LTD (archived comment)
Hi,



I have been having some discussions with other members of the
wmlprogramming mailing list and after taking a look at the current draft
of the "Device Description Repository Simple API" I have found at least
on minor issue with the API as currently defined.



For what I have read, the API is lacking mechanisms to discover the
types and values of Properties. To make myself clear, on 4.2.4 it
states: "For the getString method implementations must return an
implementation dependent String representation if the type of the value
is not natively String." There are two readings to this sentence: (a)
Strings will be represented on the native string representation for the
specific language of the implementation; this sounds completely fine.
But another reading (b) would be that the string representation of the
values is dependant on each implementation; now this would mean one
implementation may "display" integer values as binary while another as
decimal or hexadecimal. One implementation may represent Boolean values
as "0"/"1" another as "false"/"true" or "no/yes". This of course would
diminish the usability of PropertyValue.getString() as a way to fetch
values in a universal manner.



This would be acceptable if there were a way to discover the type of
Properties. But there is none. 4.2.4.1 provides a mechanism to discover
if a Property exists, but no mechanism to interrogate what is the type
and hence what Retrieval method to use. It seems to me a way to discover
the type of a PropertyValue is needed either directly on PropertyValue
or as an attribute of PropertyRef:



int getPropertyType() : One of constants: LONG_VALUE,
DOUBLE_VALUE, STRING_VALUE, BOOL_VALUE, INT_VALUE, ENUMERATION_VALUE,
FLOAT_VALUE.



I am suggesting int constants to keep the API simple and compatible
across languages; as oppose to returning a instance of a Java Enum or
Class.



Notice that the DDR implementation itself has to know the type as
otherwise it would not be able to throw the expected exception in case
of error. But without this functionality at the API level there is no
way for programs using the API to do any kind of discovery.



Hopping you take my comments into concideration.



Regards,



Jose Alberto Fernandez

Cellectivity LTD
The DDWG is providing a "simple" API, so the expectation is for it to be sufficient to get the job done, and no more. So having a specific method for type reflection/inspection is not a major requirement. There is, however, a way of discovering the data type associated with a named property: by requiring that developers who use the properties in their code also read the corresponding published vocabulary.

Reading of the vocabulary is not an automated process because we don’t rely upon a machine-readable format. The vocabulary document identified by an IRI is actually written for humans. So when a human programmer writes a piece of code to query a datum from the repository, it is a requirement that the programmer has read the appropriate vocabulary document, and thereby ensured that the correct type is applied.

The only method that a programmer could use to retrieve properties in an arbitrary manner is Service.listPropertyRefs() which returns an array of PropertyRef objects. From those objects you can get the local names, aspects and namespace (IRI). From these names you can make arbitrary queries into the DDR. This use case may give the impression that one would not know the data types and run into the problem described by the commenter.

However, this is not the case. You have access to the IRIs so, for any IRIs that you recognize, you can determine the data types if you have previously encoded this information (in a table, for example). For any IRIs that you do not recognize, basing any adaptation on such data would be pointless. If the use case involves accessing properties that are not known in advance, then the use case is perhaps something like creating a catalogue of the properties and values for a report. For reports it is generally sufficient just to have text representations of the values, which is exactly what is provided via the PropertyValue.getString() method (and it is explicitly stated that getString must give you a String representation if the datum is not natively a String). To be clear: the output of getString() is not intended to be parsed.

So we believe this covers the requirement of a *simple* API. In essence, if you are a software developer who is querying properties from a known vocabulary, then you already know the names and data types of the properties, so you don’t need any additional means to determine types. Thus you would only use the getX() method for data of known type X, with no possibility of ambiguity. If you use getString() on data that is not natively a String type, then the resulting string should not be used as input for machine processing; it may be used for output intended to be read only by humans.
tocheck
LC-1954 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
The PropertyValue interface publishes the method "getEnumeration()" to deal with property values that are an enumeration of several values, such as image formats. If a content adaptation solution needs to check if a Delivery Context supports "gif" it will need to do the following:

PropertyValue val = service.getPropertyValue(evidence,"supportedImageFormats");

String[] imageFormats = val.getEnumeration();

gifSupported = false;

for(int j = 0; j < imageFormats.length; j++) {
if(imageFormats[j].equals("gif")) {
gifSupported = true;
}
}

As it is seen this is a very inconvenient way to do a more than common operation. Also it will force develoeprs to copy & paste this code over all the applications

Proposed Amendment:

+ Add a contains method on the PropertyValue interface that returns true or false depending on the values of the enumeration

boolean gifSupported = service.getPropertyValue(evidence,"supportedImageFormats").contains("gif");

José Manuel Cantera
Senior Technologist
Telefónica I+D
The DDR Simple API has been designed to be a fair balance between core/essential methods and common (convenience) methods, keeping in mind the power of established programming languages and libraries in which the implementations are expected to function.

In many expected implementation languages, including Java, there are standard libraries to perform the contains() method as described, which will suffice for the purpose of the Simple API. More complex (and potentially more efficient) methods may be considered by individual implementers but such features would be exposed as custom extensions, which would be outside the scope of this specification.
yes
LC-1955 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
Regarding the PropertyValues interface,

there are no convenience methods on that interface that allow to retrieve PropertyValues without dealing with a PropertyRef.

However the Service interface has a lot of convenience methods that avoid dealing with PropertyRef if necessary.

This seems to be a bit contradictory in the design of the API.

Proposed Amendment:

+ Add a getValue(localPropertyName) method
+ Add a getValue(localPropertyName,localAspectName,vocabularyIRI) method

to the PropertyValues interface

---

Jose Manuel Cantera
Senior Technologist

Telefónica I+D
The "convenience" methods of the DDR Simple API are contained within the Service interface, with which you may create the PropertyRef needed by the PropertyValues.getValue() method. There is no loss of functionality by not having a convenient version of getValue() in the PropertyValues interface.

A typical usage would be: pv.getValue(s.newPropertyRef("propName"))

Instances of PropertyRef created via the Service interface may be cached for subsequent use in calls to getValue().
yes
LC-1970 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
The value "ecmascript-MP" should be changed to ecmascriptMP.

Rationale:

In our implementation We have encountered problems with the '-' character as being interpreted as a minus sign by the JSP 2.0 E-L. evaluator in expressions like

<mymw:script sel="deliveryContext.scriptSupport.ecmascript-MP" />

Also the removal of the '-' will be more consistent with the

Sorry for not having spotted this before the publication of the Core Voc but we have suffered it today
The values in enumerated properties are represented as strings, with no restrictions on such values other than those naturally present in the String type. The use of such values as the names of variables or methods in any implementation was neither intended nor advised. As third-party vocabularies may enumerate other data that naturally contain punctuation (spaces, hyphens, slashes etc.) it would be unwise to introduce constraints on the format of the values. For example, a new custom vocabulary may enumerate supported MIME types, in which case the "/" character would likely be included in the enumerated values.

In the Core Vocabulary that accompanies the DDR Simple API, the values present in enumerated properties are simply those that were proposed and agreed by the group at the time. No pattern to these values was intended or required. The absence of spaces in the values is merely coincidental. Implementers are free to create their own vocabularies and adopt whatever conventions they feel are appropriate for their own enumerated values. The DDWG's core vocabulary has already been published as a WG Note and will remain as published. Any change to this document would require republication and thus a new namespace, which would introduce unnecessary confusion. The group therefore declines to change the published vocabulary.

Regarding the sample expression provided in the comment, it is recommended that the expression be re-constructed so that the 'ecmascript-MP' part is passed as a String value.

The group appreciates the opportunity to highlight this implementation consideration as part of this response to the comment, and will consider the creation of a wiki article containing similar advice to implementers.
yes
LC-1956 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
Regarding the method getDataVersion of the Service interface,

It is said

"Returns information about the underlying data (values for Properties) if the implementation has a versioning system for that information. If it does have a versioning system for data then this value must change between calls if the implementation can not guarantee that the data is the same. If the implementation does not support versioning of data then a SystemException should be thrown."

In the description of the method the word "if the implementation ..." appears in several occasions. This is a signal of a method that can be specific for some implementations but unneeded for others. Besides, it can be very hard to figure out if the underlying data has changed, for example if there are frequent updates to a database behind a DDR. Additionally there is no point knowing the data version as whole as it does not provide any kind of valuable information to the user of the API.

Proposed Amendment:

+ Remove the getDataVersion method of the Service interface
The DDWG has resolved to simplify the getDataVersion description to say only that when the method is invoked it will return the version of the device description data or a particular constant value (to be defined in the specification), which would indicate that versioning of the data is not supported. There will be no specific mention of throwing a SystemException since such exceptions may be thrown by any method. yes
LC-1957 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
Regarding the method

Service.newHttpEvidence(Map<String,String>)

this method will force implementations of the DDR Simple API to execute on Java 1.5 and above.
This fact will avoid existing solutions deployed on Java 1.4 to migrate to the DDR Simple API. As sometimes in production environments it is difficult to do a migration due to dependencies with legacy applications, sys admin policies, etc, etc, this seems to be a critical issue. That's because we are requesting to change it to newHttpEvidence(Map)

Proposed Amendment

+ Change Service.newHttpEvidence(Map<String,String>) to Service.newHttpEvidence(Map)

In the description of the method it should be said that implementations must iterate over the keys of the map calling the toString method to obtain the header names, and must iterate over the values of the map calling the toString method to obtain the header values.
The specification references the most current version of Java where Map is qualified with the types involved in the mapping. We take on board that many readers of the specification will be working with older Java versions, so we propose to add some additional guidance for implementers to say that "in the case of implementation environments where the default Map is from Object to Object, such as in Java 1.4, the key and value parameters should be cast to String". yes
LC-1959 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
This is an editorial comment:

+ Check the use of <code> when referring to non-translatable terms in the text:

- For example in 3. Vocabularies, when boolean, int, etc. are mentioned
- For example, in 4.4.2 "SystemException" should be put between <code> tags.
Insofar as the original document in XMLSpec permits, from which the XHTML version is derived, the first occurrence of words that are fragments of programming source code shall be marked as such. The editors shall make their best effort to also mark all subsequent occurrences. yes
LC-1962 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
This is an editorial comment:

The current documentation of the method

public PropertyValues getPropertyValues(Evidence evidence) throws NameException; says

"Return all Available Values" which is not very clear

Proposed Amendment:

"Return all available property values for all the aspects and vocabularies known by a DDR"
The DDWG has resolved to update the text to say: "Return all available Property values for all the Aspects and Vocabularies known by an implementation of the DDR Simple API." tocheck
LC-1964 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
This is an editorial comment

When in section 1.2 it is said

"For example, the Core Vocabulary [Core Vocabulary]<http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#CORE-VOCAB> recognises the Aspects of "device" and "Web browser" " It should say

"For example, the Core Vocabulary [Core Vocabulary]<http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#CORE-VOCAB> recognises the Aspects "device" and "webBrowser" "
The DDWG has resolved to correct the error and replace "Web browser" with "webBrowser". tocheck
LC-1965 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
This is an editorial comment:

+ Acronyms should be used consistently through the text

For example in Section 1.2 the acronym DC, Delivery Context is introduced. However the acronym DC should have been introduced earlier in the document, on section 1.1, once the term "Delivery Context" is first mentioned.

The same applies with other acronyms that might appear on other parts of the doc
The DDWG has resolved to remove the "(DC)" in section 1.2 and to replace the subsequent mention of "DC" with "Delivery Context".

The editors will review other occurrences of acronyms to ensure they are introduced and defined appropriately.
tocheck
LC-1967 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
This is an editorial comment:

In Section 1.2 it is said:

"The DDR Simple API does not define any Properties and does not mandate the use of any particular Vocabulary of such Properties.
The DDWG strongly recommends that its Core Vocabulary is supported by all DDRs."

Also in Section 3 it is said

"The DDWG has published a suggested "Core" Vocabulary for essential Properties for Web content adaptation [Core Vocabulary]<http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#CORE-VOCAB>. It is anticipated that implementations will extend the Core Vocabulary, which may be used as an example for such extensions. Properties that extend the Core Vocabulary must be in a different namespace to the Core Vocabulary."

----------

Proposed Amendment:

We suggest to merge Section 1.2 paragraph with Section 3 paragraph, saying

"The DDWG has published a suggested "Core" Vocabulary for essential Properties for Web content adaptation [Core Vocabulary]<http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#CORE-VOCAB>. Implementations should support this vocabulary. Additionally, It is anticipated that implementations will extend the Core Vocabulary, which may be used as an example for such extensions. Properties that extend the Core Vocabulary must be in a different namespace to the Core Vocabulary."

The above text will be in section 3
The DDWG has resolved to keep the text in section 1.2, with a minor change to replace "DDRs" with "implementations of the DDR Simple API", and in section 3 to add the following text: "As mentioned in section 1.2, the DDWG strongly recommends that its Core Vocabulary is supported by all implementations of the DDR Simple API." tocheck
LC-1968 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
If an implementation decides to add an additional aspect to the Core Vocabulary, for example, "deliveryContext" how it could be done?

Should the implementation define its own namespace and then duplicate all the Core properties to support this new aspect?
The introduction of new properties, new aspects or new values for enumerations constitutes the creation of a new vocabulary. It is possible for a vocabulary to reference a previous version (to avoid having to redefine all of the properties/aspects/values), but this does not avoid the requirement for the new vocabulary to have a separate namespace. An implementation may support multiple vocabularies, and this is supported by the API, so it is permitted for extended vocabularies to co-exist with their predecessors without causing confusion.

In general, the design and implementation of extensible vocabularies is an open and ongoing issue, which in conjunction with the design of an ontology of the delivery context is something that the DDWG will be deferring to the UWA Working Group. Meanwhile, the mechanism described above will suffice for the DDR Simple API.
yes
LC-1969 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
If an implementation decides to add an additional value to an enumerated property, such as supportedImageFormats, that new value will be in the same namespace as the Core Voc or in another namespace?

How a call from the API will note this fact, as the set of values in an enumeration are represented as non-namespaced Strings?

How collisions between values are going to be avoided?
The introduction of new properties, new aspects or new values for enumerations constitutes the creation of a new vocabulary. It is possible for a vocabulary to reference a previous version (to avoid having to redefine all of the properties/aspects/values), but this does not avoid the requirement for the new vocabulary to have a separate namespace. An implementation may support multiple vocabularies, and this is supported by the API, so it is permitted for extended vocabularies to co-exist with their predecessors without causing confusion.

Only the values of enumeration types as listed in a vocabulary are associated with the namespace. Additional values may be permitted by an implementation, but if avoidance of value clashes is necessary then the introduction of new vocabularies to include such new values is advised.

In general, the design and implementation of extensible vocabularies is an open and ongoing issue, which in conjunction with the design of an ontology of the delivery context is something that the DDWG will be deferring to the UWA Working Group. Meanwhile, the mechanism described above will suffice for the DDR Simple API.
yes
LC-1973 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
Regarding section 3 Vocabularies it is said,

"Vocabularies also define the data types of values associated with their Properties. The data types supported are boolean, int, long, float, double, String and String[]"

It should said clearly that String[] is used to represent enumerations ...
The DDWG has resolved to change the list of data types so that it now reads: "boolean, int, long, float, double, String and for enumeration, String[]". tocheck
LC-1974 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
Regarding the getAPIVersion method and provided that the method is not finally removed,

It should be differentiated between the version of the API and the version of the implementation.

As this method returns information about the version of the implementation, it should be called "getVersion" and not getAPIVersion.

Proposed amendment:

Rename getAPIVersion to getVersion()

======
Follow up from Commenter: http://lists.w3.org/Archives/Public/public-ddwg-comments/2008Apr/0052.html

Regarding the getAPIVersion() method,

What are the envisioned use cases for that method?

Proposed amendment

If there are no relevant use cases for the method, it should be removed
The DDWG has resolved to change the name of getAPIVersion to getImplementationVersion and include an explanation mentioning the use in diagnostics across all languages. tocheck
LC-1975 José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived comment)
This is an editorial comment,

The reference to the XML Namespaces spec is obsolete

It points to http://www.w3.org/TR/1999/REC-xml-names-19990114/

However it should point to:

http://www.w3.org/TR/REC-xml-names

The same occurs when the NC-Name syntax is referenced on section 3 (http://www.w3.org/TR/1999/REC-xml-names-19990114/#NT-NCName)
The group shall amend the URL reference to the XML Namespaces specification. It shall now link to http://www.w3.org/TR/2006/REC-xml-names-20060816/ tocheck
LC-1948 Rotan Hanrahan <rotan.hanrahan@mobileaware.com> on behalf of MobileAware (archived comment)
Regarding the getAPIVersion() method, described here:

http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#sec-Service-getAPI
Version

The definition says:

"Returns information about the implementation of the API including the
current version."

Our development team wish to know if this information is intended to be
machine readable. In the absence of a statement to this effect, the only
valid interpretation is that the returned String is intended to be read
by a human, presumably for diagnostics purposes.

Proposed amendment:

The team also notes that in addition to getting diagnostic information
about the API implemented by an instance, it may also be of benefit to
get a machine-readable indication of the API to which the implementation
claims conformance. The proposal is to add a method:

Public String getAPINamespace();

In the case of this API, the returned value would be:

"http://www.w3.org/TR/DDR-Simple-API/"

On behalf of MobileAware Ltd, Development Team,

Dr Rotan Hanrahan
Chief Innovations Architect
MobileAware
The DDWG has resolved to change the name of getAPIVersion to getImplementationVersion and include an explanation mentioning the use in diagnostics across all languages. yes
LC-1949 Rotan Hanrahan <rotan.hanrahan@mobileaware.com> on behalf of MobileAware (archived comment)
In the DDR Simple API published draft:

http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#sec-PropertyRef

it is said that:

"Note that the value __NULL may be used where a Vocabulary does not
support the concept of Aspect."

and with respect to the NULL_ASPECT it is also said that:

"This value is used to support Vocabularies that do not distinguish
Aspects."

However, in section 3 on Vocabularies:


"http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#sec-vocabularies"

it is said that:

"Vocabularies *must* declare a default Aspect for each Property [...]"

This seems to be contradictory to the earlier text. If the DDR Simple
API supports the concept of a Null Aspect for use in cases where the
vocabulary does not provide (complete) information on Aspects, then it
has been conceded that it is permitted for such vocabularies to be used.

Proposed remedy:

Change the text in section 3 to say:

"Vocabularies *should* declare a default Aspect for each Property
[...]"

On behalf of MobileAware Ltd, Development Team,

Dr Rotan Hanrahan
Chief Innovations Architect
MobileAware
The DDWG has resolved to accept use of the word "SHOULD" as described in the comment yes
LC-1950 Rotan Hanrahan <rotan.hanrahan@mobileaware.com> on behalf of MobileAware (archived comment)
The DDR Simple API requires that Vocabularies indicate the default
Aspect to be used for properties therein (presumably only applicable
when a Property can have more than one Aspect). The document contains a
link to:

http://www.w3.org/TR/ddr-core-vocabulary/

It is observed that this referenced document does not, at present,
adhere to the requirement specified in the DDR Simple API and is
therefore an invalid reference.

The development team request information from the DDWG as to its
intentions to update the published vocabulary to be in compliance with
the DDR Simple API, or if the DDR Simple API intends to reference
another document.

Proposed remedy:

The DDWG should publish an update of the Core Vocabulary, and the DDR
Simple API should link to it via a dated URL.

On behalf of MobileAware Ltd, Development Team,

Dr Rotan Hanrahan
Chief Innovations Architect
MobileAware
The DDWG resolved to publish an update of the Core Vocabulary, and update the reference to it in the DDR Simple API via a dated URL. yes

Developed and maintained by Dominique Hazaël-Massieux (dom@w3.org).
$Id: doc.php,v 1.36 2014-02-19 08:10:56 dom Exp $
Please send bug reports and request for enhancements to w3t-sys.org