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

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

1-20 21-29

question comments

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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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?; Related issues: 1969
(space separated ids); WG Notes: You could add a new aspect by creating a new vocabulary from scratch, or your new vocabulary could simply reference the original vocabulary. The introduction of a new aspect to a collection of properties may require you to identify new default aspects for (some) properties. In general, any addition of properties or aspects is in effect the introduction of a new vocabulary. An implementation is free to use more than one such vocabulary. Question: is this clarification required in the API text?; Resolution: 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.; (Please make sure the resolution is adapted for public consumption)

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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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?; Related issues: 1968
(space separated ids); WG Notes: The properties, aspects and values of a vocabulary are namespaced. The DDR API will not recognize property or aspect references that are not defined in an indicated vocabulary, and the API includes exceptions if one attempts to access an unknown property or aspect. There is no specific check on the values within an enumeration property. The enumeration may contain one or more of the values defined by the vocabulary in use, but additional values may also be returned. Any such values must be considered to be an implementation-specific extension. A more robust approach for the inclusion of additional permitted values in an enumeration is to define a new vocabulary which extends an existing vocabulary, by adding new values to the list of enumerable values. By way of illustration, the Core Vocabulary in section 3.2 states: "The enumerations described in this document contain initial values that should be supported by all implementations of the Core Vocabulary and which may be supplemented by further DDR specific values." May 5: we figured that the general question of extensible vocabulary mechanisms should best be handled as ongoing work of the UWA, as it's related to their ontology work.; Resolution: 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.; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: This is interesting feedback. The comment is incomplete: "Also the removal of the '-' will be more consistent with the ..." so we should perhaps seek clarification. If we dictate that "-" cannot be used, then we would need to review all possible symbols and produce an exclusion list. As this is intended to be language-neutral, such an exclusion list would be in contradiction to this intention. The names are merely strings, and any attempt to exclude specific characters could impose unnecessary restrictions. Perhaps it would be possible to use an alternative EL expresssion to avoid all reserved characters when dealing with strings from an enumerated value: <mymw:script sel="deliveryContext.scriptSupport['ecmascript-MP']" /> The alternative response is that we declare that only the characters A-Z, a-z, 0-9 and _ are acceptable, and that the initial character must not be a digit. This should ensure that the names are compatible with variable names in (almost) all programming languages. An upper value on the length of such strings would also be necessary. And then what about enumerations of things which may require special symbols (such as the list of MIME types, or the list of permitted values for the language attribute in a script tag?). Apart from making the Core Vocabulary invalid, such restrictions are simply impractical. Note: ensuring that the string values in enumerations could also be used as valid variable names in programming language expressions was not a design goal. We merely allowed these to be arbitrary strings, to provide the necessary flexibility in representing collections of values as strings.; Resolution: 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.; (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; Status:
assigned to Matt Womer; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; Comment:
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; Related issues: (space separated ids); WG Notes: This is a trivial, though correct, observation. The group should just resolve to accept and act upon the comment as is.; Resolution: The correction to the URL shall be made.; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: In the weekly call of 5 May, Jose indicated that this matter would only be requested if the spec was required to go into second Last Call, but that he "could live with not having these methods" if that would help keep the spec out of 2LC. As PropertyValues.getValue() requires a PropertyRef, you can use the convenience methods in Service to create that PropertyRef, so there's no loss of functionality by not having these convenience methods. We can expect that the response from the commenter to the (proposed) response from the group would indicate that the response is accepted, but it will be raised again if the spec goes to 2LC.; Resolution: 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().; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: http://lists.w3.org/Archives/Member/member-ddwg/2008May/0042.html Extract (from Rotan's original comments): First, we are providing a "simple" API, so it cannot be expected to be all-powerful and comprehensive, just sufficient to get the job done. So having a specific method for type reflection/inspection is not high up on the list of requirements. There is, however, a way of discovering the data type associated with a named property: read the corresponding vocabulary. However, the reading of the vocabulary is not automated, 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, and you might think that in this case you 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 recognise, 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 recognise, basing any adaptation on such data would be pointless, so we must assume that all you are doing in this case is creating a catalogue of the properties and values. A report, if you will. And for such reports it is generally sufficient just to have text representations of the values, which is exactly what we provide via the PropertyValue.getString() method (and we have explicitly stated that getString must give you a String representation if the datum is not natively a String). So I think 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.; Resolution: 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.; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: During the teleconference call on 5 May, Rotan noted that standard Java had a means of doing the contains() method via java.util.Arrays and so the convenience method is not necessary in the Simple API. More efficient methods could be provided in specific implementations, but we would consider those to be implementation-specific enhancements and beyond the scope of the *simple* API.; Resolution: 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.; (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...; Status:
assigned to Matt Womer; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: Resolution taken 21 April 2008: "Simplify getDataVersion to just mention returning of version of the data, and define a constant to indicate that the versioning of data is not supported, and do not mention SystemException." A reasonable name for the constant is NOT_SUPPORTED, and the most obvious value (following on from the existing __NULL) is "__NOT_SUPPORTED".; Resolution: 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.; (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; Status:
assigned to Ignacio Marin; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; Comment:
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; Related issues: (space separated ids); WG Notes: [RH] Actually, the easiest way to solve this issue is simply to note that the API does mention a threshold for exception codes, and that offering guidance on the creation of new codes is out of scope. If we set up a wiki page for developers later, we could offer some thoughts on this, perhaps along the lines that Nacho has written below. [/RH] It is true that the section on Exceptions needs to be refined as it seems to suggest that integer values for exception codes intend to be unique across all of the DDR Simple API exception classes, but there is no text indicating this. The comment leads to rethinking of the value codes proposed as examining them from the lowest value to the highest seem to show that there is not a clear order for the chosen exception codes. For example, codes 100 and 200 belong to the NameException class, 300 to InitializationError, 400 and 500 to SystemException, 600 belongs back to NameException and so on. A possibility for exception codes of the same exception class not being consecutive might be due to the use of flags in the binary representation of the codes, but this is not the case. So refactoring the exception codes, in order to guide developers extending the API when choosing custom integer values for exception codes, seems to be necessary. Two initial options are presented below: - The first one uses current exception codes, reordering them so codes corresponding to the same normative exception class are consecutive (while trying to keep the current defined codes as much as possible): Code Symbolic value Exception associated 100 PROPERTY_NOT_RECOGNIZED NameException 200 VOCABULARY_NOT_RECOGNIZED NameException 250 ASPECT_NOT_RECOGNIZED NameException 300 INITIALIZATION_ERROR InitializationException 400 ILLEGAL_ARGUMENT SystemException 500 CANNOT_PROCEED SystemException 600 INCOMPATIBLE_TYPES ValueException 900 NOT_KNOWN ValueException 10000 MULTIPLE_VALUES ValueException 65536 IMPLEMENTATION_ERROR DDRException After choosing this first option, each exception might be assigned codes from the lowest value used in previous table to the highest value preceding the lowest value of the next exception in the table. For instance, NameException would allow value codes between 100 and 299, the range of allowed values for InitializationException codes would be 300-399, 400 to 599 for SystemException, 600-10000 for ValueException. Values from 0 to 99 and between 10001 to 65535 would be reserved, while values higher than 65536 would be implementation specific. Anyway, a new choice of values would be reasonable in order to balance the range of codes for each exception. - The second option uses flags in the binary representation of the exception codes. This would lead to completely new codes for the exceptions but it would allow to apply masks to guess the meaning of new implemented exceptions and codes. On the other hand, it would be less clear to developers, as they would have to carefully examine the flags of the binary representation of codes in the DDR Simple API spec. Obviously, knowing that you have to define values in a range is easier and faster than dealing with binary flags. An initial proposal for this option might be: Bits 16, 15: 00 = Normative Exception (an exception already defined in the DDR Simple API spec) 01 = New code for a normative exception 10 = New non-normative exception inherited from DDRException. 11 = New non-normative exception inherited from SystemException. Bit 14: "Is a DDRException" flag. Bit 13: "Is a SystemException" flag. Bit 12: "Is an InitializationException" flag. Bit 11: "Is a NameException" flag. Bit 10: "Is a ValueException" flag. Bits 9-0: Specific reason of the exception. The activation of some flags would be exclusive. For example: 14 and 13 cannot be â€˜1â€™ at the same time. Only one of bits 10, 11 and 12 can contain a value of â€˜1â€™, with bit 14 containing a value of â€˜1â€™ at the same time. Of course, the particular meaning of each bit should be more clearly defined and discussed in the working group. No matter which option is chosen, the text in section 4.4 of the document should be refined. A resolution on which option is chosen by the group is pending in order to develop proper text in this section, indicating the uniqueness of codes and the rules to create new codes. [RH] One of the reasons for using bit fields is space and processing efficiency, which was relevant in the days when space and processing were scare resources. This is not true today, and it is generally accepted that sacrificing a little bit of space/processing efficiency in order to create clear and maintainable code is quite acceptable. Something along the lines of option 1 would therefore be indicated. [/RH]; Resolution: The API permits codes whose value is IMPLEMENTATION_ERROR+1 or higher to be used for implementation-specific purposes. These are the only code values that are permitted for such purposes. This information, already mentioned, addresses the comment. Guidance on the choice of values within the indicated range is out of scope for the API. The group resolves not to change the text.; (Please make sure the resolution is adapted for public consumption)

editorial comments

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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: RESOLUTION (28 April 2008): Remove "(DC)" and replace the subsequent DC with Delivery Context.; Resolution: 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.; (Please make sure the resolution is adapted for public consumption)

Comment LC-1958: Javadoc problems detected: Commenter: JosÃ© Manuel Cantera <jmcf@tid.es> on behalf of TelefÃ³nica I+D (archived message); Context: in; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; Comment:
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; Related issues: (space separated ids); WG Notes: We should take corrective action on the Java source code to ensure that it provides complete and consistent documentation. Missing descriptions for named parameters should always be provided. Corrective action includes new text for return value (based on suggestion in the comment): "an instance of PropertyValues containing PropertyValue objects representing all available values for the evidence supplied."; Resolution: The JavaDoc has been completed in line with this and other comments.; (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; Status:
assigned to Matt Womer; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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.; Related issues: (space separated ids); WG Notes: At a minimum, for the benefit of translators, the first occurrence of a word or fragment of text that is actually source code in some programming language should be marked as such. In some cases, there may be inflexibility in XMLSpec to allow the use of <code>, but at least in advance of such occurrences we should flag the word(s) as code. Matt has volunteered to scan through the XMLSpec to find all occurrences of code that can be marked as such.; Resolution: 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.; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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"; Related issues: (space separated ids); WG Notes: RESOLUTION (28 April 2008): Return all available Property values for all the Aspects and Vocabularies known by an implementation of the DDR Simple API.; Resolution: 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."; (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; Status:
assigned to Matt Womer; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: LC-1948
(space separated ids); WG Notes: Group resolution 21 April 2008: "We change the name of getAPIVersion to getImplementationVersion and include an explanation mentioning the use in diagnostics across all languages."; Resolution: The DDWG has resolved to change the name of getAPIVersion to getImplementationVersion and include an explanation mentioning the use in diagnostics across all languages.; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: RESOLUTION (28 April 2008): Section 1.2 text remains (with minor change DDR --> impls of DDR Simple API) as is, and "As mentioned in section 1.2, the DDWG strongly recommends that its Core Vocabulary is supported by all implementations of the DDR Simple API." in section 3. We noted that the piece in section 1.2 is about Scope, so moving it to section 3 would not be right. Repeating the recommendation to support the Core Vocabulary was considered to be OK, so that all of the guidance about the vocabulary would be in one place.; Resolution: 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."; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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" "; Related issues: (space separated ids); WG Notes: This is a "snafu". The comment is valid. RESOLUTION (28 April 2008): Valid comment. Reword to "webBrowser".; Resolution: The DDWG has resolved to correct the error and replace "Web browser" with "webBrowser".; (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; Status:
assigned to Jo Rabin; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; Comment:
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; Related issues: (space separated ids); WG Notes: 28 April 2008: Matt was actioned to look into LC-1977 re canonicalized IRIs. Jo observed that case-sensitivity and other representation issues could be involved, and that we might be better advised to leave such things unsaid in the spec. We are not sure if there is some official place we can reference. If so, we should reference it. If not, leaving it unsaid is perhaps the better course of action. Jo said he'd have to think about all this (but would need time). Kevin says: IRI canonicalization is also being looked at by POWDER: how to describe an IRI if it may have been punycoded for example. We have had help from public-i18n-core@w3.org , namely Eric Prud'hommeaux and Felix Sasaki. Take a look at http://lists.w3.org/Archives/Public/public-powderwg/2008Apr/0005.html ; I would suggest that the group defer to i18n core and reference their specs if possible.; Resolution: The issue of canonical representation of IRIs as strings is beyond the scope of the API. The specification indicates that the strings are representations of IRIs. Developers should seek elsewhere for guidance on such representations. The work of the W3C i18n group is one such source of guidance. The XML Namespace specification is already referenced in the API, and is another source of guidance.; (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; Status:
assigned to Rotan Hanrahan; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; Comment:
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; Related issues: (space separated ids); WG Notes: 4.2.3 Says: "Note that the value __NULL may be used where a Vocabulary does not support the concept of Aspect." 4.2.3.1(1) Says: "This value is used to support Vocabularies that do not distinguish Aspects." The text in section 3 might be reworded for clarity. Perhaps: "The name __NULL (whose value is the character sequence: '_','_','N','U','L','L') is reserved to represent the null Aspect, to be employed where a vocabulary does not use or distinguish Aspects of the properties defined by the vocabulary."; Resolution: The clarifying text proposed by the commenter, and based on an earlier proposal from the group, has been accepted and reads: "The value __NULL ('_','_','N','U','L','L') is reserved as the null Aspect, to be employed where a vocabulary does not use or distinguish Aspects of the properties it defines."; (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; Status:
assigned to Matt Womer; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; 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; Related issues: (space separated ids); WG Notes: The point of having a NULL_ASPECT was to allow for cases where the Aspect was not specified explicitly, and this included the absence of Aspect information in the vocabulary. It was generally accepted during our conference call of the 14th that it would be more correct to say that vocabularies *should* declare a default Aspect (because obviously vocabularies with no mention of Aspects at all will have no such declaration). In the case of Vocabularies without a mention of Aspects, the fallback is to use the null aspect, as suggested in the API doc. For anyone doing draft implementations, going from Must to Should won't break anything.; Resolution: The DDWG has resolved to accept use of the word "SHOULD" as described in the comment; (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; Status:
assigned to Jo Rabin; Type:; Resolution status:
Response drafted Resolution implemented Reply sent to commenter; Response status:
No response from Commenter yet Commenter approved disposition Commenter objected to disposition
Commenter's response (URI):; Comment:
Section 3 talks about vocabularies, however, it does not mention an essential thing about vocabularies which is

"Vocabularies are identified by IRIs"; Related issues: (space separated ids); WG Notes:; Resolution: Section 3 Vocabularies Current Text: Property and Aspect names must be unique in their namespace and must conform to the syntax defined in "Namespaces in XML" [XML Namespaces]. The value __NULL ('_','_','N','U','L','L') is reserved as the null Aspect name. Proposed Text: Vocabularies are identified by an IRI and provide a namespace for the Property Names and Aspect Names that compose them. The IRI that identifies the vocabulary also identifies its namespace. Property and Aspect names must be unique in their namespace and must conform to the syntax defined in "Namespaces in XML" [XML Namespaces]. The value __NULL ('_','_','N','U','L','L') is reserved as the null Aspect, to be employed where a vocabulary does not use or distinguish Aspects of the properties it defines.; (Please make sure the resolution is adapted for public consumption)

1-20 21-29

Add a comment.