W3C

List of comments on “Device Description Repository Simple API” (dated 4 April 2008)

Quick access to

There are 29 comments (sorted by their types, and the section they are about).

1-20 21-29

question comments

Comment LC-1969: Adding to enumerations in a vocabulary
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 3 Vocabularies
assigned to Rotan Hanrahan
Resolution status:

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?
1968
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1968: Adding aspects to a vocabulary
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 3 Vocabularies
assigned to Rotan Hanrahan
Resolution status:

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?
1969
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

general comment comments

Comment LC-1970: Avoid hyphen in names
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 3 Vocabularies
assigned to Rotan Hanrahan
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

typo comments

Comment LC-1952: Correct URL needs ending "/"
Commenter: Rotan Hanrahan <rotan.hanrahan@mobileaware.com> on behalf of MobileAware (archived message)
Context: Document as a whole
assigned to Matt Womer
Resolution status:

The document contains the following URL:

http://www.w3.org/TR/2005/WD-di-gloss-20050118

The correct URL in the document should be:

http://www.w3.org/TR/2005/WD-di-gloss-20050118/

Note the trailing "/". This is to avoid a redirect from the version of
the URL that does not end in "/".

All other links in the document have been checked, and found to be
correct.

On behalf of MobileAware Ltd, Development Team,

Dr Rotan Hanrahan
Chief Innovations Architect
MobileAware
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

substantive comments

Comment LC-1955: Convenience methods on PropertyValues
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 4.2.4 PropertyValue Interface
assigned to Rotan Hanrahan
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1971: Discovery of types
Commenter: José Alberto Fernandez <alberto@cellectivity.com> on behalf of Cellectivity LTD (archived message)
Context: 4.2.4 PropertyValue Interface
assigned to Rotan Hanrahan
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1954: PropertyValue and Enumerations
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 4.3.2 Query Methods
assigned to Rotan Hanrahan
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1956: getDataVersion method
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: Get Data Version public String getDataVersion(); Returns...
assigned to Matt Womer
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1951: Reserved code numbers
Commenter: Rotan Hanrahan <rotan.hanrahan@mobileaware.com> on behalf of MobileAware (archived message)
Context: 4.4 Exceptions
assigned to Ignacio Marin
Resolution status:

In the DDR Simple API Exceptions:

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

several integer values are defined to represent status or cause of
exceptions. The following numbers are observed (in the following order):

500, 400, 65536, 300, 100, 800, 200, 900, 600, 10000.

On behalf of our development team, here is a question relating to these
integers:

Are these integer values intended to be unique across all of the DDR
Simple API exception classes? If so, then implementations that extend
the API will require guidance on the choice of custom integer values for
exception codes. Such extensions are anticipated in the text of section
4.4.

Proposed remedy:

State in the specification that exception codes below "some number" are
reserved for this and future editions of this specification, and that
numbers above "some number" are recommended for custom implementations
that extend this specification.

On behalf of MobileAware Ltd, Development Team,

Dr Rotan Hanrahan
Chief Innovations Architect
MobileAware
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

editorial comments

Comment LC-1958: Javadoc problems detected
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: in
assigned to Rotan Hanrahan
Resolution status:

Regarding http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/JavaDoc/ the following problems have been detected

-> Interface DDRException

* "code" field description is empty

-> PropertyValues<http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/JavaDoc/org/w3c/ddr/simple/PropertyValues.html> getPropertyValues(Evidence<http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/JavaDoc/org/w3c/ddr/simple/Evidence.html> evidence)

the "returns" section has a wrong description. It should say "Returns all available values for the evidence supplied"

-> PropertyRef newPropertyRef(String localPropertyName) throws NameException.

"localPropertyName" parameter description is empty

-> PropertyRef newPropertyRef(PropertyName propertyName) throws NameException

"propertyName" parameter description is empty

-> PropertyRef newPropertyRef(PropertyName propertyName, String

localAspectName) throws NameException.



"propertyName", "localAspectName" parameters description are empty
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1959: Use of <code> to delimit non-translatable terms
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: Document as a whole
assigned to Matt Womer
Resolution status:

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.
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1974: getAPIVersion, rename or remove
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: in
assigned to Matt Womer
Resolution status:

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
LC-1948
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1962: 4.3.2.1 Making text more clear (re Available Values)
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: in
assigned to Rotan Hanrahan
Resolution status:

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"
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1965: Use acronyms consistently through the text
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: Document as a whole
assigned to Rotan Hanrahan
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1964: Aspects of the Core Voc in Section 1.2
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 1.2 Scope
assigned to Rotan Hanrahan
Resolution status:

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" "
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1967: Reference to the Core Vocabulary unified in section 3
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 1.2 Scope
assigned to Rotan Hanrahan
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1976: DDR Simple API - Vocabularies
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 3 Vocabularies
assigned to Jo Rabin
Resolution status:

Section 3 talks about vocabularies, however, it does not mention an essential thing about vocabularies which is

"Vocabularies are identified by IRIs"
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1949: Requirement for support of Aspect in vocabularies
Commenter: Rotan Hanrahan <rotan.hanrahan@mobileaware.com> on behalf of MobileAware (archived message)
Context: 3 Vocabularies
assigned to Matt Womer
Resolution status:

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
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1966: null aspect name clarification
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 3 Vocabularies
assigned to Rotan Hanrahan
Resolution status:

Regarding Section 3, Vocabularies, it is said

"Property and Aspect names must be unique in their namespace and must conform to the syntax<http://www.w3.org/TR/1999/REC-xml-names-19990114/#NT-NCName> defined in "Namespaces in XML" [XML Namespaces]<http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/#ref-Namespaces>. The value __NULL ('_','_','N','U','L','L') is reserved as the null Aspect name."

What is the null aspect name? Under which conditions it should be used?

The document should clarify
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Comment LC-1977: Vocabulary IRIs clarification
Commenter: José Manuel Cantera <jmcf@tid.es> on behalf of Telefónica I+D (archived message)
Context: 3 Vocabularies
assigned to Jo Rabin
Resolution status:

It could be good for the benefit of implementors, a clarification about how vocabularies IRIs are going to be treated.

Particularly things like case-sensitiveness could cause trouble

Proposed amendment: Reference normatively XML Namespaces Spec and in particular Section 2.3 of that spec
(space separated ids)
(Please make sure the resolution is adapted for public consumption)

1-20 21-29

Add a comment.


Developed and maintained by Dominique Hazaël-Massieux (dom@w3.org).
$Id: Overview.php,v 1.46 2013-10-04 08:11:33 dom Exp $
Please send bug reports and request for enhancements to w3t-sys.org