Switch to OSGI annotations

[joerghoh]

Although the SCR annotations are still supported, we should switch over to OSGI annotations.

Carsten Ziegeler's blog:

• https://blog.osoco.de/2016/05/migrating-from-the-apache-felix-scr-annotations-to-the-osgi-declarative-services-annotations/ (Overview)
• https://blog.osoco.de/2015/08/osgi-components-simply-simple-part-i/ (Components, References)
• https://blog.osoco.de/2015/08/osgi-components-simply-simple-part-ii/ (Configuration, Services)
• https://blog.osoco.de/2015/11/osgi-components-simply-simple-part-iii/ (Metatype)

Specific for AEM:

• @heervisscher: http://blogs.adobe.com/experiencedelivers/experience-management/using-osgi-annotations-aem6-2/ (focus on Configuration)
• @nateyolles: http://www.nateyolles.com/blog/2017/05/osgi-declarative-services-annotations-in-aem

Registering Sling Servlets (new annotations): https://sling.apache.org/documentation/the-sling-engine/servlets.html#registering-a-servlet-using-java-annotations

• For the different ways to register servlets (resourcetype-based or path-based) there are different annotations!

References:

• 1567 how to deal with configuration ids containing a hyphen ("-")

Learnings regarding Labels and Descriptions

• SCR annotations mixed all up a bit; especially the label and description of the component was taken for the component itself and its configuration. This is clearly separated with OSGI annotations:
• @Component allows you to have a description, but I haven't found where it's reflected. Anyhow, just the full qualified classname in the /system/console/components isn't a bad thing either, isn't it?
• Use the name and the description on the ObjectClassDefinition annotation to provide metadata for the Configuration.

Things I learned when dealing with Configurations and properties:

• While with SCR you play with @Property and @Properties as you like (write on top of the class or annotate constant strings with it), OSGI annotations give some clear recommendations:
• If you are not supposed to change a value (with SCR you used propertyPrivate=true), add it to the @Component annotation. And propertyPrivate is not needed anymore.
• If you should be able to change them, add them to the @ObjectClassDefinition interface (tpyically called Config).
• You don't need the metatype=true|false properties in the @Component annotation anymore. If you have a @Designate(ocd=...class) annotation on your service, it will generate metatype information automatically for it.

Regarding Java package versions:

• OSGI now offers a regular @Versionannotation to annotate package names with a version. Just change the import statement in the package-info.java files to import org.osgi.annotation.versioning.Version;

In general:

• The OSGI annotations are more picky already during build (check the output of the maven-bundle-plugin) and do some validation already there.

[heervisscher]

thanks @joerghoh , happy to help to implement this

[davidjgonzalez]

Have you run into the scenario where OSGi property names have hypens in them? IIRC you can't do that w/ the new approach?

[heervisscher]

Good one! I thought this could be done via the name-attribute... @AttributeDefinition(name = "Multiple-Values", description = "Multi Configuration values")

But this is not the case.

[joerghoh]

No, the id is determined according to some rules, which described in chapter 105.15.2 (The \@AtributeDefinition in the metatype spec of R6). In R7 it's basically still the same.

The ID is deduced from the name of the method in the ObjectClassDefinition interface.

[davidjgonzalez]

@joerghoh correct - so can we move ErrorPageHandler to use the new annotations when there is this existing OSGi Property: error-page.system-path ? If so, what does that ObjectClassDefinition method name look like? (I dont know how to do that)

[heervisscher]

Just checked with carsten, conclusion: don't use hyphens for property names

[joerghoh]

R7 allows to use "$_$" which is replaced by a single hyphen (105.15.2). Not supported on R6 though.

[joerghoh]

Nevertheless, we need to find a way how we can deal with these properties on already existing components. I created issue #1567 to specifically deal with this case

[heervisscher]

first batch of change: https://github.com/Adobe-Consulting-Services/acs-aem-commons/pull/1580

[heervisscher]

When moving to R6 I see the following change in behaviour: In both cases no config was saved, but with the felix-annotations the defaults get written into the DS-properties

New code: https://github.com/Adobe-Consulting-Services/acs-aem-commons/pull/1580/files#diff-20b6e15068c1d1500bdfc90f156d2071 Old code: https://github.com/Adobe-Consulting-Services/acs-aem-commons/blob/master/bundle/src/main/java/com/adobe/acs/commons/email/impl/EmailServiceImpl.java

[joerghoh]

@heervischer: I guess that this is a feature of the SCR plugin, which mixes up DS and Metatype in many ways. Just checked the R6 spec, but I have not found a way to add metatype data also to the DS properties (just the other way around). From my point of view it's also not a show stopper.

WDYT?

[heervisscher]

No issue indeed, using this is making it fail-safe: this.profileName = StringUtils.defaultIfEmpty(config.profile(), DEFAULT_PROFILE);

[heervisscher]

also how can this replaced in r6? @References({ @Reference( name = "namedImageTransformers", referenceInterface = NamedImageTransformer.class, policy = ReferencePolicy.DYNAMIC, cardinality = ReferenceCardinality.OPTIONAL_MULTIPLE ),

[davidjgonzalez]

@heervisscher you should be able to do something like this:

https://github.com/Adobe-Marketing-Cloud/asset-share-commons/blob/master/core/src/main/java/com/adobe/aem/commons/assetshare/configuration/impl/AssetDetailsResolverImpl.java#L38

[heervisscher]

thanks @davidjgonzalez

[badvision]

How much of this do we have remaining?

[heervisscher]

around 40 classes I think

[heervisscher]

factories can be done with : @Designate(ocd=StaticReferenceRewriteTransformerFactory.Config.class,factory=true)

[heervisscher]

https://github.com/Adobe-Consulting-Services/acs-aem-commons/pull/1626

[heervisscher]

when specifying Integer and Boolean values in @Component, you need to do this with :Boolean=false or :Integer=100

[kwin]

@joerghoh Is there any reason why with this switch you not also switched to bnd-maven-plugin (instead of maven-bundle-plugin). The latter is much better supported right now and Sling is also slowly moving away from maven-bundle-plugin.

[kwin]

Also it seems to me that with the current master Felix SCR annotations are no longer in use, but still the maven-scr-plugin is defined in the root pom.xml and also the maven-bundle-plugin is still leveraging the org.apache.felix.scrplugin.bnd.SCRDescriptorBndPlugin. The latter causes issue for some people (#1675) and also makes the build slower than necessary. Can we get rid of those legacy plugins now? Also there is still the usage of aQute.bnd.annotation.ProviderType. This should be replaced by the official OSGi annotation as well. I will try to come up with a PR fixing those remaining leftovers.