Hi Felix, On Mon, Nov 14, 2011 at 12:47 AM, Felix Meschberger <[email protected]> wrote: > Hi > > Thanks for pushing this. > > I am +100 for a WebConsole plugin (and config printer). Makes perfect sense > and probably is overdue. > > But: I feare we completely overdo it with the documentation of the adapters > provided by the Adaptable implementations themselves. > This is actually where I see the most need as most of the Adaptable implementations are non-exported implementation classes for which we don't generate JavaDoc.
> While the goal is noble and makes sense, we should really take care to not > overdo... > > Whatever mechanims we invent is potentially error prone and duplicating the > code in descriptive text is probably even wrong. I think it really suffices > it to know which adapters are supported. I'm not sure it is "duplicating the code" any more than JavaDoc is duplicating code. I do think we should make the "condition" optional and it shouldn't be populated unnecessarily. But looking at the documentation which Alex helped to author on the day.com site, there clearly is a need to capture some additional metadata about each adaptation. Regarding "error prone," while this is always true of documentation, I think keeping this type of metadata as close to the code as possible will lead to fewer errors. > > Creating a service to provide this information is definitely wrong -- and may > not even work. > > Adding a new service registration property describing the conditions or the > AdapterFactor might make sense, but this should really be descriptive and not > just formulating the Java Code -- but then service.description should maybe > suffice it.... This seems like a misuse of the service.description property. IMHO, it'd be better to have no condition than to have a bad/misleading condition. Justin > > Regards > Felix > > > Am 12.11.2011 um 02:55 schrieb Justin Edelson: > >> Working with new Sling developers, I find that one of the concepts >> they have trouble with is in the area of Adapters and that it is hard >> to find out what objects are adaptable to which classes. Although it >> is possible to document this (see for example >> http://dev.day.com/docs/en/cq/current/developing/sling-adapters.html), >> because new Adapters can be dynamically added (or removed) through >> OSGi services, any documentation is potentially incomplete. >> >> What I would like to do is create a new Web Console plugin which >> displays the list of available adaptation pairs. I'm still thinking >> about the UI, but you could imagine that a first version would be a >> select list on the left listing the adaptable classes and a list on >> the right of the possible adapters for the selected adaptable. >> >> For implementations of AdapterFactory, the necessary metadata already >> exists in the service registry, but for cases where a class implements >> its own adapters, this metadata needs to be added. >> >> In order to do this, I propose the following: >> 1) The creation of such a Web Console plugin (obviously). >> 2) The creation of new OSGi Services for classes which implement their >> own adaptations. For example: >> @Component >> @Service(value=Object.class) >> @Properties({ >> @Property(name="adaptables", >> value="org.apache.sling.api.resource.Resource"), >> @Property(name="adapters", value={ >> "javax.jcr.Node", >> "javax.jcr.Item", >> "java.io.InputStream", >> "java.net.URL", >> "java.util.Map", >> "org.apache.sling.api.resource.ValueMap" >> }) >> }) >> public class JcrNodeResourceAdapterMeta { } >> >> 3) The establishment of a new service property, named >> adapter.condition, which optionally indicates the conditions under >> which an adaptation can be made. For example, in the case above: >> @Property(name="adapter.condition", value="If the resource is a >> JcrNodeResource") >> >> The Web Console plugin would need to note that potentially not all >> adapters are listed, but I believe that if we add the metadata for all >> the adapters in Sling, that will set a good precedent for downstream >> projects to follow. If we want, we could also add a note which says >> "If there's an adapter not listed here, please file an issue with the >> adapter provider." :) >> >> Adding this metadata is not a trivial amount of effort, but it also >> something I feel will pay dividends down the road. >> >> WDYT? >> >> Justin > >
