This is an automated email from the ASF dual-hosted git repository. djencks pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/felix-antora-site.git
commit d7c689634ebc5b157240ff02da29f03a5c40f9c7 Author: David Jencks <[email protected]> AuthorDate: Sun Jul 11 15:46:14 2021 -0700 remove maven scr plugin doc (unmaintained) --- modules/ROOT/pages/documentation/subprojects.adoc | 2 +- .../subprojects/apache-felix-maven-scr-plugin.adoc | 80 ---------------------- 2 files changed, 1 insertion(+), 81 deletions(-) diff --git a/modules/ROOT/pages/documentation/subprojects.adoc b/modules/ROOT/pages/documentation/subprojects.adoc index 32b2c4d..667865b 100644 --- a/modules/ROOT/pages/documentation/subprojects.adoc +++ b/modules/ROOT/pages/documentation/subprojects.adoc @@ -123,7 +123,7 @@ The last documentation may be found in the https://github.com/apache/felix-site- * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-manifest-generator-mangen.html[Manifest Generator (mangen)] * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-maven-obr-plugin.html[Maven OBR Plugin] * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-maven-osgi-plugin.html[Maven OSGi Plugin] -* xref:documentation/subprojects/apache-felix-maven-scr-plugin.adoc[Maven SCR Plugin] +* https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-maven-scr-plugin.html[Maven SCR Plugin] * xref:documentation/subprojects/mosgi-managed-osgi-framework.adoc[MOSGi Managed OSGi framework] * xref:documentation/subprojects/apache-felix-osgi-core.adoc[OSGi Core] * xref:documentation/subprojects/apache-felix-script-console-plugin.adoc[Script Console Plugin] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-maven-scr-plugin.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-maven-scr-plugin.adoc deleted file mode 100644 index 2c2f271..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-maven-scr-plugin.adoc +++ /dev/null @@ -1,80 +0,0 @@ -= Apache Felix Maven SCR Plugin - -NOTE: While the Apache Felix Maven SCR Plugin is a great tool (see below), for developing OSGi components using Declarative Services you should use the official annotations from the OSGi R6 specification. -The development of the Apache Felix SCR Plugin is in maintenance mode. - -The Apache Felix Maven SCR Plugin is a great tool to ease the development of OSGi components and services. -Components and services are defined through annotations and the plugin creates the necessary descriptors for the OSGi Declarative Services, Config Admin and Metatype services. -Recent versions of the plugin support OSGi Declarative Services versions 1.0, 1.1, and 1.2. - -Make sure to see the xref:documentation/faqs/apache-felix-scr-plugin-faq.adoc[FAQ] for known problems. - -== Introduction - -In OSGi based systems functionality is mainly provided through services. -Unlike traditional systems but comparable to Spring, a service is not reqiured to implement a framework defined interface. -Instead services implement one or more interfaces, which stipulate the type of service provided. -It is the lifetime of the bundle, which defines the lifetime of the service: A service object may be instantiated when the bundle is started and will automatically be removed when the bundle is stopped (and the service has not already been unregistered). - -Usually, the functionality of a bundle - be it the packages exported or be it the services provided - is made available to the rest of the system, when the bundle is started. -To give the bundle a change to take action, a bundle may declare a `BundleActivator` class in the `Bundle-Activato` manifest header of the bundle. -When the bundle is started, the `start(BundleContext)` method is called, while the `stop(BundleContext)` method is called when the bundle is stopped. -These methods are one place to instantiate and register services with the service registry. - -The drawback of this method of service registration is that the services have to acquire other services whose functionality is used themselves and also have to observe the presence as services may come and go at any time. -Though this observation is rather easy as basically a `ServiceListener` is to be implemented which listens for service registration and unregistration events, this is somewhat tedious and repeating for each service using other services. - -To overcome this situation, the OSGi Service Platform Compendium Specification provides the _Declarative Services Specification_. -This specification enables the declaration of services in configuration files, which are read by the _Declarative Services Runtime_ to observe dependencies and activate (register) and deactivate (unregister) services depending on whether requirements can be met. -Additionally, the dependencies may be supplied through declared methods. -The specification calls a class declared this way a component. -A component may or may not be a service registered with the service registry. - -Components are declared using XML configuration files contained in the respective bundle and listed in the `Service-Component` bundle manifest header. -These configuration files may be handwritten and registered. -To support automatic generation of the component descriptors, the Maven SCR Plugin helps in the generation of these files by means of JavaDoc tags embedded in the Java source code of the components. - -Related to declarative services is configuration support. -To support configuration of services and components, OSGi provides the Configuration Admin Service Specification. -This specification defines a service, which is the center of providing configuration to services and components. -As such the Configuration Admin Service cares for storing configuration and deliver the configuration automatically or on-demand to clients. -Configuration objects are identified by so-called Persistent Identifiers (PID) and are bound to bundles when used. -For services implementing the special `ManagedService` or `ManagedServiceFactory` interfaces the PID has to be provided in the service properties as a property with the name `service.pid`. -For Declarative Services, the name of the component is used as the PID to retrieve the configuration from the Configuration Admin Service. - -The Configuration Admin Service not only allows components to get or retrieve configuration, it also provides the entry point for Management Agents to retrieve and update configuration data. -To help building Management Agents the OSGi Metatype Service Specification defines a descripton model which may be used to describe data used by components and services. -The configuration properties and meta type description for a given PID together are used to build the user interface to configure the service and/or component. - -To summarize: - -. _Declarative Services_ provides a means to define components (and services) through one or more XML files. -Each component may get default configuration from its own definition. -. The _Configuration Admin Service_ provides functionality to provide configuration to components and services as well as to support management tools to update (and create) configuration data. -. The _Metatype Service_ provides a description suitable for management tools to manage configurations provided by the Configuration Admin Service. -The descriptions of the data is provided in one or more XML files and associated languag binding files. - -== Where to go from here - -* xref:documentation/subprojects/apache-felix-maven-scr-plugin/apache-felix-maven-scr-plugin-use.adoc[] -* xref:documentation/subprojects/apache-felix-maven-scr-plugin/apache-felix-scr-ant-task-use.adoc[] -* xref:documentation/subprojects/apache-felix-maven-scr-plugin/apache-felix-scr-bndtools-use.adoc[] -* xref:documentation/subprojects/apache-felix-maven-scr-plugin/scr-annotations.adoc[] -* xref:documentation/subprojects/apache-felix-maven-scr-plugin/scr-javadoc-tags.adoc[] -* xref:documentation/subprojects/apache-felix-maven-scr-plugin/extending-scr-annotations.adoc[] - -== Differences between JavaDoc tags and annotations - -In general both mechanisms provide the same functionality. -There are some subtle difference which are listed in this section: - -* JavaDoc tags are not supported in recent versions of the plugin, support has been removed with version 1.8.0. -New features will only be implemented as annotations. -* While the `metatype` flag is turned on by default for the JavaDoc tags, the default for the annotations is to generate no metadata. -The reason for this is, that it turned out that services with metadata are less often used. -* The JavaDoc support adds properties and references from super classes if the source is in the same module to a component even if the super class does not have the `@scr.component` tag. -With the annotations the super class is required to have the `Component` annotation. -* Property values are handled differently. -While the JavaDoc version has an auto detection of types together with an explicit type parameter, the annotations version has several attributes. -Each type has its own attribute (like `shortValue`, `intValue` and so on). -This is because of a limitation in the Java annotations which only allow typed parameters.
