Dear Wookie-Community, Unless I am mistaken, there seems to be a "semantic bug" in the connector framework (Java reference implementation): The method getOrCreateInstance takes a Widget-GUID (which is - as far as I understand - a String like "http://example.com/mywidget";) and should return a (maybe newly created) WidgetInstance object, i.e. a Java object, which should represent a WidgetInstance - not a Widget.
To create this WidgetInstance object, the method parseInstance is used. This method parses the XML returned by the Wookie server, which represents a WidgetInstance. However, when populating the properties of the object (instance of WidgetInstance) with values from the XML file, the parseInstance method applies the given Widget-GUID to the WidgetInstance.id property. Therefore, the current reference implementation creates instances of the WidgetInstance class, which hold the Widgets identifier instead of the WidgetInstance's identifier! (see: http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/java/src/org/apache/wookie/connector/framework/AbstractWookieConnectorService.java) Now that I have worked a bit with this code I have a two suggestions/thoughts, which I want to bring to discussion: * Treat the Java connector framework as part of the core * As far as I know, the connector frameworks - including the reference implementation - are considered to be provided by the community. Of course, this makes sense for an open source project. However, as the connector frameworks should serve as the starting point for new developers / Wookie integrators, I would suggest to treat *the one* reference implementation as "being part of Wookie core", which would mean that it gets polished upon releases, would stay up to date with the REST API etc... * Cleaning up the whole identifier mess by enforcing naming conventions * In Wookie (as in most software), a great number of different identifiers come into play. There are Widget GUIDs (i.e. URL-Strings), Wookie "internal" Widget IDs (i.e. integers), WidgetInstance identifiers (i.e. Strings), and so on. In variables names and in code comments, different names are used for the same concept. For example, the Widget GUID is often called "guid" in the documentation, but the XML (/wookie/widgets?all=true) uses "identifier" as attribute name - the Wookie internal id comes as "id" in this XML. The WidgetInstance XML (whose root element is called "widgetdata" instead of "widgetinstance" btw - any reason for that?) uses the element (not attribute, btw) "identifier", this identifier string is then applied to the WidgetInstances "id" (not "identifier") property by the connector framework. Of course, there is also the WidgetInstance's "url", which also somehow "uniquely identifies" a widget instance. This can result in confusion when working with the code - an evidence for this is for example, that the Ruby connector framework (in contrast to the PHP implementation, which follows the "semantic bug" of the Java version) does not use the identifier property provided by the WidgetInstance's XML at all (see: http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/ruby/wookie/WookieConnectorService.rb). Therefore, I would recommend to create a small set of "naming conventions" for those critical variable names, like "always call a widget's guid "widgetGuid" when writing code/documentation" or "never use the word "widget" when refering to a widget-instance"; and to do a small refactoring before the first Wookie release. Looking forward to see some of you in Bolton this week :-) Regards Michael
