RE: [API] Mistake on section 4.3.2.1

Regarding the DDWG DDR Simple API and the Java archive that is attached to the specification by way of an appendix:

It has been noted internally that the draft attached Java archive, which is intended to be a "compilable" version of the API specification (which itself uses Java fragments to describe the interface), is not consistent with the normative text of the specification. The group agreed that only the Java as it appears in the text of the document may be used normatively, therefore the referenced attachment is in error.

While the inconsistency introduces no functional deviation to known implementations, if one bases a Java implementation on the referenced Java files rather than on the normative specification itself, there will be a signature clash. This is obviously not in the best interest of developers.

For clarity, according to the API specification, there are four polymorphic methods of the Service interface in the DDR Simple API whose signatures are:

 - PropertyName    newPropertyName(...)    throws NameException
 - PropertyRef     newPropertyRef(...)     throws NameException
 - PropertyValues  getPropertyValues(...)  throws NameException
 - PropertyValue   getPropertyValue(...)   throws NameException

The referenced compilable Java archive deviates from the specification in that one of the forms of the getPropertyValues method does not declare that it may throw a NameException.

On the basis of the pre-eminence of the normative specification, coupled with the statement in the specification that reads "The DDR Simple API is available as a JAR file, and as Javadoc", the appropriate course of action is to correct the deviation by repairing the Java archive.

It is regrettable that this inconsistency was not noted during the LC period, but it is also fortunate that this did not affect the function of implementations that were demonstrated in support of the viability of the API. This good fortune arises because the method form in question is the only one which would not actually throw an exception in an actual implementation, even though the API permits it to do so.

I further regret that this correction may require those who have been working on Java implementations, in cooperation with the DDWG, to change a line of code. This only affects those who used the attached Java file rather than the normative specification itself. Nevertheless, for the inconvenience, I apologise.

Finally, I acknowledge that there is an argument for having polymorphic methods with differing outcomes, including the exceptions they may throw. The argument, while interesting, is academic. In the DDR Simple API agreed by the group, and as presented for possible Recommendation by W3C, all of the polymorphic methods have consistent outcomes. I believe this is in the spirit of "Simple", and I can say that in some non-Java languages this is beneficial. No doubt this will be something to consider in future evolutions of the API, and of any "advanced" successors.

Again, I apologise whole-heartedly for any inconvenience.

---Rotan. (Chair)









-----Original Message-----
From: public-ddwg-request@w3.org [mailto:public-ddwg-request@w3.org] On Behalf Of Rotan Hanrahan
Sent: 12 August 2008 18:02
To: JOSE MANUEL CANTERA FONSECA; public-ddwg@w3.org
Subject: RE: [API] Mistake on section 4.3.2.1


Thanks José,
 
However...
 
It will be observed that all of the polymorphic methods in the API differ only in their input parameters. This means the methods return the same data type and are capable of raising the same exceptions.
 
In the unique case of getPropertyValues(Evidence) this particular form of the polymorphic getPropertyValues method is technically permitted to raise the NameException but there are no circumstances in which doing so would be appropriate. However, to maintain the harmony with the rest of its siblings in the polymorphic set, it seems OK to leave it with the "throws NameException" signature.
 
A "fix" is unnecessary, assuming the design concept of polymorphism based solely on the input signature is accepted. But as this is a unique and unusual situation, it may be advised to document it in the implementation experience pages of the wiki. (This would also have the added benefit of avoiding any Process issues that would threaten to delay the specification.)
 
---Rotan.

________________________________

From: public-ddwg-request@w3.org on behalf of JOSE MANUEL CANTERA FONSECA
Sent: Tue 12/08/2008 08:53
To: public-ddwg@w3.org
Subject: [API] Mistake on section 4.3.2.1



Hi,

 

On the current editor's draft there is a mistake [1] :

 

public PropertyValues getPropertyValues(Evidence evidence)

       throws NameException;

 

getPropertyValues should not raise NameException as it retrieves all known properties in all vocabularies.

 

If would be good if it could be fixed before the PR publication

 

Best Regards

 

[1] http://www.w3.org/2005/MWI/DDWG/drafts/api/080602#sec-Service-getPropertyValues-1

Received on Friday, 15 August 2008 10:50:43 UTC