| [platform-ui-dev] Eclipse Neon M6 - User Experience with DS annotations |
Hi,
I just downloaded Neon M6 and tested the newly added DS annotations. It works pretty good, but there are some remarks about user experience. I think when we add that feature, it should have a good usability so users really like it.
I would like to discuss that first here before creating tickets, so we have a common feeling about the usability. Not sure if Plaform UI is the correct receiver, but AFAIK the most contributions to PDE came from platform commiters. ;)
After I downloaded and installed Neon M6 I immediately wanted to try out the DS annotations included in Eclipse (I know the DS annotations plugin from the market place). But the experience didn't feel complete. Following the points that bothered me:
1. Annotations import
I created a new bundle for a declarative service and wanted to test the @Component annotation.
With the old plugin from the marketplace I could write @Component and use code completion to add the import statement. No additional Import-Package is necessary there.
With the Neon M6 version code completion doesn't work. I have to add org.osgi.service.component.annotations to the Imported-Packages first, before code completion works.
I don't know what causes this difference in behavior, but as the annotations are only needed at compile time, I think we should not force a user to specify the import package statement, as it is not needed at runtime.
The need for adding the import package statement even introduces another issue if users are not aware. While running on Equinox it would be ok to simply specify the import package, it is mandatory to set it to optional if it is intended to run the bundle also on another runtime.
That means the Import-Package statement needs to look like this to work across multiple runtimes:
org.osgi.service.component.annotations;version="1.2.0";resolution:=optional
Instead the dependency should be added to the build.properties like this IMHO:
extra.. = platform:/plugin/org.eclipse.osgi.services_xxx.jar
or in a more version independent form. Maybe someone else has an idea on how to add a build time dependency from the Eclipse Platform without polluting the bundle dependencies.
2. Activation
After I saved the file, I assumed there is a component definition XML file generated, just as with the old plugin. But nothing happened. Then I realized that this needs to be activated in Neon.
Why does a user need to activate that feature actively? I think it is fine to be able to deactivate it. But it should be activated by default. I don't see a reason that it is deactivated by default, as it has only effect on sources if someone uses the DS annotations.
3. Warnings
After the generation of the component definition XML file, there are two warnings shown in the project. IMHO it is bad practice that code generation creates warnings in a project. At least if it is not intended to show a user that he has to modify something.
3.1 An entry for OSGI-INF/ is required in bin.includes
Honestly I'm not sure if the warning is correct or if the modification of the build.properties should be modified. It definitely forces a user to modify the build.properties manually to get rid of the warning.
I would suggest to modify the generation to create only an entry for the OSGI-INF folder in the build properties instead of the component definition XML.
So instead of something like this:
bin.includes = META-INF/,\
.,\
OSGI-INF/component.xml
it should look like this:
bin.includes = META-INF/,\
.,\
OSGI-INF/
Doing this would avoid the warning and automatically add all component definition XML files if there are multiple service implementations in that bundle.
This warning also comes up with the plugin, so it is not a regression regarding the move to Neon.
3.2 Bundles with a Service-Component should set the Bundle-ActivationPolicy to lazy.
IIRC that warning is introduced with Neon, so it is also not a regression.
I still don't understand why in Eclipse the DS do not work without that header. Probably a startup order issue.
Nevertheless the OSGi wiki says "if another service is registering the components (such as Declarative Services or Blueprint) then the lazy policy may be beneficial". So it doesn't seem to hurt.
Just as information, a DS bundle created with Bndtools does not specify the Bundle-ActivationPolicy.
Coming to the point, if a warning is raised that the Bundle-ActivationPolicy needs to be set to make a bundle that provides a DS work correctly with Equinox, we should add that header automatically.
4. Capabilities
Equinox supports capabilities and we could therefore add the generation of capability headers aswell.
4.1 Provide-Capability
If a service is provided, the Provide-Capability header should be added. In https://bugs.eclipse.org/bugs/show_bug.cgi?id=416047 this is also discussed for Equinox services.
If I understand correctly, adding the header should not have any impact if the header is not supported (e.g. by older Equinox implementations) and only adds information that can be used.
For a service org.eclipse.MyService, the header would look like this:
Provide-Capability: osgi.service;objectClass:List<String>="org.eclipse.MyService"
4.2 Require-Capability
If a bundle provides a DS, it should specify the requirement for DS. Since Neon Equinox adds the corresponding Provide-Capability header in the Manifest. We could therefore add the corresponding Require-Capability header, which would look like this:
Require-Capability: osgi.extender;
filter:="(&(osgi.extender=osgi.component)(version>=1.2)(!(version>=2.0)))"
But there are two downsides with adding the Require-Capability header.
a) The service won't work with an older Equinox version, because the Provide-Capability header is not specified there.
b) p2 does not support OSGi capabilities. It has its own capability mechanism that needs to be specified via p2.inf. That means, the p2.inf file needs also to be added in case OSGi capabilities should be supported.
So if we decide to add that, we should make it configurable.
I’m not sure how to proceed here. Maybe first a discussion about the facts, then the information who should take care about the decisions (who is responsible for the maintenance of the annotations?) and then correct things as decided here.
Greez,
Dirk