Re: Your comments on Device Description Repository Simple API ( LC-1971)

 Dear José Alberto Fernandez ,

The Mobile Web Initiative Device Description Working Group has reviewed
the comments you sent [1] on the Last Call Working Draft [2] of the Device
Description Repository Simple API published on 4 Apr 2008. Thank you for
having taken the time to review the document and to send us comments!

The Working Group's response to your comment is included below, and has
been implemented in the new version of the document available at:
http://www.w3.org/2005/MWI/DDWG/drafts/api/080525.

Please review it carefully and let us know by email at
public-ddwg-comments@w3.org if you agree with it or not before 5 June
2008. In case of disagreement, you are requested to provide a specific
solution for or a path to a consensus with the Working Group. If such a
consensus cannot be achieved, you will be given the opportunity to raise a
formal objection which will then be reviewed by the Director during the
transition of this document to the next stage in the W3C Recommendation
Track.

Thanks,

For the Mobile Web Initiative Device Description Working Group,
Matt Womer
W3C Staff Contact

 1.
http://www.w3.org/mid/3AAB09AEC806CB469174F8CC39E578180137AFDF@lonex01.Cellectivity.local
 2. http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/


=====

Your comment on 4.2.4 PropertyValue Interface:
> 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


Working Group Resolution (LC-1971):
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.


----

Received on Sunday, 25 May 2008 20:22:22 UTC