You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by Justin Edelson <ju...@justinedelson.com> on 2011/11/12 02:55:19 UTC
[PROPOSAL] add Adapter Metadata services
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
Re: [PROPOSAL] add Adapter Metadata services
Posted by Justin Edelson <ju...@justinedelson.com>.
Hi Felix,
On Mon, Nov 14, 2011 at 12:47 AM, Felix Meschberger <fm...@adobe.com> 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
>
>
Re: [PROPOSAL] add Adapter Metadata services
Posted by Carsten Ziegeler <cz...@apache.org>.
2011/11/14 Felix Meschberger <fm...@adobe.com>:
> 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.
>
> 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.
>
> 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....
Yeah, while I a agree that maybe such a property would be sufficient,
the problem is that in some cases we don't have a service doing the
adaption - it's rather the data object itself, therefore we can't
simply add some service props
Regards
Carsten
>
> 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
>
>
--
Carsten Ziegeler
cziegeler@apache.org
Re: [PROPOSAL] add Adapter Metadata services
Posted by Felix Meschberger <fm...@adobe.com>.
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.
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.
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....
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
Re: [PROPOSAL] add Adapter Metadata services
Posted by Alexander Klimetschek <ak...@adobe.com>.
On 13.11.11 00:52, "Justin Edelson" <ju...@justinedelson.com> wrote:
>Indeed. I updated the gist to better reflect that situation. The idea
>is that the condition applies to that particular combination of
>adaptable/adapters, so in the case of InputStream (and
>PersistableValueMap), I broke those out into separate JSON objects.
>
>To be sure, I'm not confident we're going to be able to capture all
>the "condition" but I both think it is worth trying. I had thought of
>using a generic label like "notes" or "comments", but I think
>"condition" better identifies the content I think is most relevant.
What about this form, making use of Javascript objects:
{
"adaptables": "org.apache.sling.api.resource.Resource",
"adapters":[
"javax.jcr.Node": "If the resource is a JcrNodeResource",
"javax.jcr.Item": "If the resource is a JcrNodeResource",
"java.net.URL": "If the resource is a JcrNodeResource",
"java.util.Map": "If the resource is a JcrNodeResource",
"org.apache.sling.api.resource.ValueMap": "If the resource is a
JcrNodeResource",
"java.io.InputStream": "If the resource is a JcrNodeResource and
has a jcr:data property or in an nt:file node",
"org.apache.sling.api.resource.PersistableValueMap": "If the
resource is a JcrNodeResource and the user has set property privileges on
the node"
]
}
Cheers,
Alex
--
Alexander Klimetschek
Developer // Adobe (Day) // Berlin - Basel
Re: [PROPOSAL] add Adapter Metadata services
Posted by Justin Edelson <ju...@justinedelson.com>.
On Sat, Nov 12, 2011 at 9:00 AM, Alexander Klimetschek
<ak...@adobe.com> wrote:
> On 12.11.11 04:37, "Justin Edelson" <ju...@justinedelson.com> wrote:
>>https://gist.github.com/1359997
>>
>>WDYT?
>
> +1 for the overall concept, very useful (I know, since I once created that
> documentation reference you linked to ;-))
I probably should have given you credit :)
>
> One comment though: the "condition" isn't always valid for all adapters.
> Your example gist is a good case: the InputStream is only possible if that
> resource is a JCRNodeResource *and* an nt:file with binary content.
Indeed. I updated the gist to better reflect that situation. The idea
is that the condition applies to that particular combination of
adaptable/adapters, so in the case of InputStream (and
PersistableValueMap), I broke those out into separate JSON objects.
To be sure, I'm not confident we're going to be able to capture all
the "condition" but I both think it is worth trying. I had thought of
using a generic label like "notes" or "comments", but I think
"condition" better identifies the content I think is most relevant.
Justin
>
> Cheers,
> Alex
>
> --
> Alexander Klimetschek
> Developer // Adobe (Day) // Berlin - Basel
>
>
>
>
>
Re: [PROPOSAL] add Adapter Metadata services
Posted by Carsten Ziegeler <cz...@apache.org>.
2011/11/13 Justin Edelson <ju...@justinedelson.com>:
>
> I'm thinking JSON because this may end up being the same object
> structure which is consumed by the UI. Not sure yet...
ok
>
>>
>> What about adding support for this to some maven plugin, so we can
>> have an annotation somewhere in the java code and this file gets
>> generated?
>> The maven-sling-plugin looks like a good place to me.
>
> Sure, why not? I'm thinking the annotations should be in a separate
> module and not part of the api or adapters bundle. WDYT?
>
Yepp a separate module sounds good
Regards
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: [PROPOSAL] add Adapter Metadata services
Posted by Justin Edelson <ju...@justinedelson.com>.
On Fri, Nov 11, 2011 at 7:42 PM, Carsten Ziegeler <cz...@apache.org> wrote:
> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>> On Fri, Nov 11, 2011 at 7:16 PM, Justin Edelson
>> <ju...@justinedelson.com> wrote:
>>> On Fri, Nov 11, 2011 at 6:42 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>>>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>>>> A configuration printer is certainly an option, but I think the devs
>>>>> I've see run into this problem would be better served by something
>>>>> more interactive. So let's say both :)
>>>> +1
>>>>
>>>>>
>>>>> I'm not opposed to a metadata file, but the reason I prefer the
>>>>> service property method to a file in META-INF is that we can reuse the
>>>>> service properties from AdapterFactory implementations. The Web
>>>>> Console doesn't need to care whether the metadata is provided by a
>>>>> metadata provider service or an AdapterFactory service (or some other
>>>>> arbitrary service). See https://gist.github.com/1359911 for an example
>>>>> of the Web Console plugin I built as a POC.
>>>> Hmm, I'm not a fan of declaring a service just for the sake to provide
>>>> meta information :)
>>>> But we could use the annotations to just generate meta type info, by
>>>> just using the Component annotation with ds=false.
>>>
>>> That's worse IMHO. You convinced me - we should use a sidecar file.
>>
>> https://gist.github.com/1359997
>>
>> WDYT?
>
> Looks fine to me - not sure whether json or xml is better, but I'm
> fine with json :)
I'm thinking JSON because this may end up being the same object
structure which is consumed by the UI. Not sure yet...
>
> What about adding support for this to some maven plugin, so we can
> have an annotation somewhere in the java code and this file gets
> generated?
> The maven-sling-plugin looks like a good place to me.
Sure, why not? I'm thinking the annotations should be in a separate
module and not part of the api or adapters bundle. WDYT?
Justin
>
> Carsten
>>
>>>
>>> Justin
>>>
>>>>
>>>> Carsten
>>>>
>>>>>
>>>>> Justin
>>>>>
>>>>> On Fri, Nov 11, 2011 at 6:08 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>>>>>> Great idea and I'm definitely +1 on such a web console plugin. Not
>>>>>> sure if this is a web console plugin or a configuration status
>>>>>> renderer (we need the last one as well).
>>>>>>
>>>>>> I think instead of defining the additional metadata through the java
>>>>>> annotations with additional classes like the
>>>>>> JcrNodeResourceAdapterMeta in your example, what about having a meta
>>>>>> data file in META-INF of the bundle instead. I know its separate from
>>>>>> the java code though.
>>>>>>
>>>>>> Regards
>>>>>> Carsten
>>>>>>
>>>>>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>>>>>> 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
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Carsten Ziegeler
>>>>>> cziegeler@apache.org
>>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Carsten Ziegeler
>>>> cziegeler@apache.org
>>>>
>>>
>>
>
>
>
> --
> Carsten Ziegeler
> cziegeler@apache.org
>
Re: [PROPOSAL] add Adapter Metadata services
Posted by Carsten Ziegeler <cz...@apache.org>.
2011/11/11 Justin Edelson <ju...@justinedelson.com>:
> On Fri, Nov 11, 2011 at 7:16 PM, Justin Edelson
> <ju...@justinedelson.com> wrote:
>> On Fri, Nov 11, 2011 at 6:42 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>>> A configuration printer is certainly an option, but I think the devs
>>>> I've see run into this problem would be better served by something
>>>> more interactive. So let's say both :)
>>> +1
>>>
>>>>
>>>> I'm not opposed to a metadata file, but the reason I prefer the
>>>> service property method to a file in META-INF is that we can reuse the
>>>> service properties from AdapterFactory implementations. The Web
>>>> Console doesn't need to care whether the metadata is provided by a
>>>> metadata provider service or an AdapterFactory service (or some other
>>>> arbitrary service). See https://gist.github.com/1359911 for an example
>>>> of the Web Console plugin I built as a POC.
>>> Hmm, I'm not a fan of declaring a service just for the sake to provide
>>> meta information :)
>>> But we could use the annotations to just generate meta type info, by
>>> just using the Component annotation with ds=false.
>>
>> That's worse IMHO. You convinced me - we should use a sidecar file.
>
> https://gist.github.com/1359997
>
> WDYT?
Looks fine to me - not sure whether json or xml is better, but I'm
fine with json :)
What about adding support for this to some maven plugin, so we can
have an annotation somewhere in the java code and this file gets
generated?
The maven-sling-plugin looks like a good place to me.
Carsten
>
>>
>> Justin
>>
>>>
>>> Carsten
>>>
>>>>
>>>> Justin
>>>>
>>>> On Fri, Nov 11, 2011 at 6:08 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>>>>> Great idea and I'm definitely +1 on such a web console plugin. Not
>>>>> sure if this is a web console plugin or a configuration status
>>>>> renderer (we need the last one as well).
>>>>>
>>>>> I think instead of defining the additional metadata through the java
>>>>> annotations with additional classes like the
>>>>> JcrNodeResourceAdapterMeta in your example, what about having a meta
>>>>> data file in META-INF of the bundle instead. I know its separate from
>>>>> the java code though.
>>>>>
>>>>> Regards
>>>>> Carsten
>>>>>
>>>>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>>>>> 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
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Carsten Ziegeler
>>>>> cziegeler@apache.org
>>>>>
>>>>
>>>
>>>
>>>
>>> --
>>> Carsten Ziegeler
>>> cziegeler@apache.org
>>>
>>
>
--
Carsten Ziegeler
cziegeler@apache.org
Re: [PROPOSAL] add Adapter Metadata services
Posted by Alexander Klimetschek <ak...@adobe.com>.
On 12.11.11 04:37, "Justin Edelson" <ju...@justinedelson.com> wrote:
>https://gist.github.com/1359997
>
>WDYT?
+1 for the overall concept, very useful (I know, since I once created that
documentation reference you linked to ;-))
One comment though: the "condition" isn't always valid for all adapters.
Your example gist is a good case: the InputStream is only possible if that
resource is a JCRNodeResource *and* an nt:file with binary content.
Cheers,
Alex
--
Alexander Klimetschek
Developer // Adobe (Day) // Berlin - Basel
Re: [PROPOSAL] add Adapter Metadata services
Posted by Justin Edelson <ju...@justinedelson.com>.
On Fri, Nov 11, 2011 at 7:16 PM, Justin Edelson
<ju...@justinedelson.com> wrote:
> On Fri, Nov 11, 2011 at 6:42 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>> A configuration printer is certainly an option, but I think the devs
>>> I've see run into this problem would be better served by something
>>> more interactive. So let's say both :)
>> +1
>>
>>>
>>> I'm not opposed to a metadata file, but the reason I prefer the
>>> service property method to a file in META-INF is that we can reuse the
>>> service properties from AdapterFactory implementations. The Web
>>> Console doesn't need to care whether the metadata is provided by a
>>> metadata provider service or an AdapterFactory service (or some other
>>> arbitrary service). See https://gist.github.com/1359911 for an example
>>> of the Web Console plugin I built as a POC.
>> Hmm, I'm not a fan of declaring a service just for the sake to provide
>> meta information :)
>> But we could use the annotations to just generate meta type info, by
>> just using the Component annotation with ds=false.
>
> That's worse IMHO. You convinced me - we should use a sidecar file.
https://gist.github.com/1359997
WDYT?
>
> Justin
>
>>
>> Carsten
>>
>>>
>>> Justin
>>>
>>> On Fri, Nov 11, 2011 at 6:08 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>>>> Great idea and I'm definitely +1 on such a web console plugin. Not
>>>> sure if this is a web console plugin or a configuration status
>>>> renderer (we need the last one as well).
>>>>
>>>> I think instead of defining the additional metadata through the java
>>>> annotations with additional classes like the
>>>> JcrNodeResourceAdapterMeta in your example, what about having a meta
>>>> data file in META-INF of the bundle instead. I know its separate from
>>>> the java code though.
>>>>
>>>> Regards
>>>> Carsten
>>>>
>>>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>>>> 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
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Carsten Ziegeler
>>>> cziegeler@apache.org
>>>>
>>>
>>
>>
>>
>> --
>> Carsten Ziegeler
>> cziegeler@apache.org
>>
>
Re: [PROPOSAL] add Adapter Metadata services
Posted by Justin Edelson <ju...@justinedelson.com>.
On Fri, Nov 11, 2011 at 6:42 PM, Carsten Ziegeler <cz...@apache.org> wrote:
> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>> A configuration printer is certainly an option, but I think the devs
>> I've see run into this problem would be better served by something
>> more interactive. So let's say both :)
> +1
>
>>
>> I'm not opposed to a metadata file, but the reason I prefer the
>> service property method to a file in META-INF is that we can reuse the
>> service properties from AdapterFactory implementations. The Web
>> Console doesn't need to care whether the metadata is provided by a
>> metadata provider service or an AdapterFactory service (or some other
>> arbitrary service). See https://gist.github.com/1359911 for an example
>> of the Web Console plugin I built as a POC.
> Hmm, I'm not a fan of declaring a service just for the sake to provide
> meta information :)
> But we could use the annotations to just generate meta type info, by
> just using the Component annotation with ds=false.
That's worse IMHO. You convinced me - we should use a sidecar file.
Justin
>
> Carsten
>
>>
>> Justin
>>
>> On Fri, Nov 11, 2011 at 6:08 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>>> Great idea and I'm definitely +1 on such a web console plugin. Not
>>> sure if this is a web console plugin or a configuration status
>>> renderer (we need the last one as well).
>>>
>>> I think instead of defining the additional metadata through the java
>>> annotations with additional classes like the
>>> JcrNodeResourceAdapterMeta in your example, what about having a meta
>>> data file in META-INF of the bundle instead. I know its separate from
>>> the java code though.
>>>
>>> Regards
>>> Carsten
>>>
>>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>>> 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
>>>>
>>>
>>>
>>>
>>> --
>>> Carsten Ziegeler
>>> cziegeler@apache.org
>>>
>>
>
>
>
> --
> Carsten Ziegeler
> cziegeler@apache.org
>
Re: [PROPOSAL] add Adapter Metadata services
Posted by Carsten Ziegeler <cz...@apache.org>.
2011/11/11 Justin Edelson <ju...@justinedelson.com>:
> A configuration printer is certainly an option, but I think the devs
> I've see run into this problem would be better served by something
> more interactive. So let's say both :)
+1
>
> I'm not opposed to a metadata file, but the reason I prefer the
> service property method to a file in META-INF is that we can reuse the
> service properties from AdapterFactory implementations. The Web
> Console doesn't need to care whether the metadata is provided by a
> metadata provider service or an AdapterFactory service (or some other
> arbitrary service). See https://gist.github.com/1359911 for an example
> of the Web Console plugin I built as a POC.
Hmm, I'm not a fan of declaring a service just for the sake to provide
meta information :)
But we could use the annotations to just generate meta type info, by
just using the Component annotation with ds=false.
Carsten
>
> Justin
>
> On Fri, Nov 11, 2011 at 6:08 PM, Carsten Ziegeler <cz...@apache.org> wrote:
>> Great idea and I'm definitely +1 on such a web console plugin. Not
>> sure if this is a web console plugin or a configuration status
>> renderer (we need the last one as well).
>>
>> I think instead of defining the additional metadata through the java
>> annotations with additional classes like the
>> JcrNodeResourceAdapterMeta in your example, what about having a meta
>> data file in META-INF of the bundle instead. I know its separate from
>> the java code though.
>>
>> Regards
>> Carsten
>>
>> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>>> 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
>>>
>>
>>
>>
>> --
>> Carsten Ziegeler
>> cziegeler@apache.org
>>
>
--
Carsten Ziegeler
cziegeler@apache.org
Re: [PROPOSAL] add Adapter Metadata services
Posted by Justin Edelson <ju...@justinedelson.com>.
A configuration printer is certainly an option, but I think the devs
I've see run into this problem would be better served by something
more interactive. So let's say both :)
I'm not opposed to a metadata file, but the reason I prefer the
service property method to a file in META-INF is that we can reuse the
service properties from AdapterFactory implementations. The Web
Console doesn't need to care whether the metadata is provided by a
metadata provider service or an AdapterFactory service (or some other
arbitrary service). See https://gist.github.com/1359911 for an example
of the Web Console plugin I built as a POC.
Justin
On Fri, Nov 11, 2011 at 6:08 PM, Carsten Ziegeler <cz...@apache.org> wrote:
> Great idea and I'm definitely +1 on such a web console plugin. Not
> sure if this is a web console plugin or a configuration status
> renderer (we need the last one as well).
>
> I think instead of defining the additional metadata through the java
> annotations with additional classes like the
> JcrNodeResourceAdapterMeta in your example, what about having a meta
> data file in META-INF of the bundle instead. I know its separate from
> the java code though.
>
> Regards
> Carsten
>
> 2011/11/11 Justin Edelson <ju...@justinedelson.com>:
>> 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
>>
>
>
>
> --
> Carsten Ziegeler
> cziegeler@apache.org
>
Re: [PROPOSAL] add Adapter Metadata services
Posted by Carsten Ziegeler <cz...@apache.org>.
Great idea and I'm definitely +1 on such a web console plugin. Not
sure if this is a web console plugin or a configuration status
renderer (we need the last one as well).
I think instead of defining the additional metadata through the java
annotations with additional classes like the
JcrNodeResourceAdapterMeta in your example, what about having a meta
data file in META-INF of the bundle instead. I know its separate from
the java code though.
Regards
Carsten
2011/11/11 Justin Edelson <ju...@justinedelson.com>:
> 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
>
--
Carsten Ziegeler
cziegeler@apache.org