You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by dj...@apache.org on 2021/07/11 23:13:50 UTC
[felix-antora-site] 01/18: remove .mdtext files
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 6ed7c13905b80395b30140f75b42dc5e63102181
Author: David Jencks <dj...@apache.org>
AuthorDate: Sun Jul 11 15:17:55 2021 -0700
remove .mdtext files
---
modules/ROOT/pages/documentation.mdtext | 18 -
modules/ROOT/pages/documentation/community.mdtext | 4 -
.../documentation/community/contributing.mdtext | 43 -
.../documentation/community/project-info.mdtext | 48 -
.../community/projects-using-felix.mdtext | 13 -
.../ROOT/pages/documentation/development.mdtext | 7 -
.../development/coding-standards.mdtext | 481 ------
.../development/dependencies-file-template.mdtext | 43 -
.../development/provisional-osgi-api-policy.mdtext | 27 -
.../development/release-management-nexus.mdtext | 345 -----
.../documentation/development/site-how-to.mdtext | 201 ---
.../using-the-osgi-compliance-tests.mdtext | 213 ---
modules/ROOT/pages/documentation/faqs.mdtext | 6 -
.../faqs/apache-felix-bundle-plugin-faq.mdtext | 179 ---
.../faqs/apache-felix-scr-plugin-faq.mdtext | 71 -
.../pages/documentation/getting-started.mdtext | 11 -
.../ROOT/pages/documentation/subprojects.mdtext | 61 -
.../subprojects/apache-felix-autoconf.mdtext | 4 -
.../subprojects/apache-felix-commons.mdtext | 68 -
.../creating-bundles-using-bnd.mdtext | 84 -
.../apache-felix-dependency-manager.mdtext | 62 -
.../guides/annotations.mdtext | 347 -----
.../guides/background.mdtext | 28 -
.../guides/bundles-and-dependencies.mdtext | 23 -
.../guides/design-patterns.mdtext | 161 --
.../guides/development.mdtext | 48 -
.../guides/dm-lambda.mdtext | 943 ------------
.../guides/history.mdtext | 15 -
.../guides/javadocs.mdtext | 4 -
.../guides/migrating-from-earlier-versions.mdtext | 69 -
.../guides/migrating-from-other-solutions.mdtext | 2 -
.../guides/performance-tuning.mdtext | 37 -
.../guides/resources.mdtext | 97 --
.../guides/whatsnew-r15.mdtext | 199 ---
.../guides/whatsnew.mdtext | 68 -
.../reference/component-adapter.mdtext | 44 -
.../reference/component-aspect.mdtext | 35 -
.../reference/component-bundle-adapter.mdtext | 35 -
.../component-factory-configuration-adapter.mdtext | 44 -
.../reference/component-resource-adapter.mdtext | 114 --
.../reference/component-singleton.mdtext | 63 -
.../reference/components.mdtext | 227 ---
.../reference/dependencies.mdtext | 32 -
.../reference/dependency-bundle.mdtext | 34 -
.../reference/dependency-configuration.mdtext | 105 --
.../reference/dependency-resource.mdtext | 93 --
.../reference/dependency-service.mdtext | 35 -
.../reference/dm-annotations.mdtext | 1611 --------------------
.../reference/external-links.mdtext | 7 -
.../reference/service-scopes.mdtext | 221 ---
.../reference/thread-model.mdtext | 113 --
.../tutorials/getting-started.mdtext | 195 ---
.../tutorials/leveraging-the-shell.mdtext | 97 --
.../tutorials/sample-code.mdtext | 63 -
.../tutorials/working-with-annotations.mdtext | 214 ---
.../apache-felix-deployment-admin.mdtext | 4 -
.../subprojects/apache-felix-event-admin.mdtext | 225 ---
.../subprojects/apache-felix-file-install.mdtext | 104 --
.../apache-felix-framework-security.mdtext | 50 -
.../subprojects/apache-felix-framework.mdtext | 8 -
.../apache-felix-framework-bundle-cache.mdtext | 66 -
...felix-framework-configuration-properties.mdtext | 82 -
.../apache-felix-framework-faq.mdtext | 60 -
...-felix-framework-launching-and-embedding.mdtext | 784 ----------
...ache-felix-framework-usage-documentation.mdtext | 179 ---
.../subprojects/apache-felix-gogo.mdtext | 195 ---
.../apache-felix-gogo/rfc-147-overview.mdtext | 158 --
.../subprojects/apache-felix-healthchecks.mdtext | 19 -
.../subprojects/apache-felix-inventory.mdtext | 133 --
.../subprojects/apache-felix-ipojo.mdtext | 83 -
.../dive-into-the-ipojo-manipulation-depths.mdtext | 209 ---
.../how-to-use-ipojo-manipulation-metadata.mdtext | 79 -
.../how-to-write-your-own-handler.mdtext | 821 ----------
.../apache-felix-ipojo-eclipse-integration.mdtext | 60 -
.../apache-felix-ipojo-feature-overview.mdtext | 54 -
.../apache-felix-ipojo-dosgi.mdtext | 132 --
.../how-to-use-ipojo-annotations.mdtext | 375 -----
.../ipojo-advanced-tutorial.mdtext | 518 -------
.../ipojo-composition-tutorial.mdtext | 504 ------
.../ipojo-hello-word-maven-based-tutorial.mdtext | 428 ------
.../ipojo-in-10-minutes.mdtext | 514 -------
.../apache-felix-ipojo-junit4osgi.mdtext | 26 -
...ache-felix-ipojo-junit4osgi-architecture.mdtext | 39 -
.../apache-felix-ipojo-junit4osgi-maven.mdtext | 211 ---
.../apache-felix-ipojo-junit4osgi-methods.mdtext | 74 -
.../apache-felix-ipojo-junit4osgi-tutorial.mdtext | 311 ----
.../apache-felix-ipojo-keypoints.mdtext | 46 -
.../apache-felix-ipojo-successstories.mdtext | 54 -
.../apache-felix-ipojo-supportedosgi.mdtext | 80 -
.../apache-felix-ipojo-supportedvms.mdtext | 106 --
.../apache-felix-ipojo-testing-components.mdtext | 87 --
.../apache-felix-ipojo-online-manipulator.mdtext | 51 -
.../apache-felix-ipojo-tools/ipojo-ant-task.mdtext | 124 --
.../ipojo-arch-command.mdtext | 169 --
.../ipojo-karaf-feature.mdtext | 31 -
.../ipojo-maven-plug-in.mdtext | 245 ---
.../ipojo-webconsole-plugin.mdtext | 70 -
.../apache-felix-ipojo-tools/junit4osgi.mdtext | 191 ---
.../apache-felix-ipojo-api.mdtext | 321 ----
.../apache-felix-ipojo-instances.mdtext | 391 -----
.../describing-components.mdtext | 34 -
.../architecture-handler.mdtext | 59 -
.../configuration-handler.mdtext | 155 --
.../controller-lifecycle-handler.mdtext | 56 -
.../event-admin-handlers.mdtext | 321 ----
.../extender-pattern-handler.mdtext | 133 --
.../injecting-bundle-context.mdtext | 66 -
.../describing-components/ipojo-jmx-handler.mdtext | 307 ----
.../lifecycle-callback-handler.mdtext | 146 --
.../providing-osgi-services.mdtext | 396 -----
.../service-requirement-handler.mdtext | 734 ---------
.../temporal-service-dependency.mdtext | 142 --
.../white-board-pattern-handler.mdtext | 151 --
.../instance-vs-service-controller.mdtext | 77 -
.../ipojo-advanced-topics.mdtext | 17 -
.../combining-ipojo-and-configuration-admin.mdtext | 298 ----
...ucting-pojo-objects-with-factory-methods.mdtext | 43 -
.../how-to-use-ipojo-factories.mdtext | 239 ---
.../ipojo-extender-configuration.mdtext | 168 --
.../ipojo-factory-service.mdtext | 145 --
.../ipojo-hierarchical-composition-overview.mdtext | 250 ---
.../service-binding-interceptors.mdtext | 200 ---
.../using-ipojo-introspection-api.mdtext | 267 ----
.../ipojo-advanced-topics/using-stereotypes.mdtext | 83 -
.../apache-felix-ipojo-userguide/ipojo-faq.mdtext | 448 ------
.../using-xml-schemas.mdtext | 90 --
.../apache-felix-ipojo-why-choose-ipojo.mdtext | 74 -
.../articles-and-presentations.mdtext | 16 -
.../developing-camel-mediators-with-ipojo.mdtext | 157 --
.../subprojects/apache-felix-ipojo/download.mdtext | 61 -
.../apache-felix-ipojo/ipojo-news.mdtext | 42 -
.../apache-felix-ipojo/ipojo-reference-card.mdtext | 886 -----------
.../apache-felix-ipojo/ipojo-support.mdtext | 24 -
.../apache-felix-ipojo/related-works.mdtext | 18 -
.../subprojects/apache-felix-jaas.mdtext | 306 ----
.../apache-felix-lightweight-http-service.mdtext | 18 -
.../subprojects/apache-felix-log.mdtext | 200 ---
.../subprojects/apache-felix-logback.mdtext | 173 ---
.../apache-felix-manifest-generator-mangen.mdtext | 534 -------
.../apache-felix-maven-bundle-plugin-bnd.mdtext | 921 -----------
.../apache-felix-maven-obr-plugin.mdtext | 196 ---
.../apache-felix-maven-osgi-plugin.mdtext | 287 ----
.../apache-felix-maven-scr-plugin.mdtext | 49 -
.../apache-felix-maven-scr-plugin-use.mdtext | 144 --
.../apache-felix-scr-ant-task-use.mdtext | 162 --
.../apache-felix-scr-bndtools-use.mdtext | 142 --
.../extending-scr-annotations.mdtext | 63 -
.../scr-annotations.mdtext | 367 -----
.../scr-javadoc-tags.mdtext | 162 --
.../apache-felix-metatype-service.mdtext | 124 --
.../apache-felix-osgi-bundle-repository.mdtext | 324 ----
.../subprojects/apache-felix-osgi-core.mdtext | 3 -
.../apache-felix-preferences-service.mdtext | 86 --
.../subprojects/apache-felix-remote-shell.mdtext | 32 -
.../apache-felix-script-console-plugin.mdtext | 157 --
.../apache-felix-serialization-framework.mdtext | 42 -
.../subprojects/apache-felix-shell-tui.mdtext | 9 -
.../subprojects/apache-felix-shell.mdtext | 239 ---
.../subprojects/apache-felix-upnp.mdtext | 21 -
.../apache-felix-upnp/upnp-acknowledgments.mdtext | 5 -
.../upnp-driver-architecture.mdtext | 45 -
.../apache-felix-upnp/upnp-getting-started.mdtext | 52 -
.../apache-felix-upnp/upnp-known-issues.mdtext | 13 -
.../apache-felix-upnp/upnp-testing-devices.mdtext | 38 -
.../upnp-testing-devices/upnp-examples.mdtext | 24 -
.../upnp-examples/upnp-writing-cd-and-cp.mdtext | 60 -
.../subprojects/apache-felix-user-admin.mdtext | 12 -
.../apache-felix-user-admin-background.mdtext | 20 -
.../apache-felix-user-admin-file-store.mdtext | 11 -
.../apache-felix-user-admin-getting-started.mdtext | 31 -
.../apache-felix-user-admin-introduction.mdtext | 3 -
.../apache-felix-user-admin-mongodb-store.mdtext | 16 -
.../subprojects/apache-felix-web-console.mdtext | 180 ---
.../extending-the-apache-felix-web-console.mdtext | 10 -
.../branding-the-web-console.mdtext | 115 --
.../providing-resources.mdtext | 22 -
.../providing-web-console-plugins.mdtext | 62 -
.../web-console-logging.mdtext | 21 -
.../web-console-output-templating.mdtext | 66 -
.../web-console-restful-api.mdtext | 345 -----
.../web-console-security-provider.mdtext | 104 --
.../mosgi-managed-osgi-framework.mdtext | 83 -
.../mosgi-managed-osgi-framework/probeguide.mdtext | 149 --
.../tutorials-examples-and-presentations.mdtext | 35 -
.../apache-felix-application-demonstration.mdtext | 139 --
.../apache-felix-osgi-faq.mdtext | 123 --
.../apache-felix-osgi-tutorial.mdtext | 16 -
.../apache-felix-tutorial-example-1.mdtext | 117 --
.../apache-felix-tutorial-example-2.mdtext | 153 --
.../apache-felix-tutorial-example-2b.mdtext | 129 --
.../apache-felix-tutorial-example-3.mdtext | 149 --
.../apache-felix-tutorial-example-4.mdtext | 242 ---
.../apache-felix-tutorial-example-5.mdtext | 163 --
.../apache-felix-tutorial-example-6.mdtext | 327 ----
.../apache-felix-tutorial-example-7.mdtext | 161 --
.../apache-felix-tutorial-example-8.mdtext | 251 ---
.../apache-felix-tutorial-example-9.mdtext | 115 --
modules/ROOT/pages/errors/403.mdtext | 24 -
modules/ROOT/pages/errors/404.mdtext | 25 -
modules/ROOT/pages/index.mdtext | 20 -
modules/ROOT/pages/license.mdtext | 206 ---
modules/ROOT/pages/media.mdtext | 8 -
modules/ROOT/pages/miscellaneous.mdtext | 2 -
.../ROOT/pages/miscellaneous/apache-karaf.mdtext | 5 -
.../ROOT/pages/miscellaneous/board-reports.mdtext | 6 -
.../apache-felix-board-report-template.mdtext | 17 -
.../board-reports/board-report-2007-04.mdtext | 23 -
.../board-reports/board-report-2007-05.mdtext | 21 -
.../board-reports/board-report-2007-06.mdtext | 25 -
.../board-reports/board-report-2007-09.mdtext | 22 -
.../board-reports/board-report-2007-12.mdtext | 23 -
.../board-reports/board-report-2008-03.mdtext | 18 -
.../board-reports/board-report-2008-06.mdtext | 20 -
.../board-reports/board-report-2008-09.mdtext | 18 -
.../board-reports/board-report-2008-12.mdtext | 20 -
.../board-reports/board-report-2009-03.mdtext | 22 -
.../board-reports/board-report-2009-06.mdtext | 34 -
.../board-reports/board-report-2009-09.mdtext | 25 -
.../board-reports/board-report-2009-12.mdtext | 34 -
.../board-reports/board-report-2010-03.mdtext | 26 -
.../board-reports/board-report-2010-06.mdtext | 39 -
.../board-reports/board-report-2010-09.mdtext | 26 -
.../board-reports/board-report-2010-12.mdtext | 29 -
.../board-reports/board-report-2011-03.mdtext | 30 -
.../board-reports/board-report-2011-06.mdtext | 32 -
.../board-reports/board-report-2011-09.mdtext | 32 -
.../board-reports/board-report-2011-12.mdtext | 32 -
.../board-reports/board-report-2012-03.mdtext | 29 -
.../board-reports/board-report-2012-06.mdtext | 34 -
.../board-reports/board-report-2012-09.mdtext | 31 -
.../board-reports/board-report-2012-12.mdtext | 32 -
.../board-reports/board-report-2013-03.mdtext | 23 -
.../miscellaneous/cat-scan-project-proposal.mdtext | 12 -
.../cat-scan-001-use-cases.mdtext | 3 -
.../cat-scan-002-profiles.mdtext | 10 -
.../cat-scan-002-001-basic-profile.mdtext | 2 -
.../cat-scan-003-run-log-archive.mdtext | 3 -
.../cat-scan-004-api-reference.mdtext | 3 -
...cat-scan-005-technical-compatibility-kit.mdtext | 3 -
.../cat-scan-006-glossary.mdtext | 3 -
.../cat-scan-007-references.mdtext | 3 -
.../incubator-status-report-january-2007.mdtext | 26 -
.../incubator-status-report-october-2006.mdtext | 20 -
.../osgi-bundle-service-diagrams.mdtext | 18 -
modules/ROOT/pages/miscellaneous/sandbox.mdtext | 3 -
.../miscellaneous/sandbox/composite-bundles.mdtext | 242 ---
.../miscellaneous/sandbox/virtual-bundles.mdtext | 220 ---
.../miscellaneous/sandbox/web-console-ng.mdtext | 12 -
.../miscellaneous/subproject-release-status.mdtext | 100 --
.../ROOT/pages/miscellaneous/tlp-task-list.mdtext | 30 -
modules/ROOT/pages/news.mdtext | 455 ------
251 files changed, 32735 deletions(-)
diff --git a/modules/ROOT/pages/documentation.mdtext b/modules/ROOT/pages/documentation.mdtext
deleted file mode 100644
index fbed85d..0000000
--- a/modules/ROOT/pages/documentation.mdtext
+++ /dev/null
@@ -1,18 +0,0 @@
-Title: Documentation
-
-In an effort to make it easier to find desired documentation, we have divided our documentation section into the following six areas:
-
-* [Getting started]({{ refs.getting-started.path }}) - This area captures a few links from the areas below that will help you get started with Felix.
-* [FAQs]({{ refs.faqs.path }}) - This area captures all FAQ documentation, which typically varies from subproject to subproject.
-* [Community]({{ refs.community.path }}) - This area captures documentation associated with how the Felix community works and how to become involved in it.
-* [Development]({{ refs.development.path }}) - This area captures documentation for Felix developers or those interested in becoming Felix developers; this is not intended for Felix users although some information may be useful.
-* [Subprojects]({{ refs.subprojects.path }}) - This area captures user documentation for the various Felix subprojects.
-* [Tutorials, examples, and presentations]({{ refs.tutorials-examples-and-presentations.path }}) - This area captures general user documentation that does not necessarily fit into any single subproject.
-
-In addition a [site map](https://felix.apache.org/sitemap.html) is available as a table of
-contents of the site.
-
-If you are unable to find the documentation you need, please ask on the [mailing lists]({{ refs.mailinglists.path }}). Also, feedback on improving the documentation and/or organization of this site is welcome.
-
-*The Felix web site and documentation are managed with the [Apache CMS](https://www.apache.org/dev/cms.html).
-For Apache Felix specific extensions see the [Site How-To]({{refs.site-how-to.path}}).*
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/community.mdtext b/modules/ROOT/pages/documentation/community.mdtext
deleted file mode 100644
index ded7b9f..0000000
--- a/modules/ROOT/pages/documentation/community.mdtext
+++ /dev/null
@@ -1,4 +0,0 @@
-Title: Community Documentation
-
-{% for label, page in children %}* [{{ page.headers.title }}]({{ page.path }})
-{% endfor %}
diff --git a/modules/ROOT/pages/documentation/community/contributing.mdtext b/modules/ROOT/pages/documentation/community/contributing.mdtext
deleted file mode 100644
index 8630a8c..0000000
--- a/modules/ROOT/pages/documentation/community/contributing.mdtext
+++ /dev/null
@@ -1,43 +0,0 @@
-Title: Contributing
-
-Apache Felix is a volunteer effort, so there is always plenty of work that needs to be accomplished. If you want to help support Felix, this page is intended as a starting point for specific contribution ideas. To further understand how the Felix community operates, refer to the [Community Roles and Processes](https://www.apache.org/foundation/how-it-works.html) document and/or join the [mailing lists]({{ refs.project-info.path }}).
-
-The Felix project organizes its "to do" list using the [JIRA](https://issues.apache.org/jira/browse/Felix) issue tracking system. Specific items from Felix' JIRA issue tracking system are highlighted on this page, but are not limited to it. The purpose of the list here is to highlight issues that are either more important or serve as good entry points for new contributors.
-
-It is important to point out that you do not need to be a programmer to contribute to Felix. As such, we will break out the list of issues below for non-programmers and programmers.
-
-## Non-Programmers
-
-* Improve web site or documentation (e.g., create/propose FAQ entries). There is no specific JIRA issue for this task, but any contributions could be posted as new JIRA issues for the Documentation component.
-
-## Programmers
-
-Before contributing, make sure to be subscribed to the [developer mailing list]({{ refs.project-info.path }}). If you don't have your own issue to scratch, you can browse open issues in [JIRA](https://issues.apache.org/jira/browse/Felix) and submit a patch.
-
-Source code contributions fall into two categories: pull requests or grants. This document describes both and how to handle each.
-
-### Pull Requests
-
-A pull request is a small change to existing code, typically in response to a bug fix or improvement. If you have created a change, you should:
-
-1. Create a [JIRA](https://issues.apache.org/jira/browse/Felix) issue (or find a pertinent existing issue) describing the issue needing to be addressed.
-1. Create a pull requests against the git repository containing the code.
-1. The pull request will eventually be reviewed and applied (if accepted) by a Felix committer, but feel free to bug us \[nicely\]({{ refs.nicely.path }}) if you get impatient.
-
-Providing pull requests is a very good way to become a committer at Felix, since we'd rather have you review and apply the patches than us. :-)
-
-### Grants
-
-A grant involves donating a larger chunk of code developed elsewhere. The line dividing a patch and a grant is sort of like the definition of pornography, we know it when we see it. The steps for granting software are a little more complicated since we need to ensure proper IP handling. For grants, you should:
-
-1. Verify that you have the authorization to donate the code.
-1. Review our [developer documentation]({{ refs.development.path }}) as well as the general [Apache documentation|https://www.apache.org/foundation/getinvolved.html] to determine whether you would really like be involved with us and how we work.
-1. Assuming you're still interested, create a [JIRA](https://issues.apache.org/jira/browse/Felix) issue describing the code you wish to donate.
-1. Attach an archive containing the code along with an MD5 signature of the archive to the above issue. You should remove any existing headers from the source files and add the standard Apache header to each. Note that you keep the rights to your code and can do anything with it you want, you will just grant us the right to use it too.
-1. Allow the community time to discuss the contribution, after which a vote will be called to accept the contribution.
-1. If the vote passes, then you will need to submit a [software grant](https://www.apache.org/licenses/software-grant.txt) form.
-1. It is also a good idea to submit an [ICLA](https://www.apache.org/licenses/icla.txt) to ease future contributions. Depending on the company you work for, they may also want to contribute a [CCLA|https://www.apache.org/licenses/cla-corporate.txt], although this isn't strictly necessary from an Apache point of view, since it is your responsibility to verify your ability to submit an ICLA.
-1. Once all of this information is received, then we will gather it and perform [IP clearance](https://incubator.apache.org/ip-clearance/index.html).
-1. After a few days, if no red flags are raised, then we'll commit the code and we're good to go.
-
-Granting code is also a path to committership at Felix, since we look more highly on contributions from developers who wish to stay involved in the continuing evolution and maintenance of the donated code.
diff --git a/modules/ROOT/pages/documentation/community/project-info.mdtext b/modules/ROOT/pages/documentation/community/project-info.mdtext
deleted file mode 100755
index 610e738..0000000
--- a/modules/ROOT/pages/documentation/community/project-info.mdtext
+++ /dev/null
@@ -1,48 +0,0 @@
-Title: Apache Felix Project Info
-
-There are different roles with which Felix community members may be associated, these roles are: users, contributors, committers, and Project Management Committee (PMC) members. These roles are assigned and assumed based on merit. Everyone in the Felix community can participate to whatever level they desire, but participating and the resulting merit gained is directly linked to the role an individual may obtain. To further understand how the Felix community operates, refer to the [Commun [...]
-
-## Committers and Project Management Committee (PMC)
-
-See Apache Phone Book: [Apache Felix Committers and PMC members](https://people.apache.org/phonebook.html?pmc=felix)
-
-### Past members:
-
-* Niclas Hedhman (stepped down 1/26/2009)
-* Trustin Lee (stepped down 2/9/2008)
-* Upayavira (stepped down 9/11/2007)
-
-## Source Code
-
-This project uses [git](https://git-scm.com/) to manage its source code. Instructions on git can be found at [git docs](https://git-scm.com/docs).
-
-### Web Access
-
-The following is a link to the online source repository.
-
-[https://github.com/apache/felix-dev](https://github.com/apache/felix-dev)
-
-### Committer and anonymous access
-
-The Felix source code can be checked out (anonymously) with the following command:
-
- :::sh
- $ git clone https://github.com/apache/felix-dev
-
-## Mailing lists
-
-The following mailing lists have been established for Apache Felix. For each list, there is a subscribe, unsubscribe, and archive link.
-
-|Name|Subscribe|Unsubscribe|Archive|
-|--|--|--|--|
-|*Felix Users* - For people using Felix subprojects and/or developing bundles. |[Subscribe](mailto:users-subscribe@felix.apache.org)|[Unsubscribe](mailto:users-unsubscribe@felix.apache.org)|[www.mail-archive.com](https://www.mail-archive.com/users%40felix.apache.org/)|
-|*Felix Dev* - For people interested in the internal development of Felix subprojects. |[Subscribe](mailto:dev-subscribe@felix.apache.org)|[Unsubscribe](mailto:dev-unsubscribe@felix.apache.org)|[www.mail-archive.com](https://www.mail-archive.com/dev%40felix.apache.org/)|
-|*Felix Commits* - For people intested in Felix subproject code changes. |[Subscribe](mailto:commits-subscribe@felix.apache.org)|[Unsubscribe](mailto:commits-unsubscribe@felix.apache.org)|[www.mail-archive.com](https://www.mail-archive.com/commits%40felix.apache.org/)|
-
-## Issue Tracking
-
-This project uses [JIRA](https://www.atlassian.com/software/jira), a J2EE-based, issue tracking and project management application. We use it for bugs, tasks and code contributions.
-
-Before creating a new issue, please make sure nobody has already added the issue you're reporting. When you do add an issue, please try to make it as informative as possible.
-
-The issue tracker can be found at [https://issues.apache.org/jira/browse/FELIX](https://issues.apache.org/jira/browse/FELIX)
diff --git a/modules/ROOT/pages/documentation/community/projects-using-felix.mdtext b/modules/ROOT/pages/documentation/community/projects-using-felix.mdtext
deleted file mode 100644
index 5a48bb6..0000000
--- a/modules/ROOT/pages/documentation/community/projects-using-felix.mdtext
+++ /dev/null
@@ -1,13 +0,0 @@
-Title: Projects Using Felix
-
-This page highlights projects that use Apache Felix (listed alphabetically):
-
-* [Apache Karaf](https://karaf.apache.org) - A small, OSGi-based runtime that provides a lightweight container into which various components and applications can be deployed (formerly an Apache Felix subproject).
-* [Apache ServiceMix](https://servicemix.apache.org/) - an Enterprise Service Bus (using Felix via Karaf).
-* [Apache Sling](https://sling.apache.org/) - a framework for RESTful web-applications based on an extensible content tree
-* [Apache Tuscany](https://tuscany.apache.org/) - an open source implementation of [SCA|http://www.oasis-opencsa.org/].
-* [Ascert VersaTest](http://www.ascert.com/) - enterprise system testing platform
-* [DySoWeb](http://www.requea.com/dysoweb/rq/en/archi/dysoweb) - A platform for dynamic component deployment.
-* [GlassFish](http://glassfish.dev.java.net) - JavaEE application server.
-* [OW2 JOnAS](http://jonas.ow2.org/) - JavaEE application server.
-* [SIP Communicator](https://sip-communicator.dev.java.net/) - a multi-protocol instant messenger and SIP software phone.
diff --git a/modules/ROOT/pages/documentation/development.mdtext b/modules/ROOT/pages/documentation/development.mdtext
deleted file mode 100644
index 3f535ef..0000000
--- a/modules/ROOT/pages/documentation/development.mdtext
+++ /dev/null
@@ -1,7 +0,0 @@
-Title: Development
-
-This page contains links related to Felix project development.
-
-{% for label, page in children %}* [{{ page.headers.title }}]({{ page.path }})
-{% endfor %}
-
diff --git a/modules/ROOT/pages/documentation/development/coding-standards.mdtext b/modules/ROOT/pages/documentation/development/coding-standards.mdtext
deleted file mode 100644
index 40cf737..0000000
--- a/modules/ROOT/pages/documentation/development/coding-standards.mdtext
+++ /dev/null
@@ -1,481 +0,0 @@
-Title: Coding Standards
-
-## Guidelines Summary
-
-This style guide is intended to help the computer professional produce better Java programs. It presents a set of specific guidelines for using the features of Java in a disciplined manner. The goal is to develop high quality, reliable, reusable, portable software. For a number of reasons, no programming language can ensure the achievements of these desirable objectives on its own. Programming must be embedded in a disciplined development process that addresses a number of topics in a we [...]
-
-Clear, readable, understandable source text eases program evolution, adaptation and maintenance. First, such source text is more likely to be correct and reliable. Second, effective code adaptation is a prerequisite to code reuse, a technique that has the potential for drastic reductions in system development costs. Easy adaptation requires thorough understanding of the software, and that is facilitated considerably by clarity. Finally, since maintenance (really evolution) is a costly pr [...]
-
-This style guide is intended for those involved in the development of real software systems written in Java. Different roles in a software project can exploit the style guide in different ways. The programmer can use it as a reference on good Java style. It can be used in code reviews as a common reference. Finally, lessons learned in real projects can be captured by extending the style guide.
-
-## Class layout and comments
-
-### Files and filenames
-
-Files longer than 2000 lines are cumbersome and should be avoided.
-
-#### File names
-
-The file must be named after the class it represents. As for most cases each file contains only one class, this is an easy naming convention. For nested or inner classes the name of the main class must be the name of the file. As names in Java are case-sensitive, the filename is case-sensitive also.
-
-#### File organization
-
-Each Java source file contains a single class or interface. Of course, this excludes inner classes as these must be defined without an (outer) class, and thus in the same file.
-
-Java source files have the following ordering:
-
-- Beginning comments
-- Package and import statements
-- Class and interface declarations
-
-#### Beginning comments
-
-All source files must begin with the comments shown in the following code sample.
-
-
- /*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-
-Note that this comment part is not according to the JavaDoc style (See: How to write doc comments for JavaDoc - Sun Microsystems, Inc.) as this is file specific information that is not relevant in generated API documentation.
-
-##### Package and import Statements
-
-The first non-comment line of most Java source files is a package statement. After an empty line import statements can follow. For example:
-
-
- package org.apache.felix.whatever.this.is;
-
- import java.awt.Frame;
- import java.io.InputStream;
- import java.util.Vector;
-
-
-A few notes must be made here:
-1. Package rules.
- When not using an explicit package statement in your code the code still is in a package, the default package. This easily results in name clashes and as package naming should be a part of the design, always use an explicit package name. For naming rules of packages see 3.4 Naming conventions.
-1. Import statements need to be explicit in order to overcome name clashes.
- They should be grouped by name. When the number of import statements of the same package exceeds the 'readability' limit (please use common sense), then import the complete package by adding '.*'.
-1. Import order.
- First in this section should be the standard Java imports like: java.lang.Throwable. Second should be the Java extensions (i.e. javax), third, the third party stuff. Finally the project-specific imports should be added.
-
-##### Class and interface Declarations
-
-The following comment block is an example for the comment that belongs to the declaration of a class or an interface. The combination of JavaDoc syntax and keywords that are expanded by the source integrity tool result in the following block:
-
-
- /**
- * This class is not really a class, because this file is just
- * a template that shows how the file header and class header
- * should look like.
- *
- * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
- */
-
-
-The following table describes the parts of a class or interface declaration, in the order that they should appear.
-
-| Part of Class/Interface Declaration | Notes |
-|--|--|
-|Class/Interface documentation|According to comment block as shown above.|
-|Class or interface statement| |
-|Class (static) variables|These should be grouped by functionality rather than by scope.|
-|Instance variables|These should be grouped by functionality rather than by scope.|
-|Constructors|Start with the default constructor if any.|
-|Methods that belong to the class (see also 2.1.3.4 Class methods versus specific interface methods and event methods)|These methods should also be grouped by functionality rather than by scope or accessibility. E.g. a private class method can be in between two public instance methods. The goal is to make reading and understanding the code easier. When implementing an interface, group the methods that are part of the interface.|
-|Methods of interfaces that are implemented by the class.|Automatically grouped by functionality if grouped by interface.|
-|Inner classes|As they are only visible within their top-level class, they are placed at the bottom of the file.|
-
-### Indentation
-
-Four spaces should be used as unit of indentation. Use spaces or let your editor convert tabs to spaces as some editors might show the tabs different than they were intended! Tabs must be set exactly every 4 spaces.
-
-#### Line length
-
-There is no explicit limit for the length of a line. Make sure that the flow of the code is clear and that, when printing the file, it is well formed when using a reasonable font. A reasonable length would be around 80 characters.
-
-#### Wrapping lines
-
-When an expression will not fit on a single line, break it according to these general principles:
-- break after a comma;
-- break before an operator;
-- prefer higher level breaks to lower level breaks;
-- align the new line with the beginning of the expression after the assignment;
-- if the above rules lead to confusing code or to code that's squished up against the right margin, please use common sense.
-
-Some examples breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesised expression:
-
-
- longName1 = longName2 * (longName3 + longName4 - longName5)
- + 4; // preferred
- longName1 = longName2 * (longName3 + longName4
- - longName5) + 4;
-
-
-### Comment
-
-#### Comment styles
-
-The Java language supports three different kinds of comments:
-
-
- // text
-
-
-The compiler ignores everything from // to the end of the line. Use this style when adding a description or some kind of explanation at the same line of code.
-
-
- /* text */
-
-
-The compiler ignores everything from /* to */. The next documentation style is preferred.
-
-
- /** Documentation. */
-
-
-This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use /* and */. The JDK JavaDoc tool uses doc comments when preparing automatically generated documentation (See: JavaDoc keywords and HTML tags). But JavaDoc only uses this documentation when it occurs at an expected position in the file like the class definition or a member declaration.
-
-#### Block comments
-
-Block comments are used to provide English descriptions of the contents of files, the task of methods and the description of data structures and algorithms. Block comments should be used at the beginning of each file and before each method. They can also be used in other places, such as within methods.
-
-For a description of class comment see 2.1.3.3 Class and Interface Declarations. A method block comment looks as follows:
-
-
- /**
- * Position the splitter location at a specified position.
- * This method can for instance be used when the last position
- * is stored as a preference setting for the user.
- *
- * @param position New position of divider, defined in pixels
- * from the left of the containing window
- * @see com.sun.java.swing.JSplitPane
- * @exception org.apache.felix.player.PositionException
- * Whenever an invalid position is passed.
- */
- public void setSplitterLocation(int position) throws PositionException
-
-
-#### JavaDoc keywords and HTML tags
-
-For class headers, method headers and member variables JavaDoc is used in order to generate API documentation from the source later on (See: JavaDoc homepage - Sun Microsystems, Inc.).
-A few specific JavaDoc keywords are:
-
-|Keyword|Short description|
-|--|--|
-|@version|Can be used to label a specific version of a package or application so the documentation shows this version number also.|
-|@author|The name entered here is shown as the author.|
-|@param|Used to define one parameter and describe this parameter.|
-|@see|When there are similarities with another class this tag is used to offer the reader a hyperlink to the mentioned class.|
-|@exception or @throws|Offered as hyperlink to the exception that can be thrown by a method.|
-|@return|Return value of a method|
-
-Some HTML-tags that can be used in order to make the comment blocks more readable:
-
-|Tag|Short description|
-|--|--|
-|<p>|New paragraph.|
-|<br>|Break, a carriage return. For separation of two paragraphs, usage of <p> is preferred.|
-|<ul><li></li></ul>|Unordered list of items; each item should start with a <li> tag. By most browsers, this is formatted as a bulleted list.|
-|<code></code>|Code samples; use this when refering to class names, method names, parameter names, etc.|
-|<pre></pre>|Preformatted text. Use these tags to protect figures and schemas "drawn" in Ascii, against formatting by the browser (which normally ignores whitespace and line breaks)|
-|<dl><dt></dt><dd></dd></dl>|Definition lists; <dt> specifies the term that is defined and <dd> the definition of this term. Not frequently used.|
-
-Note: there is no need to embed the parameter name in the @param tag in <code> tags; this is done by javadoc automatically. The same holds for the exception name in the @exception or @throws tag. In the clarifying text however, use the <code> tags when refering to parameter names etc. The example below shows the <code> tag being used for the array parameter in the text, but not in its definition.
-
-Example:
-
- /**
- * Prints a range from an object array. The range
- * is specified by the first element to print, and
- * ranges to the last element of the array.
- *
- * @param array contains the objects to print
- * @param first index of first element in
- * the <code>array</code> to print
- */
- public void printRange(Object[] array, int first)
-
-
-## Java syntax and its layout
-
-### Declarations
-
-When declaring a variable or method make the accessibility as restrictive as possible. When using multiple keywords use the following ordering of keywords:
-
-1. accessibility
- Start with the accessibility as it makes clear if the method or variable is reachable at all.
-1. static (if applicable)
-1. final (if applicable)
-1. return type (methods only) or type (for variables)
- The type is for readability as close as possible to the name.
-
-This order is also compatible with the order that is used in Java for the main() method. This results in following sequence:
-
-
- // A familiar one:
- public static void main(String[] args) {}
- private static String m_lastCreated = null;
- private static final int RED = 4711;
-
-
-#### Number per line
-
-One declaration per line is recommended since it encourages commenting and it does not lead to confusing code. It also is more clear about the explicit initialization of variables as discussed in Initialization.
-
-Example:
-
-
- int level = 0; // level where user enters the system
- int horizontalSize = 0; // horizontal size of current level layer
-
-
-is preferred over:
-
-
- int level, horizontalSize; // level and size of current level layer
-
-
-#### Placement
-
-In a method, declare local variables just before they are needed. This overcomes the problem of a big list of parameters at the beginning of a method and the use of a variable becomes more clearly in the context of the code, .e.g. its initialization.
-
-#### Initialization
-
-The initialization of class variables is strictly not necessary because of the default initialization that takes place for these kinds of members. For some types, e.g. Booleans, this requires detailed knowledge of all the default values so it is more clear and explicit to initialize each member.
-Variables that are used and declared within methods must always be initialized explicitly (the compiler will generate an error when you forget this).
-
-#### Class and Interface Declarations
-
-When coding Java classes and interfaces, the following formatting rules should be followed:
-
-- no space between a method and its parameter list
-- "\{" is on a line by itself indented to match its corresponding opening statetment, except when it is a null statement, in which case the "\{" should appear on the same line as the opening statement
-- "}" starts a line by itself indented to match its corresponding opening statement, except when it is a null statement, in which the case the "}" should appear immediately after the "\{".
-
-Example:
-
-
- class ShipmoTrial extends Trial
- {
- int m_index = 0;
-
- ShipmoTrial(int index)
- {
- m_index = index;
- }
-
- void emptyMethod() {}
- }
-
-
-### Statements
-
-#### Simple statements
-
-Each line should contain at most one statement.
-
-Example:
-
-
- // Do not use this
- argv++; argc++;
-
-
-#### Compound statements
-
-Compound statements are statements that contain lists of statements enclosed in braces ("\{...}"):
-
-- The enclosed statements should be indented one more level than the compound statement.
-- The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement.
-- Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.
-
-#### if, if-else, if else-if else statements
-
-There are a lot of nested possibilities for if-else constructions. All these variations can be programmed in very cryptic ways that easily and often will lead to buggy code. By being more explicit in the used coding style a lot of confusion can be taken away.
-
-Note: When using only one statement in a compound block brackets are optional. It can be a good practice to use always brackets because mistakes can be made easily when adding a second statement and brackets are forgotten.
-
-The following example illustrates the correct use of brackets in a few different if-then-else constructions:
-
-
- if (condition)
- {
- statement1;
- statement2;
- }
- else
- {
- statement3;
- }
-
- if (condition)
- {
- statement1;
- statement2;
- }
- else if (condition1)
- {
- statement3;
- statement4;
- }
- else
- {
- statement5;
- statement6;
- }
-
-
-Note that in the example the else if construction is started at a new line so the statement can not be overlooked.
-
-#### switch
-
-When using a switch statement use following guidelines:
-
-- Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.
-- The so-called fall-through construction should be avoided. Only when there are good reasons to use it, make sure that it is very clear that a fall-through is used (comment it).
-
-The next example shows the sample code that uses the guidelines for a switch statement:
-
-
- switch (condition)
- {
- case A:
- statements;
- // falls through here!!
- case B:
- statements;
- break;
- default:
- statements;
- break;
- }
-
-
-#### try - catch
-
-A try - catch statement should have the following format:
-
-
- try
- {
- statements;
- }
- catch (ExceptionClass ex)
- {
- statements;
- }
-
-
-When using finally to add code that always will be executed this will look like:
-
-
- try
- {
- statements;
- }
- catch (ExceptionClass ex)
- {
- statements;
- }
- finally
- {
- statements;
- }
-
-
-Note that the catch and the finally start at a new line in order to be compliant to the guidelines for if-then-else statements.
-
-### White Space
-
-#### Blank lines
-
-Blank lines improve readability by setting of sections of code that are logically related.
-
-Two blank lines should always be used in the following circumstances:
-
-- between class and interface definitions;
-- between a group of methods that belong together (by its functionality or because they are part of the same interface).
-
-One blank line should always be used in the following circumstances:
-
-- between methods;
-- before a block or single line comment;
-- between logical sections inside a method to improve readability.
-
-#### Blank spaces
-
-Blank spaces should be used in the following circumstances:
-
-- A keyword followed by a parenthesis should be separated by a space.
-
- while (ready == false)
- {
- ...
- }
-
-Note that blanks should not be used between a method call and its opening parenthesis. This helps to distinguish keywords from function calls.
-- Blanks should appear after commas in argument lists.
-- All binary operators except "." should be separated from their operands by spaces. Blanks should never separate unary operators such as unary minus, increment("++") and decrement("--") from their operands.
-
- a += c + d;
- a = (a + b) / (c * d);
- xCoord++;
-
-- The expressions in a for statement should be separated by blanks.
-
- for (expr1; cond1; expr2)
-
-- Casts should be followed by a blank.
-
- myInstance.doIt((TreeFrame) frame);
-
-
-### Naming conventions
-
-Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier.
-
-|Identifier Type|Rules for Naming|Examples|
-|--|--|--|
-
-
-|Interfaces|Interface names should be capitalized like class names.|interface Enumeration;|
-|Methods|Methods should be verbs in mixed case with the first letter lowercase. Within each method name capital letters separate words. Property methods or get-set methods are used as follows:
-
-
-
-
-
-
-|Constant (static final) variables|Names should be all uppercase with words separated by underscores ("_").|public static final int BLACK = 99;|
-|Exceptions|Like class names; always ending in "Exception"|InputException|
-|Packages|Lowercase only; avoid lengthy package names; always start with org.apache.felix.|org.apache.felix.demo.bundle|
-
-Note: All Java identifiers are case sensitive.
-
-## References
-
-- Java Code Conventions - Sun Microsystems, Inc.
- No ref. number, only hyperlink: http://java.sun.com/docs/codeconv/
-- How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc.
- http://java.sun.com/products/jdk/javadoc/writingdoccomments.html
-- JavaDoc homepage - Sun Microsystems, Inc.
- http://java.sun.com/products/jdk/javadoc/
-- [Eclipse formatting template](https://issues.apache.org/jira/secure/attachment/12419890/Apache+Felix+Eclipse+Template.xml).
diff --git a/modules/ROOT/pages/documentation/development/dependencies-file-template.mdtext b/modules/ROOT/pages/documentation/development/dependencies-file-template.mdtext
deleted file mode 100644
index ac7f474..0000000
--- a/modules/ROOT/pages/documentation/development/dependencies-file-template.mdtext
+++ /dev/null
@@ -1,43 +0,0 @@
-Title: DEPENDENCIES file template
-
-Each released software archive must contain a DEPENDENCIES file in it to declare third-party dependencies and their licenses. The following template should be used:
-
-
- Apache Felix AAA
- Copyright BBB The Apache Software Foundation
-
- This software was developed at the Apache Software Foundation
- (http://www.apache.org) and may have dependencies on other
- Apache software licensed under Apache License 2.0.
-
- I. Included Third-Party Software
-
- CCC
-
- II. Used Third-Party Software
-
- DDD
-
- III. Overall License Summary
- - Apache License 2.0
- - EEE
-
-
-Where the placeholders have the following meaning:
-
-* AAA - Name of the Felix subproject.
-* BBB - Copyright year or range of years.
-* CCC - List of third-party software included in the archive.
-* DDD - List of third-party software used (but not included) by the archive.
-* EEE - List of additional third-party licenses as a result of the dependencies.
-
-The format for an individual third-party dependency is flexible, but should try to include the name of the developing organization or individual, a URL, a copyright, and the license. For example, a dependency on OSGi software would look like this:
-
-
- This product includes software developed at
- The OSGi Alliance (http://www.osgi.org/).
- Copyright (c) OSGi Alliance (2000, 2009).
- Licensed under the Apache License 2.0.
-
-
-If you need additional examples on how to fill out a DEPENDENCIES file, look at other examples in the SVN repo or ask on the dev@felix mailing list.
diff --git a/modules/ROOT/pages/documentation/development/provisional-osgi-api-policy.mdtext b/modules/ROOT/pages/documentation/development/provisional-osgi-api-policy.mdtext
deleted file mode 100644
index 6b07eb9..0000000
--- a/modules/ROOT/pages/documentation/development/provisional-osgi-api-policy.mdtext
+++ /dev/null
@@ -1,27 +0,0 @@
-Title: Provisional OSGi API Policy
-
-The OSGi Alliance exposes provisional API that may or may not become part of future OSGi specifications. This policy explains how and when Felix subprojects may relate to such API. Provisional OSGi API refers to anything in the `org.osgi.*` package namespace that is not part of a final released specification.
-
-## Policy
-1. No Felix release may contain or refer to provisional OSGi API.
-1. Provisional API may be included and used in unreleased source code, however the API must be part of a final released OSGi specification before this Felix source may be released.
-1. It is recommended that provisional OSGi API be committed separately from other changes and, if possible, with a reference to its source.
-1. Although it is STRONGLY NOT RECOMMENDED, modified versions of provisional api may be released with these modifications:
-
- 1. Any provisional OSGi API must be recreated in the `org.apache.felix.*` package name space; this effectively makes it provisional Felix API.
- 1. All Felix provisional API must be marked as deprecated.
- 1. All Felix provisional API exported from bundles should be exported with a mandatory attribute of `status="provisional"`.
-
-## Discussion
-
-The first goal of this policy is to completely avoid using provisional OSGi API in released Felix projects given the potential confusion and questions by doing so. The second goal is to make the existence of any released Felix provisional API completely obvious to downstream users and make it difficult for them to use it unknowingly. However, any such release is likely to involve numerous problems such as incorrect semantic versioning or version mismatch between the provisional and event [...]
-
-As an example, to provisionally export the `org.apache.felix.service.metatype` package, the
-`Export-Package` statement would look something like this:
-
- :::xml
- <Export-Package>
- org.apache.felix.service.metatype; version="0.1"; mandatory:="status"; status="provisional"
- </Export-Package>
-
-When working with new OSGi specifications, constructing a Felix provisional API will likely result in parallel package structures between the provisional OSGi and Felix APIs. When working with existing specifications, it may be necessary to create extensions to existing OSGi interfaces in the Felix package namespace.
diff --git a/modules/ROOT/pages/documentation/development/release-management-nexus.mdtext b/modules/ROOT/pages/documentation/development/release-management-nexus.mdtext
deleted file mode 100644
index c953d99..0000000
--- a/modules/ROOT/pages/documentation/development/release-management-nexus.mdtext
+++ /dev/null
@@ -1,345 +0,0 @@
-Title: Release Management
-
-*This is the release process for Apache Felix, based on Apache Maven [process](https://maven.apache.org/developers/release/releasing.html)
-
-## Basics
-
-Apache Felix artifacts are distributed in two channels: The Maven Repository and the Apache
-distribution channels.
-
-The basic steps for releasing are:
-
-* [Release the module with the Maven Release plugin deploying to the Nexus Staging repository](#staging-the-release-candidates)
-* Check the artifacts
-* [Call for vote](#starting-the-vote)
-* [Publish the release candidate](#promoting-the-release):
- * Publish the staged artifacts from Nexus Staging
- * `svn add` the artifacts to the `dist` Subversion repository and `svn rm` the artifacts from the previous release
-* [Announce the release](#create-an-announcement)
-
-<div class="note">
-The Apache Felix PMC appreciates all committers playing release manager for the projects they
-maintain. Due to restrictions imposed on us, only members of the PMC are actually able to
-commit the releases to the distribution repository (See <a href="#promoting-the-release">Publish the release candidate</a>).
-In this case please ask a member of the PMC to actually publish the release artifacts. Thanks.
-</div>
-
-## Prerequisites
-
-To prepare or perform a release you *MUST BE* at least an Apache Felix Committer.
-
-* each and every release must be [SIGNED](https://www.apache.org/dev/release-signing.html); your public key should be added to [https://www.apache.org/dist/felix/KEYS] (see *Appendix A*)
-* your public key should also be cross-signed by other Apache committers (not required, but suggested)
-* make sure you have all Apache servers defined in your [settings.xml](https://maven.apache.org/developers/committer-settings.html)
-* use Maven 3.5.0 (or higher)
-
-*Note*: Listing the Apache servers in the `settings.xml` file also requires adding the password to that file. Starting with Maven 2.1 this password may be encrypted and needs not be give in plaintext. Please refer to [Password Encryption](https://maven.apache.org/guides/mini/guide-encryption.html) for more information.
-
-In the past we staged release candidates on our local machines using a semi-manual process. Now that we inherit from the Apache parent POM version 5, a repository manager will automatically handle staging for you. This means you now only need to specify your GPG passphrase in the release profile of your `$\{user.home\}/.m2/settings.xml`:
-
- :::xml
- <settings>
- ...
- <profiles>
- <profile>
- <id>release</id>
- <properties>
- <gpg.passphrase> <!-- YOUR KEY PASSPHRASE --> </gpg.passphrase>
- </properties>
- </profile>
- </profiles>
- ...
- </settings>
-
-
-Everything else has been configured in the latest Felix parent POM:
-
- :::xml
- <parent>
- <groupId>org.apache.felix</groupId>
- <artifactId>felix-parent</artifactId>
- <version>6</version>
- <relativePath>../pom/pom.xml</relativePath>
- </parent>
-
-
-## Staging the Release Candidates
-
-First prepare your POMs for release:
-
-1. Make sure you have correct NOTICE, [DEPENDENCIES]({{ refs.dependencies-file-template.path }}), and LICENSE files. Remember to update the copyright year.
-1. Make sure you have an updated change log file, typically in `doc/changelog.txt` but in the project root is also acceptable.
-1. Make sure there are no snapshots in the POMs to be released
-1. Check that your POMs will not lose content when they are rewritten during the release process
- * `mvn release:prepare -DdryRun=true`
- * diff the original `pom.xml` with the one called `pom.xml.tag` to see if the license or any other info has been removed. This has been known to happen if the starting `<project>` tag is not on a single line. The only things that should be different between these files are the `<version>` and `<scm>` elements. If there are any other changes, you must fix the original `pom.xml` file and commit before proceeding with the release
-1. Publish a snapshot. This is useful for existing builds that still depend on a snapshot version of this artifact. It means that the snapshot they will be getting is effectively the same as
-the released version.
- <div class="codehilite"><code>$ mvn deploy
- ...
- [INFO] [deploy:deploy]
- [INFO] Retrieving previous build number from apache.snapshots.https
- ...</code></div>
- * if you experience an error during deployment like a HTTP 401 check your settings for the required server entries as outlined in the *Prerequisites*
- * be sure that the generated artifacts respect the Apache release [rules](https://www.apache.org/dev/release.html): NOTICE and LICENSE files should be present in the META-INF directory within the jar. For -sources artifacts, be sure that your POM does not use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4
- * you should verify the deployment under the [snapshot](https://repository.apache.org/content/groups/snapshots/org/apache/felix) repository on Apache
-1. Prepare the release
- <div class="codehilite"><code>$ mvn release:clean
- $ mvn release:prepare</code></div>
- * preparing the release will create the new tag in git, automatically checking in on your behalf
-1. Stage the release for a vote
- <div class="codehilite"><code>$ mvn release:perform</code></div>
- * the release will automatically be inserted into a temporary staging repository for you, see the Nexus [staging documentation](https://www.sonatype.com/books/nexus-book/reference/staging.html) for full details
- * you can continue to use `mvn release:prepare` and `mvn release:perform` on other sub-projects as necessary on the same machine and they will be combined in the same staging repository - this is useful when making a release of the Felix framework and its associated bundles.
-1. Close the staging repository
- * login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.felix* in the list of repositories. In the panel below you should see an open repository that is linked to your username and IP. Right click on this repository and select *Close*. This will close the repository from future deployments and make it available for others to view. If you are staging multiple releases togethe [...]
-1. Verify the staged artifacts
- * if you click on your repository, a tree view will appear below. You can then browse the contents to ensure the artifacts are as you expect them. Pay particular attention to the existence of \*.asc (signature) files. If you don't like the content of the repository, right click your repository and choose *Drop*. You can then rollback your release (see *Canceling the Release*) and repeat the process
- * note the staging repository URL (especially the number at the end of the URL) you will need this in your vote email.
-
-
-## Starting the Vote
-
-Propose a vote on the dev list with the closed issues, the issues left, and the staging repository - for example:
-
- :::text
- To: "Felix Developers List" <de...@felix.apache.org>
- Subject: [VOTE] Release Felix XXX version Y.Z
-
- Hi,
-
- We solved N issues in this release:
- https://issues.apache.org/jira/...
-
- There are still some outstanding issues:
- https://issues.apache.org/jira/...
-
- Staging repository:
- https://repository.apache.org/content/repositories/orgapachefelix-[YOUR REPOSITORY ID]/
-
- You can use this UNIX script to download the release and verify the signatures:
- https://github.com/apache/felix-dev/blob/master/check_staged_release.sh
-
- Usage:
- sh check_staged_release.sh [YOUR REPOSITORY ID] /tmp/felix-staging
-
- Please vote to approve this release:
-
- [ ] +1 Approve the release
- [ ] -1 Veto the release (please provide specific comments)
-
- This vote will be open for 72 hours.
-
-To get the JIRA release notes link, browse to the FELIX [JIRA](https://issues.apache.org/jira/browse/FELIX) page, select [Release Notes|https://issues.apache.org/jira/secure/ConfigureReleaseNote.jspa?projectId=12310100] and choose the relevant sub-project release and format (HTML)
-
-To get the list of issues left in JIRA, select the [Open Issues](https://issues.apache.org/jira/browse/FELIX?report=com.atlassian.jira.plugin.system.project:openissues-panel) tab on the main FELIX page, and select the relevant sub-project.
-
-## Wait for the Results
-
-From [Votes on Package Releases](https://www.apache.org/foundation/voting.html):
-
-> Votes on whether a package is ready to be released follow a format similar to majority approval -- except that the decision is officially determined solely by whether at least three +1 votes were registered. Releases may not be vetoed. Generally the community will table the vote to release if anyone identifies serious problems, but in most cases the ultimate decision, once three or more positive votes have been garnered, lies with the individual serving as release manager. The specifi [...]
-
-The list of binding voters is available at [{{ refs.project-management-committee-pmc.headers.title }}]({{ refs.project-management-committee-pmc.path }})
-
-If the vote is successful, post the result to the dev list - for example:
-
- :::text
- To: "Felix Developers List" <de...@felix.apache.org>
- Subject: [RESULT] [VOTE] Release Felix XXX version Y.Z
-
- Hi,
-
- The vote has passed with the following result :
-
- +1 (binding): <<list of names>>
- +1 (non binding): <<list of names>>
-
- I will copy this release to the Felix dist directory and
- promote the artifacts to the central Maven repository.
-
-If the vote is unsuccessful, you need to fix the issues and restart the process - see *Canceling the Release*.
-If the vote is successful, you need to promote and distribute the release - see *Promoting the Release*.
-
-## Canceling the Release
-
-If the vote fails, or you decide to redo the release:
-
-1. remove the release tag from Subversion (`svn rm ...`)
-1. login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.felix* in the list of repositories. In the panel below you should see a closed repository that is linked to your username and IP (if it's not yet closed you need to right click and select *Close*). Right click on this repository and select *Drop*.
-1. rollback the version in the `pom.xml` and commit any fixes you need to make
-
-<div class="info" markdown="1">
-The release manager is free to either reuse the same version when proposing a new release for vote (for example 2.1.2 after a failed 2.1.2 release attempt), or choose a different number (for example 2.1.4 after a failed 2.1.2 attempt). (cf. vote on 02/14/11).
-</div>
-
-
-## Promoting the Release
-
-If the vote passes:
-
-* [Upload the Artifacts](#upload-the-artifacts)
-* [Release to the Maven Repository](#release-to-the-maven-repository)
-* [Release Bundles to the OBR](#release-bundle-to-the-obr)
-* [Update the Site](#update-the-site)
-
-### Upload the Artifacts
-
-<div class="note">
-If you are not a member of the Apache Felix PMC you might have to ask a member of
-the PMC to execute this step.
-</div>
-
-<div class="note">
-It is recommended to use the check_staged_release.sh script to download your release prior to releasing the staging repository. This will make the task of uploading the release to the Felix releases repository easier.
-</div>
-
-We use the distribution mechanism as described in [How do I upload a release (newer way)?](https://www.apache.org/dev/release.html#upload-ci)
-
-1. Check out the [Felix releases repository](https://dist.apache.org/repos/dist/release/felix);
-1. `svn add` the artifacts to your checkout;
-1. `svn rm` the artifacts from the previous release from your checkout. This
-will remove the artifacts from the main distribution and the mirrors. They
-are still kept in the archive;
-1. `svn commit` your changes.
-
-After committing your changes, the [Apache Felix Dist](https://www.apache.org/dist/felix)
-folder is immediately updated. Updating the mirrors takes another few hours
-(up to a day).
-
-### Release to the Maven Repository
-
-1. Login to [Apache Nexus Repository](https://repository.apache.org) with your Apache SVN credentials;
-1. Click on *Staging*;
-1. Find your closed staging repository, select it, and click the *Release* button;
-1. Click on *Repositories*;
-1. Select the *Releases* repository;
-1. Validate that your artifacts are all there.
-
-### Release Bundles to the OBR
-
-If you're releasing bundles, you can also add them to the Felix Release OBR. To do this, execute the following command
-in a checkout of the release tag (target/checkout if is still around, otherwise a new one):
-
- :::bash
- $ export site=# your checkout of (https://svn.apache.org/repos/asf/felix/site/trunk/content)
- $ export obr=${site}/obr
- $ mvn clean install \
- org.apache.felix:maven-bundle-plugin:deploy \
- -DprefixUrl=https://repo1.maven.org/maven2 \
- -DremoteOBR=releases.xml \
- -DaltDeploymentRepository=apache.website::default::file:///${obr}
- $ svn commit -m"..." ${obr}/repository.xml
-
-After committing the site must be published. If you release to OBR before [updating the site](update-the-site) you can defer publishing until after that.
-Otherwise publish the site by visiting the [Site Publication](https://cms.apache.org/felix/publish) link.
-
-The [releases](https://felix.apache.org/obr/releases.xml) page is updated immediately.
-
-**Note**: the project building the bundle must use the [{{ maven-bundle-plugin.headers.title }}]({{ maven-bundle-plugin.path }}) and use a version equal to or higher than 1.4.2.
-
-**Note**: with Maven 3, you must add an extension to your `<build>` providing the SCP/SSH protocol:
-
- :::xml
- <build>
- ...
- <extensions>
- <extension>
- <groupId>org.apache.maven.wagon</groupId>
- <artifactId>wagon-ssh</artifactId>
- <version>1.0-beta-6</version>
- </extension>
- </extensions>
- </build>
-
-
-### Update the Site
-
-1. Update the news section on the website at [news](https://cms.apache.org/redirect?uri=http%3A//felix.apache.org/news.html);
-1. Update the download page on the website at [downloads](https://cms.apache.org/redirect?uri=http%3A//felix.apache.org/downloads.list) to point to the new release;
-1. Commit your changes (click the commit link);
-1. [Publish the site](https://cms.apache.org/felix/publish).
-
-For the last two tasks, it's better to give the mirrors some time to distribute the uploaded artifacts (one day should be fine). This ensures that once the website (news and download page) is updated, people can actually download the artifacts.
-
-
-## Update JIRA
-
-Go to [Admin](https://issues.apache.org/jira/secure/project/ViewProject.jspa?pid=12310100) section on the FELIX JIRA and mark the Y.Z version as released - create version Y.Z+1, if that hasn't already been done.
-
-
-## Publish Generated Documentation
-
-This procedure applies currently only to the `maven-bundle-plugin`:
-
-1. Checkout the release tag of the plugin
-1. Run `mvn clean package site`
-1. Create a new folder for the new version at `https://svn.apache.org/repos/asf/felix/site/trunk/content/components/bundle-plugin-archives/bundle-plugin-<version>` and publish the generated site from `target/site` there
-1. Remove the previous documentation from `components/bundle-plugin` and SVN-copy the new version there as well
-
-
-## Create an Announcement
-
-
- :::text
- To: "Felix Users List" <us...@felix.apache.org>
- Subject: [ANN] Felix XXX version Y.Z Released
-
- The Felix team is pleased to announce the release of Felix XXX version Y.Z
-
- <<insert short description of the sub-project>>
-
- https://felix.apache.org/site/apache-felix-XXX.html
-
- This release is available from https://felix.apache.org/site/downloads.cgi and Maven:
-
- <dependency>
- <groupId>org.apache.felix</groupId>
- <artifactId>org.apache.felix.XXX</artifactId>
- <version>Y.Z</version>
- </dependency>
-
- Release Notes:
-
- <<insert release notes in text format from JIRA>>
-
- Enjoy!
-
- -The Felix team
-
-
-Remember to forward this announcement to `users@felix.apache.org` - try *not* to cross-post (CC:\) announcements to both user and dev lists.
-
-*Remind Carsten about this release when he writes the next board report ;)*
-
-## Appendix A: create and add your key to https://www.apache.org/dist/felix/KEYS
-
-If you are using a *nix system with a working OpenSSH, GnuPG, and bash you can create and add your own key with the following command:
-
- :::bash
- $ gpg --gen-key
-
-When gpg asks for e-mail linked the key you *MUST USE* the <committer>@apache.org one.
-When gpg asks for comment linked the key you *SHOULD USE* "CODE SIGNING KEY".
-
-Second, *Add the key to* (https://dist.apache.org/repos/dist/release/felix/KEYS).
-
-Only PMC members can commit to files in the dist area, so you should do the key export in the
-shell commands below, and send the results along to a friendly PMC member for assistance.
-
-Type the following command replacing the word e-mail with your Apache's one (<committer>@apache.org). To update you have to checkout the Felix
-dist release repository (you also need this to publish a release):
-
- :::bash
- $ (gpg --list-sigs e-mail && gpg --export --armor e-mail) > toadd.key
-
-Provide the file to a PMC member, who will:
-
- :::bash
- $ svn checkout https://dist.apache.org/repos/dist/release/felix felix-dist
- $ cat toadd.key >> felix-dist/KEYS
- $ scn commit -m"KEYS += <committer>" felix-dist/KEYS
-
-You are now *DONE* and the changes are visible on https://www.apache.org/dist/felix/KEYS.
-
-
diff --git a/modules/ROOT/pages/documentation/development/site-how-to.mdtext b/modules/ROOT/pages/documentation/development/site-how-to.mdtext
deleted file mode 100644
index 99a5cd9..0000000
--- a/modules/ROOT/pages/documentation/development/site-how-to.mdtext
+++ /dev/null
@@ -1,201 +0,0 @@
-Title: Site How To
-
-The site is managed with the [Apache CMS](https://www.apache.org/dev/cms.html)
-where the source is kept in SVN at <https://svn.apache.org/repos/asf/felix/site/trunk/content>.
-
-## To update the documentation using the CMS system
-
-* Install the bookmarklet from the [cms](https://cms.apache.org/) page. You only have to do this once.
-* Navigate to the page you wish to edit (on the live site, not in the cms).
-* Click the bookmarklet. There will be a short pause while the CMS system is initialised for you.
-* Click on `Edit` (to skip this step hack the bookmarklet to add an 'action=edit' param to the query string)
-* The page editor should then be displayed.
-* Click `Submit` to save your edit to the workarea
-* Click `Commit` to save the updated file to SVN and trigger a staged build. (to skip this step click on the "Quick Commit" checkbox in the `Edit` form).
-* The results should appear shortly on the [staging](http://felix.staging.apache.org/content/documentation.html) site. (You may have to force the page to refresh in order to see the updated content)
-* Once you are happy with the updated page, click on `Publish Site` to deploy.
-
-There is also a [Reference Manual](https://www.apache.org/dev/cmsref.html) of the Apache CMS as well as a
-video tutorial at <http://s.apache.org/cms-tutorial>.
-
-## Features of the Apache Felix Site
-
-This section lists some Apache Felix features to help with the maintenance
-of the site, such as automatic link generation.
-
-Start the file with a `Title:` line to define the page title and the first H1 tag:
-
- Title: Page Title
-
- Here comes the content separated with a blank like from the
- header ...
-
-The last modification information from SVN (revision, committer, and
-date/time) is automatically added when the page is rendered
-
-Excerpts can be added to a page using the `Excerpt:` header:
-
- Title: Page Title
- Excerpt: Summary of the page for inclusion in other pages;
- continuation of the excerpt must be indented
-
- Here comes the content separated with a blank like from the
- header ...
-
-Metadata from child pages can be referred to in the content with the
-Django variable reference notation using the child page name (without
-extension) as its container; e.g. for the child page named `childpage`:
-
- :::django
- {{ y|default:"{{" }} children.childpage.headers.excerpt }}
- {{ y|default:"{{" }} children.childpage.headers.title }}
-
-Content Pages can contain Django templates of the form `{{ y|default:"{{" }}...}}` and `{{ y|default:"{%" }}...%}`.
-If so, the page content is evaluated as a Django template before running
-it through the page template.
-
-Any page in the site can be referenced with refs.pagename returning properties:
-
-`.path`
-: the absolute path of the page on the site
-
-`.headers`
-: page headers (e.g. `.title`, `.excerpt`)
-
-`.content`
-: the raw page content
-
-All pages in the children namespace are also available in the refs namespace
-
-Some usefull hints:
-
-Printing title of another page "handler":
-
- :::django
- {{ y|default:"{{" }} refs.handler.headers.title }}
-
-Printing excerpt of another page "handler":
-
- :::django
- {{ y|default:"{{" }} refs.handler.headers.excerpt }}
-
-Linking to another page "handler":
-
- :::django
- ({{ y|default:"{{" }} refs.handler.path }})
-
-Printing title as a link to another page "handler":
-
- :::django
- [{{ y|default:"{{" }} refs.handler.headers.title }}]({{ y|default:"{{" }} refs.handler.path }})
-
-Printing excerpt as a link to another page "handler":
-
- :::django
- [{{ y|default:"{{" }} refs.handler.headers.excerpt }}]({{ y|default:"{{" }} refs.handler.path }})
-
-Print a bullet pointed child page list:
-
- :::django
- {{ y|default:"{%" }} for label, page in children %}* [{{ y|default:"{{" }} page.headers.title }}]({{ y|default:"{{" }} page.path }})
- {{ y|default:"{%" }} endfor %}
-
-<div class="note">
-It is important to have the first part as a single line, otherwise
-the Django/Markdown combo will create a list for each entry.
-</div>
-
-
-## Code Highlighting
-
-Code Highlighting works by indenting code by four blanks. To indicate the
-type of highlighting preced the code style text with either `:::<lexer>` to
-get high lighted code using the given `<lexer>` or `#!<lexer>` to get high
-lighted code with line numbers using the given `<lexer>`. See
-<http://www.apache.org/dev/cmsref.html#code-hilighter> for main info and
-<http://pygments.org/docs/lexers/> for supported lexers
-
-
-## HTML and Markdown
-
-Markdown supports embedding HTML. But be aware that contents of HTML elements
-are not further handled by the Markdown converter. Thus it is not possible
-to embed Markdown syntax inside of HTML elements to have them converted.
-
-
-## Manual Generation
-
-When commiting changes to pages into SVN the pages are automatically
-generated in [the staging site](http://felix.staging.apache.org).
-
-<div class="info">
-<p>To generate the site locally, you must have checked out the complete SVN to access the tools:</p>
-
-<div class="codehilite"><pre><span class="nv">$ </span>svn <span class="s2">https://svn.apache.org/repos/asf/felix/site/ felix-site</span>
-</pre></div>
-</div>
-
-To manually generate the site or single pages the [site](http://svn.apache.org/repos/asf/felix/site)
-can be checked out from SVN. In addition Perl and Python must be installed
-for the build tools to work.
-
-To prepare for site build, the Markdown daemon has to be started:
-
- :::sh
- $ export MARKDOWN_SOCKET="$PWD/tools/build/../markdown.socket"
- $ export PYTHONPATH="$PWD/tools/build"
- $ python "$PWD/tools/build/markdownd.py"
-
-
-
-The `MARKDOWN_SOCKET` environment variables is also required by the `build_site.pl`
-and `build_file.pl` scripts to connect to the Markdown daemon.
-
-To build the complete site use the `build_site.pl` script:
-
- :::sh
- $ tools/build/build_site.pl --source-base $PWD/trunk \
- --target-base $PWD/trunk/target
-
-To build a single page use the `build_file.pl` script:
-
- :::sh
- $ tools/build/build_site.pl --source-base $PWD/trunk \
- --target-base $PWD/trunk/target \
- --source content/documentation.mdtext
-
-The argument to the `--source` parameter is relative to the `--source-base` folder.
-
-## Configuring site generation on Mac
-
-<div class="info">
-Those instructions were computed on Mountain Lion.
-</div>
-
-A couple of Python and Perl libraries are required and need to be installed
-
- :::sh
- $ sudo easy_install Pygments
- $ sudo easy_install Markdown
-
-And for the Perl modules:
-
- :::sh
- $ sudo cpan install XML::Atom::Feed
- $ sudo cpan install XML::RSS::Parser
- $ sudo cpan install XML::Parser::Lite
- $ sudo cpan install XML::RSS::Parser::Lite
- $ sudo cpan install Net::Twitter
- $ sudo cpan install SVN::Client
-
-Be careful that some of those commands require time... Once done, launch the mardown daemon with the following command from the SVN root:
-
- :::sh
- $ export MARKDOWN_SOCKET="$PWD/tools/build/../markdown.socket"
- $ export PYTHONPATH="$PWD/tools/build"
- $ python "$PWD/tools/build/markdownd.py"
-
-And finally, generate the web site from the svn root with:
-
- :::sh
- tools/build/build_site.pl --source-base $PWD/trunk --target-base $PWD/trunk/target
diff --git a/modules/ROOT/pages/documentation/development/using-the-osgi-compliance-tests.mdtext b/modules/ROOT/pages/documentation/development/using-the-osgi-compliance-tests.mdtext
deleted file mode 100644
index aa9ea6d..0000000
--- a/modules/ROOT/pages/documentation/development/using-the-osgi-compliance-tests.mdtext
+++ /dev/null
@@ -1,213 +0,0 @@
-Title: Using the OSGi Compliance Tests
-
-The OSGi Alliance provides Apache committers access to its Compliance Tests (CT). This
-page describes how to get access to the CTs and how to use them with Felix subprojects.
-
-
-## Gaining Access to OSGi CTs
-
-The general process is to send a request to the jcp-open@apache.org mailing requesting
-access. Since redistributing the OSGi CTs is not allowed, you will need to submit an
-[NDA](http://www.apache.org/jcp/ApacheNDA.pdf) to be granted access to the
-[SVN repo](https://svn.apache.org/repos/tck/osgi-cts) containing the binaries.
-
-
-## OSGi CT Overview
-
-The CT is delivered as three JAR files, one for the core CT, one of the enterprise CT and one for the compendium CT.
-Each JAR file is composed of several other JAR files, which are the actual compliance
-tests. Typically, there is one JAR per specification, except for the OSGi framework. The
-CT uses BND as its testing harness, which in turn uses the OSGi framework launching
-and embedding API to configure, launch, and install test bundles. Each test JAR file has
-an associated BND file which supplies the configuration BND needs to run the associated tests.
-
-
-## Modifying the BND files
-
-Modifying the BND files is fairly straightforward. A typical BND file looks like this:
-
- :::plaintext
- # bnd pack for project org.osgi.test.cases.startlevel
- # Mon Aug 31 18:50:18 EDT 2009
- build=.
-
- -target = \
- jar/org.osgi.test.cases.startlevel-4.2.0.jar;version=file,
-
- -runpath = \
- jar/org.eclipse.osgi-3.5.1.jar;version=file, \
- jar/com.springsource.junit-3.8.2.jar;version=file;export="junit.framework;version=3.8"
-
- -runbundles
-
- -runproperties = \
- report="true", \
- osgi.compatibility.bootdelegation="false", \
- osgi.resolverMode="strict"
-
-
-The important parts are the following settings:
-
-* `-target` specifies the bundles containing the tests.
-* `-runpath` specifies the class path used to run the tests.
-* `-runbundles` specifies the bundles to install for the tests.
-* `-runproperties` specifies configuration properties to pass into the framework.
-
-The following two examples show how to edit these files for the Felix framework and Felix
-bundle subprojects.
-
-## Testing the Felix framework
-
-The Felix framework is tested against the core CT. The first thing to do is extract the core
-CT JAR file, which includes test suites for:
-
-###Core functionality
-
-* Framework core (`org.osgi.test.cases.framework.bnd`)
-* Framework launching (`org.osgi.test.cases.framework.launch.bnd`)
-* Tracker Specification (`org.osgi.test.cases.tracker.bnd`)
-* URL Handlers (`org.osgi.test.cases.url.bnd`)
-
-While the Tracker and URL Handler specifications are optional as per the OSGi Specification, they are implemented by the
-Felix Framework and therefore the tests should be run and pass.
-
-The following CT tests from the Compendium/Enterprise CT also pass with the Felix framework:
-
-* XML Parser Specification (`org.osgi.test.cases.xml.bnd`)
-
-###Security components
-
-OSGi Security components are optional. They are supported by Felix but require
-security support to be enabled. See the [Security][1] section below for more details.
-
-* Framework security (`org.osgi.test.cases.framework.secure.bnd`)
-* Framework launching security (`org.osgi.test.cases.framework.launch.secure.bnd`)
-* Permission Admin (`org.osgi.test.cases.permissionadmin.bnd`)
-* Conditional Permission Admin (`org.osgi.test.cases.condpermadmin.bnd`)
-
-With security correctly enabled in Felix all the above security CT suites should pass.
-
-### Running the tests
-
-For each of the associated BND files, the `-runpath` needs to be edited to refer to the Felix
-framework. The easiest way to do this is by modifying the `shared.inc` file which is included by
-all BND files. It should look something like this after editing:
-
- :::plaintext
- -runpath = \
- /path/to/felix/framework/org.apache.felix.framework-4.4.1.jar;version=file, \
- jar/com.springsource.junit-3.8.2.jar;version=file;export="junit.framework;version=3.8"
-
-
-Typically, it is not necessary to change anything else in the BND files and it is normal that
-the `-runbundles` setting is empty, since there are no additional bundles associated with
-testing the framework.
-
-After editing the BND files, run the tests using:
-
- :::plaintext
- source runtests
-
-
-This will run all test suites for all BND files. To run a specific test suite, do the following:
-
-
- :::bash
- $ java -jar jar/bnd.jar runtests --title osgi.ct <bnd-file>
-
-
-Where `<bnd-file>` specifies one or more BND files associated with the desired test suites.
-
-<div class="note" markdown="1">
-<b>Be Aware</b>
-Tests for native code loading will fail on Java 6, so do not use this JDK for testing the
-framework.
-</div>
-
-Reports for the tests suites are generated in the `reports/` subdirectory and are named
-after the appropriate test suite.
-
-### <a id="security"></a>Security
-***TODO this section is unfinished.***
-
-The exception to this is for the framework test suites for security.
-To test with security enabled, you will need to add the framework security provider in
-`-runbundles` like this:
-
- :::plaintext
- -runbundles = \
- /path/to/felix/framework.security/org.apache.felix.framework.security-1.0.0.jar.jar;version=file
-
-
-### Deviations
-#### Core R5
-When running the Core R5 CT the following error appears:
-
- :::plaintext
- testEERequirement
- junit.framework.AssertionFailedError: Required Execution Environment is available: Unresolved constraint in bundle org.osgi.test.cases.framework.div.tb7a [214]: Unable to resolve 214.0: missing requirement [214.0] osgi.ee; (|(osgi.ee=div/tb7a)(osgi.ee=div/tb7b))
- at org.osgi.test.support.OSGiTestCase.fail(OSGiTestCase.java:70)
- at org.osgi.test.cases.framework.junit.div.DivTests.testEERequirement(DivTests.java:253)
-
-This is a known deviation in the Core R5 CT and can be ignored.
-
-#### Core R6
-When running the Core R6 CT the following error appears:
-
- :::plaintext
- testArrayServiceReferenceDTO
- junit.framework.AssertionFailedError: ServiceReferenceDTO[] for stopped bundle is null
- at junit.framework.Assert.fail(Assert.java:47)
- at junit.framework.Assert.assertTrue(Assert.java:20)
- at junit.framework.Assert.assertNotNull(Assert.java:217)
- at org.osgi.test.cases.framework.junit.dto.DTOTestCase.testArrayServiceReferenceDTO(DTOTestCase.java:429)
-
-This is a known deviation in the Core R6 CT and can be ignored.
-
-## Testing a Felix bundle
-
-The core CT tests the framework implementation and its related services. The compendium CT
-tests the various non-framework-related specifications, which are implemented as bundles. For
-the most part, testing a bundle is similar to testing the framework.
-
-Extract the compendium CT JAR file to access the individual test suites. Since most compendium
-service specification test suites require security, it is necessary to use a framework
-implementation that supports security. For the Felix framework, you will have to add the
-security provider to the `-runbundles` to enable security.
-
-For example, to test Felix' Event Admin bundle, edit the `-runbundles` setting in
-`org.osgi.test.cases.event.bnd` to look something like this:
-
- :::plaintext
- -runbundles = \
- /path/to/felix/eventadmin/org.apache.felix.eventadmin-1.0.0.jar;version=file,\
- /path/to/felix/framework.security/org.apache.felix.framework.security-1.0.0.jar.jar;version=file
-
-
-After editing the BND files to refer to the appropriate bundles, run the tests using:
-
-
- :::plaintext
- source runtests
-
-
-This will run all test suites for all BND files. To run a specific test suite, do the following:
-
-
- :::bash
- $ java -jar jar/bnd.jar runtests --title osgi.ct <bnd-file>
-
-
-Where `<bnd-file>` specifies one or more BND files associated with the desired test suites.
-Reports for the tests suites are generated in the `reports/` subdirectory and are named
-after the appropriate test suite.
-
-
-## Feedback
-
-For any questions or feedback, subscribe to the Felix developers mailing list by sending a
-message to [dev-subscribe@felix.apache.org](mailto:dev-subscribe@felix-apache-org); after
-subscribing, email questions or feedback to [dev@felix.apache.org](mailto:dev@felix.apache.org).
-
-
- [1]: #security
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/faqs.mdtext b/modules/ROOT/pages/documentation/faqs.mdtext
deleted file mode 100644
index ed3f09d..0000000
--- a/modules/ROOT/pages/documentation/faqs.mdtext
+++ /dev/null
@@ -1,6 +0,0 @@
-Title: Frequently Asked Questions
-
-* [OSGi FAQ]({{ refs.apache-felix-osgi-faq.path }}) - Contains answers to general OSGi-related questions.
-* [Framework FAQ]({{ refs.apache-felix-framework-faq.path }}) - Contains answers to questions that are specifically related to Felix' OSGi framework implementation.
-* [Bundle Plugin FAQ]({{ refs.apache-felix-bundle-plugin-faq.path }}) - Contains answers to questions about the Felix maven-bundle-plugin
-* [SCR Plugin FAQ]({{ refs.apache-felix-scr-plugin-faq.path }}) - Contains answers to questions about the Felix maven-scr-plugin
diff --git a/modules/ROOT/pages/documentation/faqs/apache-felix-bundle-plugin-faq.mdtext b/modules/ROOT/pages/documentation/faqs/apache-felix-bundle-plugin-faq.mdtext
deleted file mode 100644
index eb8abae..0000000
--- a/modules/ROOT/pages/documentation/faqs/apache-felix-bundle-plugin-faq.mdtext
+++ /dev/null
@@ -1,179 +0,0 @@
-Title: Apache Felix Bundle Plugin Frequently Asked Questions
-
-[TOC]
-
-## When I embed a dependency why do I see duplicated content?
-
-Having two copies of classes, both unpacked and embedded as jars, is a sign that your Embed-Dependency and Export-Package instructions are overlapping. Export-Package tells BND to pull in classes found in the named packages from the build classpath and add them to the bundle, Embed-Dependency tells BND to embed (or inline if enabled) whole artifacts in the bundle.
-
-so say I have:
-
-
- Export-Package: org.objectweb.asm.*
-
-
-and I have the asm artifact as a compile scope dependency, then I would see the org.objectweb.asm classes unpacked in the bundle, ie. pulled in by BND.
-
-say I now decide to embed asm as a jar, for example with:
-
-
- Embed-Dependency: *;scope=compile|runtime
-
-
-I would now see the asm artifact embedded inside bundle - but I would also see the unpacked classes from before, because I'm still asking BND to pull them in (you will probably also see split package warnings during the build).
-
-ok - so how do I embed asm as a jar, but mark its packages as exported without pulling in the unpacked classes... well, there is another export instruction added for exactly this reason:
-
-
- -exportcontents: org.objectweb.asm.*
-
-
-(this is <_exportcontents> in the POM because a tag can't start with '-')
-
-this instruction is merged with Export-Package, after BND has decided on the content of the bundle - that is, it works just like Export-Package except that it won't alter the content of the bundle.
-
-So by removing org.objectweb.asm.* from Export-Package and using the -exportcontents instruction instead along with Embed-Dependency, I can now embed the asm artifact in my bundle and export its packages:
-
-
- Embed-Dependency: *;scope=compile|runtime
- -exportcontents: org.objectweb.asm.*
-
-
-## Why do I see more classes in my bundle after upgrading to maven-bundle-plugin 2.0.0?
-
-Before 2.0.0 the maven-bundle-plugin only passed local classes and compile scope dependencies to bnd. This was because the main BundlePlugin mojo used "@requiresDependencyResolution runtime" which asks Maven to only resolve dependencies of compile or runtime scope (the maven-bundle-plugin also explicitly filtered runtime scope dependencies from the classpath passed to bnd). Because bnd only had a fraction of the original classpath used to compile the bundle classes it meant that imported [...]
-
-In 2.0.0 a conscious decision was made to pass the complete classpath to bnd so it would have the complete set of information used during compilation. To do this the @requiresDependencyResolution setting was changed to "test" so all dependencies will now be resolved. Furthermore only test scope artifacts are now filtered from the final classpath passed to bnd.
-
-For most users passing more of the original compilation classpath to bnd simply means you get more accurate and consistent results. However, if you happened to rely on the old behaviour (perhaps by setting Private-Package: * to pull in all local and compile scope classes) then you will see more classes added to your bundle as the wildcard matches against additional content in the classpath.
-
-There are two solutions when this happens:
-
-* Change your Private-Package / Export-Package instructions to more accurately describe what you want in your bundle
-* Add the following setting to remove provided and runtime scope dependencies from the classpath passed to bnd:
-
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <configuration>
- <excludeDependencies>*;scope=provided|runtime</excludeDependencies>
- </configuration>
- </plugin>
-
-
-This second option effectively switches the maven-bundle-plugin back to the old 1.X behaviour.
-
-Please also note that since 2.0.0 the maven-bundle-plugin also sets default Export-Package and Private-Package instructions based on your local source files, so you might well find that simply removing any Private-Package and/or Export-Package instructions from your pom.xml will actually produce the correct result.
-
-## Why do I get an exception (Unsupported major.minor version 49.0) when I build with a 1.4 or earlier JDK?
-
-The latest maven-bundle-plugin (2.0.0) uses a new release of bnd which requires Java5. This means you now have to build your bundle projects using a Java5 (or later) JDK. Note that you can still compile classes for earlier releases of the JVM by setting the appropriate source and target levels in your pom.xml:
-
-
- <plugin>
- <artifactId>maven-compiler-plugin</artifactId>
- <configuration>
- <source>1.4</source>
- <target>1.4</target>
- </configuration>
- </plugin>
-
-
-## When I build a bundle, some classes are built in "target/classes" but they're not included in the final jar.
-
-The only classes that will appear in the bundle are the ones you ask it to include using Export-Package, Private-Package, Include-Resource, and Embed-Dependency - so just because a file exists under target/classes does NOT mean it will end up in the bundle. This is because this is the way the underlying [BND](http://bnd.bndtools.org/) tool works (it is primarily pull-based).
-
-Now the bundleplugin will look at your Maven project and add appropriate BND instructions to pull in resource files - and version 2.0.0 will also look at your source directory to set reasonable defaults for Export-Package and Private-Package (unless you set these yourself). So when using bundleplugin 2.0.0 I'd use the default Private-Package and Export-Package to begin with - I would then move towards using an explicit list of packages in Export-Package to add versioning, directives, etc.
-
-The only time I would set Private-Package would be to have more control over what ends up in the bundle - either to remove certain packages or perhaps pull in additional packages not found by the source scanner. Also note that both Export-Package and Private-Package accept wildcards such as "org.example.\*" which can reduce the number of entries in the list, but you should be careful not to set either the export or private instruction to "\*" as this would pull in the entire classpath... [...]
-
-## How do I remove the generated Maven information from the resulting bundle JAR file?
-
-Use the following archive setting:
-
-
- <configuration>
- <archive>
- <addMavenDescriptor>false</addMavenDescriptor>
- </archive>
- </configuration>
-
-
-Put this in either the JAR or bundle plugin configuration.
-
-## Why do some generated resources (such as Declarative Services XML files) appear in the final jar, but others don't?
-
-When you use the Service-Component instruction to specify Declarative Services the BND tool scans the project classpath for components and automatically adds its generated XML to the final bundle, therefore Include-Resource is not necessary. But if you generate files under OSGI-INF using another mechanism then they won't end up in the bundle unless you add that directory using Include-Resource (this goes back to the core design decision that BND pulls classes and resources into the bundl [...]
-
-## Use SCR metadata generated by BND in Unit Tests
-
-BND and the maven-bundle-plugin support the generation of SCR metadata for OSGi Declarative Service components annotated with the OSGi annotations from the Java package `org.osgi.service.component.annotations`.
-
-To enable this you have to set two special instructions in your maven-bundle-plugin configuration:
-
-
- <configuration>
- <instructions>
- <!-- Enable processing of OSGI DS component annotations -->
- <_dsannotations>*</_dsannotations>
- <!-- Enable processing of OSGI metatype annotations -->
- <_metatypeannotations>*</_metatypeannotations>
- </instructions>
- </configuration>
-
-
-This generates the SCR metadata files at `/OSGI-INF` and `/OSGI-INF/metatype` when building the JAR file.
-
-If you want to run unit test in the same maven projects that need these SCR metadata files when running the tests (e.g. when using [OSGi Mocks](http://sling.apache.org/documentation/development/osgi-mock.html)) you need some special configurations to ensure the SCR metadata is also generated in the filesystem in the maven target folder, and is already available when the unit tests are executed and not only in the package phase:
-
-
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <extensions>true</extensions>
- <executions>
- <!-- Configure extra execution of 'manifest' in process-classes phase to make sure SCR metadata is generated before unit test runs -->
- <execution>
- <id>scr-metadata</id>
- <goals>
- <goal>manifest</goal>
- </goals>
- <configuration>
- <supportIncrementalBuild>true</supportIncrementalBuild>
- </configuration>
- </execution>
- </executions>
- <configuration>
- <exportScr>true</exportScr>
- <instructions>
- <!-- Enable processing of OSGI DS component annotations -->
- <_dsannotations>*</_dsannotations>
- <!-- Enable processing of OSGI metatype annotations -->
- <_metatypeannotations>*</_metatypeannotations>
- </instructions>
- </configuration>
- </plugin>
-
-
-The flag `supportIncrementalBuild` is only necessary when you are using Eclipse and m2e, it supports generating the appropriate metadata during incremental builds. When you also want to support the old-style Felix SCR annotations from Java package `org.apache.felix.scr.annotations` you can add this BND plugin:
-
-
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <!-- Support parsing of maven-scr-plugin annotations through the felix.scr.bnd plugin -->
- <_plugin>org.apache.felix.scrplugin.bnd.SCRDescriptorBndPlugin;destdir=${project.build.outputDirectory}</_plugin>
- </instructions>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.apache.felix</groupId>
- <artifactId>org.apache.felix.scr.bnd</artifactId>
- <version>1.9.4</version>
- </dependency>
- </dependencies>
- </plugin>
-
diff --git a/modules/ROOT/pages/documentation/faqs/apache-felix-scr-plugin-faq.mdtext b/modules/ROOT/pages/documentation/faqs/apache-felix-scr-plugin-faq.mdtext
deleted file mode 100644
index 1ae7de2..0000000
--- a/modules/ROOT/pages/documentation/faqs/apache-felix-scr-plugin-faq.mdtext
+++ /dev/null
@@ -1,71 +0,0 @@
-Title: Apache Felix SCR Plugin Frequently Asked Questions
-
-[TOC]
-
-This page provides answers to frequently asked questions using the Maven
-SCR Plugin. See [{{ refs.apache-felix-maven-scr-plugin.headers.title }}]({{ refs.apache-felix-maven-scr-plugin.path }})
-for documentation on that plugin.
-
-## Should I still use the Apache Felix SCR annotations over the official OSGi annotations?
-
-Starting with the R6 release of the OSGi Declarative Services and Metatype specification, the official annotations support the same features as the Apache Felix SCR annotations in a more elegant manner and even provide additional functionality. Therefore the Apache Felix SCR annotations are now in maintenance mode and therefore you should rather use the official annotations. The Apache Felix maven-bundle-plugin, version 3.0.1 or higher supports those directly and there is no need for an [...]
-
-## Why are the (standard) annotations not processed?
-
-In order to process any annotations, a processor for them needs to be added as a dependency to your project. There are currently two different processors, one for the annotations defined within the Apache Felix project and another one for the standard annotations from the Declarative Services specification.
-## Syntax Error when Enums are used?
-
-During a SCR plugin run, a syntax error might occur if enums are used in the source code. This is a know problem of the used QDox version that reads the Java source files. Usually this happens when an enum is used inline and does not end with a ";". So adding this character should solve the problem:
-
- :::java
- public interface MyTest {
-
- /** more error codes may be added */
- enum Result {
- OK, UNKNOWN, ERROR, DENIED
- }; // <!-- HERE
-
- /** @return the result */
- public void getResult();
- }
-
-
-## NoClassDefFoundError during build
-
-This error might happen with older versions of the Maven SCR Plugins in combination with javadoc tags or newer versions in combination with the annotations.
-In both cases, the scanned classes have to be loaded and static fields have to be initialized. If you have have for example something like
-
- :::java
- private static final org.slf4f.Logger LOGGER = org.slf4j.LoggerFactory.getLogger("name");
-
-in your code, during the plugin run, a slf4j logger is tried to be instantiated. This requires an implementation of the logger. Ususally your module only depends on the slf4j API and therefore a
-
- :::plaintext
- java.lang.NoClassDefFoundError: org/slf4j/impl/StaticLoggerBinder
-
-is thrown - this often happens with slf4j but might also happen with other libraries.
-
-In these cases you should add a dependency to the missing class to the dependency list of the plugin, for example:
-
- :::xml
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-scr-plugin</artifactId>
- <version>...</version>
- <dependencies>
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-simple</artifactId>
- <version>1.5.2</version>
- </dependency>
- </dependencies>
- ...
- </plugin>
-
-or in the special case of slf4j, using slf4j API 1.6 or higher solves the problem as well
-
-## No components or services available at runtime
-
-The SCR plugin generates a descriptor for Declarative Services (see OSGi compendium specification). Therefore at runtime, you must have an implementation of DS running in your OSGi framework, like the SCR implementation from the Apache Felix project.
-
-Otherwise your bundle might resolve fine, however no services are registered with the service registry and no components are activated.
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/getting-started.mdtext b/modules/ROOT/pages/documentation/getting-started.mdtext
deleted file mode 100644
index 57763db..0000000
--- a/modules/ROOT/pages/documentation/getting-started.mdtext
+++ /dev/null
@@ -1,11 +0,0 @@
-Title: Getting Started
-
-For first-time users, here are a few links that might get you started more quickly:
-
-* [Downloads](https://felix.apache.org/downloads.cgi) - Go to the download page and download and extract the Felix release.
-* [Launching Felix]({{ refs.apache-felix-framework-usage-documentation.path }}) - Go to the Felix usage page to learn how to launch the Felix framework.
-* [OSGi tutorial]({{ refs.apache-felix-osgi-tutorial.path }}) - Go to the tutorial page to learn some OSGi basics.
-* [OSGi FAQ]({{ refs.apache-felix-osgi-faq.path }}) - Check out the OSGi FAQ for answers to common questions.
-* [Documentation]({{ refs.documentation.path }}) - Search the documentation pages for additional examples and presentations or subproject documentation to learn about specific subprojects.
-
-If you are unable to find the documentation you need, please ask on the [mailing lists]({{ refs.mailinglists.path }}). Also, feedback on improving the documentation and/or organization of this site is welcome.
diff --git a/modules/ROOT/pages/documentation/subprojects.mdtext b/modules/ROOT/pages/documentation/subprojects.mdtext
deleted file mode 100644
index 53fded2..0000000
--- a/modules/ROOT/pages/documentation/subprojects.mdtext
+++ /dev/null
@@ -1,61 +0,0 @@
-# Apache Felix Subproject Documentation
-
-## Building Apache Felix
-
-The Felix project is organized into subprojects, where each subproject targets a specific OSGi specification or OSGi-related technology. Most of these projects are in a single git repository, some have moved into separate git repositories.
-
-Use the below table of subprojects to find the git repository for that subproject, if you want to checkout the [main git repository](https://github.com/apache/felix-dev.git) with most subprojects use `git clone https://github.com/apache/felix-dev.git`, otherwise use the git repository mentioned in the table.
-
-To get started:
-
-- Most Apache Felix projects use Apache Maven as the build tool. Therefore, download and install the latest Apache Maven 3 release.
-- Check out or update the git repository (see above).
-- Go to the sub project you're interested in and type: "mvn clean install" to build it. If this project is not using Maven, refer to the docs for the subproject on how to build it.
-
-## Active subprojects
-
-|Name|Description|Source|
-|--|--|--|
-|[Atomos](https://github.com/apache/felix-atomos)|An OSGi module connector that enables loading bundles in a variety of environments, such as, jlink image, native-image, Android and flat class path. |[source](https://github.com/apache/felix-atomos)|
-|[Config Admin](https://github.com/apache/felix-dev/tree/master/configadmin)|An implementation of the [OSGi Configuration Admin service specification](https://osgi.org/specification/osgi.cmpn/7.0.0/service.cm.html) for managing bundle configuration properties.|[source](https://github.com/apache/felix-dev/tree/master/configadmin)|
-|[Dependency Manager](subprojects/apache-felix-dependency-manager.html)|An API-based component model to simplify OSGi-based development.|[source](https://github.com/apache/felix-dev/tree/master/dependencymanager)|
-|[Event Admin](subprojects/apache-felix-event-admin.html)|An implementation of the OSGi Event Admin service specification for event-based communication.|[source](https://github.com/apache/felix-dev/tree/master/eventadmin)|
-|[File Install](subprojects/apache-felix-file-install.html)|A simple, directory-based management agent for managing bundle deployment.|[source](https://github.com/apache/felix-dev/tree/master/fileinstall)|
-|[Framework](subprojects/apache-felix-framework.html)|An implementation of the OSGi R7 core framework.|[source](https://github.com/apache/felix-dev/tree/master/framework)|
-|[Framework Security](subprojects/apache-felix-framework-security.html)||[source](https://github.com/apache/felix-dev/tree/master/framework.security)|
-|[Gogo](subprojects/apache-felix-gogo.html)|An advanced shell for interacting with OSGi frameworks.|[source](https://github.com/apache/felix-dev/tree/master/gogo)|
-|[Health Checks](subprojects/apache-felix-healthchecks.html)|An extensible framework to monitor the status of the OSGi container at runtime.|[source](https://github.com/apache/felix-dev/tree/master/healthcheck)|
-|[HTTP Service](https://github.com/apache/felix-dev/tree/master/http)|An implementation of the [OSGi HTTP Whiteboard](https://osgi.org/specification/osgi.cmpn/7.0.0/service.http.whiteboard.html) and [Http Service specification](https://osgi.org/specification/osgi.cmpn/7.0.0/service.http.html).|[source](https://github.com/apache/felix-dev/tree/master/http)|
-|[Inventory Printer](subprojects/apache-felix-inventory.html)|A simple and extensible framework to retrieve inventory information about applications running in an OSGi Framework.|[source](https://github.com/apache/felix-dev/tree/master/inventory)|
-|[iPOJO](subprojects/apache-felix-ipojo.html)|A sophisticated service-oriented component model to simplify OSGi-based development.|[source](https://github.com/apache/felix-dev/tree/master/ipojo)|
-|[Log](subprojects/apache-felix-log.html)|A simple, memory-based implementation of the OSGi Log service specification.|[source](https://github.com/apache/felix-dev/tree/master/log)|
-|[Logback](subprojects/apache-felix-logback.html)|Apache Felix Logback is a small integration of the [Logback](https://logback.qos.ch/) backend with OSGi.|[source](https://github.com/apache/felix-dev/tree/master/logback)|
-|[Maven Bundle Plugin](subprojects/apache-felix-maven-bundle-plugin-bnd.html)|A Maven plugin to simplify building bundles.|[source](https://github.com/apache/felix-dev/tree/master/tools/maven-bundle-plugin)|
-|[Metatype](subprojects/apache-felix-metatype-service.html)|An implementation of the OSGi Metatype service to describe types needed by bundles.|[source](https://github.com/apache/felix-dev/tree/master/shell)|
-|[OSGi Bundle Repository](subprojects/apache-felix-osgi-bundle-repository.html)|A bundle repository service to simplify discovering and deploying bundles and their dependencies.|[source](https://github.com/apache/felix-dev/tree/master/org.osgi.service.obr)|
-|[Preferences Service](subprojects/apache-felix-preferences-service.html)|An implementation of the OSGi Preferences service specification for storing settings and preferences.|[source](https://github.com/apache/felix-dev/tree/master/preferences)|
-|[Remote Shell](subprojects/apache-felix-remote-shell.html)|A remote, text-based interface to the Apache Felix Shell.|[source](https://github.com/apache/felix-dev/tree/master/shell.remote)|
-|[Service Component Runtime](https://github.com/apache/felix-dev/tree/master/scr)|An implementation of the [OSGi Declarative Services specification](https://osgi.org/specification/osgi.cmpn/7.0.0/service.component.html) providing a service-oriented component model to simplify OSGi-based development.|[source](https://github.com/apache/felix-dev/tree/master/scr)|
-|[Shell](subprojects/apache-felix-shell.html)|A very simple shell service implemented as a bundle for interacting with an OSGi framework instance.|[source](https://github.com/apache/felix-dev/tree/master/shell)|
-|[Shell TUI](subprojects/apache-felix-shell-tui.html)|A simple, text-based interface to the Apache Felix Shell.|[source](https://github.com/apache/felix-dev/tree/master/shell.tui)|
-|[Web Console](subprojects/apache-felix-web-console.html)|A simple tool to inspect and manage OSGi framework instances using your favorite Web Browser.|[source](https://github.com/apache/felix-dev/tree/master/webconsole)|
-
-## Maintenance
-
-The following projects are in maintenance mode meaning there is no active development anymore.
-
-* [Auto Configuration](subprojects/apache-felix-autoconf.html)
-* [Commons](subprojects/apache-felix-commons.html)
-* [Deployment Admin](subprojects/apache-felix-deployment-admin.html)
-* [JAAS Support](subprojects/apache-felix-jaas.html)
-* [Lightweight HTTP Service](subprojects/apache-felix-lightweight-http-service.html)
-* [Manifest Generator (mangen)](subprojects/apache-felix-manifest-generator-mangen.html)
-* [Maven OBR Plugin](subprojects/apache-felix-maven-obr-plugin.html)
-* [Maven OSGi Plugin](subprojects/apache-felix-maven-osgi-plugin.html)
-* [Maven SCR Plugin](subprojects/apache-felix-maven-scr-plugin.html)
-* [MOSGi Managed OSGi framework](subprojects/mosgi-managed-osgi-framework.html)
-* [OSGi Core](subprojects/apache-felix-osgi-core.html)
-* [Script Console Plugin](subprojects/apache-felix-script-console-plugin.html)
-* [Serialization Framework](subprojects/apache-felix-serialization-framework.html)
-* [UPnP](subprojects/apache-felix-upnp.html)
-* [User Admin](subprojects/apache-felix-user-admin.html)
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-autoconf.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-autoconf.mdtext
deleted file mode 100644
index 869f6f8..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-autoconf.mdtext
+++ /dev/null
@@ -1,4 +0,0 @@
-Title: Apache Felix Auto Configuration
-
-This project implements the OSGi Auto Configuration specification; please consult the OSGi Compendium Specification chapter 115 for more information.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-commons.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-commons.mdtext
deleted file mode 100644
index c5d220a..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-commons.mdtext
+++ /dev/null
@@ -1,68 +0,0 @@
-Title: Apache Felix Commons
-
-### Purpose
-
-Apache Felix Commons is a community effort to create OSGi bundle ("bundlized") versions of popular third-party open-source libraries. Today, OSGi developers must create bundles out of third-party libraries within their own development communities. The purpose of Felix Commons is to avoid duplicating the effort of bundle creation by sharing these bundlized artifacts. Our hope is that over time, the original developers of the third-party libraries can use these bundlized libraries to le [...]
-
-This web page will be used to document who is doing what and to provide pointers to more information.
-
-### How Can I Help?
-
-If you have libraries you have turned into bundles, then you can offer to contribute them. Additionally, you may request that a certain bundle be created. If you wish to submit a POM file for a specific library, you can attach it to a [Felix JIRA issue](http://issues.apache.org/jira/browse/Felix) under the "Felix Commons" component. For Apache purposes, contributing a bundle POM is the same as contributing code.
-
-### Getting Started
-
-In most cases, creating bundlized versions of a library is as simple as creating a POM file for the library using Felix' new [Maven Bundle Plugin]({{ refs.apache-felix-maven-bundle-plugin-bnd.path }}). The OSGi headers are non-intrusive. A JAR can be made in such a way that it runs on the Classpath as well as a bundle in an OSGi framework. In short you:
-1. Set the groupId to:
-
- <groupId>org.apache.felix.commons</groupId>
-
-1. Append "-osgi" to the name of the artifact:
-
- <artifactId>FOO-osgi</artifactId>
-
-1. Set the "packaging" to use the Maven Bundle Plugin:
-
- <packaging>bundle</packaging>
-
-1. Set any configuration options in the [Maven Bundle Plugin]({{ refs.apache-felix-maven-bundle-plugin-bnd.path }}).
-
-We recommend you read the longer [steps for converting a library to a bundle]({{ refs.creating-bundles-using-bnd.path }}).
-
-### Contributions
-
-| Library | Version | Description | Contributor | Grant OK | Committed |
-|--|--|--|--|--|--|
-| cglib | 2.0.2 | CGLib | Felix Meschberger | Yes | Yes |
-| commons-beanutils | 1.7.0 | BeanUtils | Felix Meschberger | Yes | Yes |
-| commons-codec | 1.2 | Codec | Felix Meschberger | Yes | Yes |
-| commons-configuration | 1.3 | Configuration | Felix Meschberger | Yes | Yes |
-| commons-digester | 1.8 | Digester | Felix Meschberger | Yes | Yes |
-| commons-el | 1.0 | EL | Felix Meschberger | Yes | Yes |
-| commons-fileupload | 1.1.1 | FileUpload | Felix Meschberger | Yes | Yes |
-| commons-httpclient | 3.0.1 | Client-side HTTP. | Felix Meschberger | Yes | Yes |
-| commons-io | 1.3 | IO | Felix Meschberger | Yes | Yes |
-| commons-lang | 2.2 | Lang | Felix Meschberger | Yes | Yes |
-| antlr | 2.7.6 | Parser generator. | John Conlon | Yes | Yes |
-| commons-collections | 3.2 | Data structures for collections. | John Conlon | Yes | Yes |
-| jzlib | 1.0.7 | Data compression library. | John Conlon | Yes | Yes |
-| commons-email | 1.0 | An API for sending email. | Felix Meschberger | Yes | Yes |
-
-### Supporting Libraries
-
-These are projects that have expressed support for the Felix Commons initiative and that are working directly within their respective projects to support OSGi.
-
-| Project | Description | Supporter(s) | More Information |
-|--|--|--|--|
-| Spring | | Adrian Colyer, Andy Piper | [Spring-OSGi](http://www.springframework.org/osgi) |
-| SLF4J | | Ceki Gülcü | [SLF4J](http://www.slf4j.org/) |
-| Logback | | Ceki Gülcü | [Logback](http://logback.qos.ch/) |
-| MINA | NIO framework | Trustin Lee | [DIRMINA-27](http://issues.apache.org/jira/browse/DIRMINA-27) |
-| HTTP Client | Client-side HTTP. | Roland Weber | [HTTPCLIENT-639](https://issues.apache.org/jira/browse/HTTPCLIENT-639) |
-| Apache OFBiz | Enterprise automation. | Christopher Snow | [Mailing list archives](http://mail-archives.apache.org/mod_mbox/incubator-felix-dev/200704.mbox/%3c8A31258D-1FB4-4F42-A145-94136D750EF0@coralms.com%3e) |
-| Jetty | Servlet engine. | Jan Bartel | Jetty 6.1.5 and onwards uses the 'maven-bundle-plugin'.|
-### Similar Efforts
-Eclipse Orbit - http://www.eclipse.org/orbit/
-{quote}
-... will provide a repository of bundled versions of third party libraries that are approved for use in one or more Eclipse projects.
-{quote}
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-commons/creating-bundles-using-bnd.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-commons/creating-bundles-using-bnd.mdtext
deleted file mode 100644
index 921f580..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-commons/creating-bundles-using-bnd.mdtext
+++ /dev/null
@@ -1,84 +0,0 @@
-Title: Creating Bundles Using BND
-
-##### Purpose
-
-Provide the list of steps required to create a library bundle by wrapping the library jar using bnd (http://bnd.bndtools.org/).
-
-##### Steps
-
-1. Use bnd to analyze the library jar (e.g., java -jar bnd-0.0.jar print path/to/FOO.jar)
-1. At the bottom of the bnd output, look for "Unresolved references to ..." which identify package dependencies. If found,
- a. Identifiy the library jars that provide the missing packages
- b. Recursively use this process on each dependency
-1. Create a directory that will be the project directory for the bundle (e.g., mkdir FOO-osgi)
-1. Copy the template pom.xml file to the bundle's project directory
-1. Edit the pom.xml file to tailor it for the library jar. Specifically,
- a. change artifactId
- b. verify description
- c. change version
- d. change FOO's library jar dependency (groupId, artifactId)
- e. add any other dependencies (from step 2b)
- f. change Export-Package
- g. change Private-Package or delete it if it's not needed
- h. All packages listed in step 1 should be in either Export-Package or Private-Package. Use the library's javadoc to identify the exported packages. The remaining packages should be private.
-1. Run "mvn package" to in the project directory to create the bundle
-1. Use bnd to verify the bundle's contents (e.g., java -jar bnd-0.0.jar print target/FOO-osgi-VERSION.jar)
-1. Run "mvn install" to install the bundle in the local repository
-
-##### Example POM
-
- <project
- xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.apache.felix.commons</groupId>
- <artifactId>FOO-osgi</artifactId>
- <name>${pom.artifactId} bundle</name>
- <description>
- This bundle simply wraps FOO-${pom.version}.jar.
- </description>
- <version>X.Y</version>
- <packaging>bundle</packaging>
-
- <organization>
- <name>Apache Felix Project</name>
- <url>http://felix.apache.org/</url>
- </organization>
-
- <dependencies>
- <dependency>
- <groupId>FOO</groupId>
- <artifactId>FOO</artifactId>
- <version>${pom.version}</version>
- </dependency>
- </dependencies>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
- <Export-Package>FOO</Export-Package>
- <Private-Package>FOO.impl</Private-Package>
- </instructions>
- </configuration>
- </plugin>
- </plugins>
- </build>
-
- </project>
-
-
-##### Resources
-
-Bnd - Bundle Tool
-http://bnd.bndtools.org/
-
-Bundle Plugin for Maven
-http://felix.apache.org/site/maven-bundle-plugin-bnd.html
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager.mdtext
deleted file mode 100644
index 0c95e19..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager.mdtext
+++ /dev/null
@@ -1,62 +0,0 @@
-Title: Apache Felix Dependency Manager
-
-Welcome to the Dependency Manager, a great bundle for managing your components and dependencies!
-
-## Introduction
-
-In a service oriented architecture, applications are built out of components that are packaged in bundles and interact through services. These components, that both publish services and depend on other services, form networks that are often dynamic in nature. That makes managing these dependencies something the developer needs to address.
-
-Whilst the OSGi framework provides the low-level building blocks to do that in the form of service listeners and trackers, these should not be used directly by developers. Instead, a more declarative approach works best, and the Dependency Manager provides this in the form of a declarative API and/or annotations that allow you to dynamically declare and change dependencies.
-
-On top of that, a set of OSGi design patterns are defined and supported that can be used as building blocks for more complex applications.
-
-The documentation for the dependency manager is split into three sections:
-
-1. Step-by-step tutorials which provide a good introduction to the technology and should get you started quickly.
-2. Overviews and guides that provide more in-depth knowledge about specific aspects of the dependency manager.
-3. Reference materials that describe all the individual nuts and bolts.
-
-Below is the full table of contents.
-
-## Table of Contents
-
-### Step-by-step Tutorials
-
-* [Getting started](apache-felix-dependency-manager/tutorials/getting-started.html)
-* [Leveraging the shell](apache-felix-dependency-manager/tutorials/leveraging-the-shell.html)
-* [Hello World example projects](apache-felix-dependency-manager/tutorials/sample-code.html)
-
-### Overviews and Guides
-
-* [History](apache-felix-dependency-manager/guides/history.html)
-* [Background](apache-felix-dependency-manager/guides/background.html)
-* [What's new in DM 4](apache-felix-dependency-manager/guides/whatsnew.html)
-* [What's new in release r15](apache-felix-dependency-manager/guides/whatsnew-r15.html)
-* [Bundles and dependencies](apache-felix-dependency-manager/guides/bundles-and-dependencies.html)
-* [Migrating from earlier versions](apache-felix-dependency-manager/guides/migrating-from-earlier-versions.html)
-* [Performance Tuning](apache-felix-dependency-manager/guides/performance-tuning.html)
-* [Development](apache-felix-dependency-manager/guides/development.html)
-* [Design Patterns](apache-felix-dependency-manager/guides/design-patterns.html)
-* [Resource Adapters](apache-felix-dependency-manager/guides/resources.html)
-* [Javadocs](apache-felix-dependency-manager/guides/javadocs.html)
-
-### Reference Guide
-
-* [Components](apache-felix-dependency-manager/reference/components.html)
- * [Singleton](apache-felix-dependency-manager/reference/component-singleton.html)
- * [Aspect](apache-felix-dependency-manager/reference/component-aspect.html)
- * [Adapter](apache-felix-dependency-manager/reference/component-adapter.html)
- * [Resource Adapter](apache-felix-dependency-manager/reference/component-resource-adapter.html)
- * [Bundle Adapter](apache-felix-dependency-manager/reference/component-bundle-adapter.html)
- * [Factory Configuration Adapter](apache-felix-dependency-manager/reference/component-factory-configuration-adapter.html)
-* [Dependencies](apache-felix-dependency-manager/reference/dependencies.html)
- * [Service](apache-felix-dependency-manager/reference/dependency-service.html)
- * [Configuration](apache-felix-dependency-manager/reference/dependency-configuration.html)
- * [Bundle](apache-felix-dependency-manager/reference/dependency-bundle.html)
- * [Resource](apache-felix-dependency-manager/reference/dependency-resource.html)
-* [Service Scopes](apache-felix-dependency-manager/reference/service-scopes.html)
-* [Dependency Manager Annotations](apache-felix-dependency-manager/reference/dm-annotations.html)
-* [Dependency Manager Lambda](apache-felix-dependency-manager/guides/dm-lambda.html)
-* [Thread Model](apache-felix-dependency-manager/reference/thread-model.html)
-* [External Links and Articles](apache-felix-dependency-manager/reference/external-links.html)
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext
deleted file mode 100644
index cccc5b1..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext
+++ /dev/null
@@ -1,347 +0,0 @@
-Title: Dependency Manager - Annotations
-
-This section presents a quick overview of the capabilities and usage of the DependencyManager Java annotations. In particular, we will recap the DependencyManager annotation architecture, and identify some simple usage scenarios using a SpellChecker
-sample application with annotated components. The application is available from the felix trunk, in the `dependencymanager/samples.annotation` subproject.
-
-## Architecture
-
-Instead of writing Activators which extends the DependencyActivatorBase class, service
-components can now be annotated using the annotations provided by the
-*org.apache.felix.dependencymanager.annotation* bundle. Annotations are not reflectively
-parsed at runtime; but we use a BND plugin which scans annotations at compilation phase
-and generates a compact metadata file in the bundle's META-INF/dependencymanager
-subdirectory. This has the following benefits:
-
-- JVM startup speed is not affected, and class files are not parsed when the framework is starting
-- Moreover, since the annotations are not retained by the VM at runtime, it is not necessary to load the annotation API bundle at runtime.
-
-At runtime, the metadata generated during the compilation phase are processed by a
-specific DependencyManager Runtime bundle, which is in charge of managing the service
-component lifecycle and dependencies. This Runtime bundle actually uses the
-DependencyManager programmatic API in order to manage the annotated components.
-Annotated components can then be inspected with the DependencyManager Gogo shell, as it is
-the case with DM components declared through the programmatic DM API.
-
-## Registering a Service
-
-To register a service, your can annotate your class with a *@Component* annotation, and
-an instance of your class will be registered under all directly implemented interfaces
-into the OSGi registry. You can however take control on the interfaces to be exposed, and
-in this case, you can use the *provides* attribute, which takes a list of classes to
-expose from the registry.
-
-To illustrate this, we are now introducing a SpellChecker application which provides a
-Felix "spellcheck" Gogo shell command. Gogo is the new shell supported by the Felix
-Framework. Our "spellcheck" command is implemented by the SpellChecker component which
-accepts a string as parameter. This string is then checked for proper existence. To do
-the checking, The SpellChecker class has a required/multiple (1..N) dependency over
-every available DictionaryService services. Such DictionaryService represents a real
-dictionary for a given language (it has a *lang* service property), and is
-configurable/instantiable from the OSGi Configuration Admin Service.
-
-Configuration Admin service provides a mechanism for configuring components
-(using ManagedService interfaces), and WebConsole actually implements this service.
-ConfigAdmin is also able to instantiate some Services (using ManagedServiceFactory
-interfaces).
-
-Now we have introduced the background, here is the SpellCheck component:
-
- :::java
- @Component(provides={SpellChecker.class},
- properties={@Property(name=CommandProcessor.COMMAND_SCOPE, value="dmsample.annotation"),
- @Property(name=CommandProcessor.COMMAND_FUNCTION, values={"spellcheck"})})
- public class SpellChecker {
- // --- Gogo Shell command
-
- @Descriptor("checks if word is found from an available dictionary")
- public void spellcheck(@Descriptor("the word to check")String word) {
- // Check the proper existence of the word parameter, using injected DictionaryService instances
- // ...
- }
- }
-
-
-In the code above, you see that the SpellCheck is annotated with the *@Component*
-annotation. Gogo runtime does not required shell commands to implement a specific
-interface. Commands just have to register some Pojos in the OSGi registry, but the only
-thing required is to provide the Pojos with two service properties ( COMMAND_SCOPE, and
-COMMAND_FUNCTION) which will be used by the Gogo runtime when instropecting the Pojo
-for invoking the proper functions.
-
-
-So, coming back to the sample code, the SpellChecker class registers itself into the OSGi registry, using the *provides* attribute, which just refer to our SpellChecker class, and the two mandatory Gogo service properties are also specified using the *@Property* annotation. It is not shown here, but service properties can also be provided dynamically from a method that can return a Map, and annotated with the *@Start* lifecycle callback, but we will see this feature in a another section.
-
-## Depending on a Service
-
-Our SpellChecker component can expose itself as a Gogo shell command, but before being
-registered into the OSGi registry, we also need to be injected with two dependencies:
-one required dependency (at minimum) on a DictionaryService, and another optional one on
-a LogService. First, let's look at the DictionaryService, which is a simple interface:
-
- :::java
- public interface DictionaryService {
- /**
- * Check for the existence of a word.
- * @param word the word to be checked.
- * @return true if the word is in the dictionary, false otherwise.
- */
- public boolean checkWord(String word);
- }
-
-And here is our previous SpellChecker component, augmented with two new ServiceDependency
-annotations:
-
- :::java
- @Component(provides={SpellChecker.class},
- properties={@Property(name=CommandProcessor.COMMAND_SCOPE, value="dmsample.annotation"),
- @Property(name=CommandProcessor.COMMAND_FUNCTION, values={"spellcheck"})})
- public class SpellChecker {
- @ServiceDependency(required = false)
- private LogService m_log;
-
- private CopyOnWriteArrayList<DictionaryService> m_dictionaries = new CopyOnWriteArrayList<DictionaryService>();
-
- @ServiceDependency(removed = "removeDictionary")
- protected void addDictionary(DictionaryService dictionary) {
- m_dictionaries.add(dictionary);
- }
-
- protected void removeDictionary(DictionaryService dictionary) {
- m_dictionaries.remove(dictionary);
- }
-
- // --- Gogo Shell command
-
- @Descriptor("checks if word is found from an available dictionary")
- public void spellcheck(@Descriptor("the word to check")String word) {
- m_log.log(LogService.LOG_INFO, "Checking spelling of word \"" + word
- + "\" using the following dictionaries: " + m_dictionaries);
-
- for (DictionaryService dictionary : m_dictionaries) {
- if (dictionary.checkWord(word)) {
- System.out.println("word " + word + " is correct");
- return;
- }
- }
- System.err.println("word " + word + " is incorrect");
- }
- }
-
-There are many things to describe in the code above:
-
-First, we define an optional dependency on the LogService, by defining a
-*@ServiceDependency(required=false)* annotation on our m_logService field: This
-means that our component will be provided into the OSGi registry even if there
-is no available LogService, and in this case, a NullObject will be injected in
-our class field;
-This will avoid to check for nullability, when using the m_logService field.
-All optional dependencies applied on class fields are injected with a
-NullObject (when not available).
-The NullObject can be invoked and will do nothing. For a lot of cases that is
-good enough to handle optional dependencies. But when you really want to check
-if an optional service is there or not, then you have to apply the optional
-dependency on a callback method, which will be called when the optional
-service is available.
-
-Next comes the dependency on the DictionaryService. Here, we use a *ServiceDependency*
-annotation, but this time we apply it on a method (*add/removeDictionary*). There is no
-need to specify the "*required=true*" flag because it is the default value. Notice that
-this behavior is different from the API, where service dependencies are optional by default
-. We use a callback method, because we just need to register all available
-DictionaryService services in our dictionary list, which is used when checking word
-existence. This list is a copy on write list because the dependency may be injected at
-any time, possibly from another thread. So, using a copy on write list avoid us to use synchronized methods.
-
-## Creating a Service from ConfigAdmin
-
-The *@Component* annotation is not the only one for creating services. Another one is
-the *@FactoryConfigurationAdapterService* annotation which allows to instantiate many
-instances of the same annotated service class from ConfigAdmin (and WebConsole).
-To illustrate this, let's take a look at our DictionaryImpl class which is part of the
-SpellChecker sample. This service is required by the SpellChecker component, when
-checking for proper word existence. And you can instantiate as many DictionaryService as
-you want, from ConfigAdmin ...
-
- :::java
- @FactoryConfigurationAdapterService(factoryPid="DictionaryImplFactoryPid", updated="updated")
- public class DictionaryImpl implements DictionaryService {
- /**
- * We store all configured words in a thread-safe data structure, because ConfigAdmin
- * may invoke our updated method at any time.
- */
- private final CopyOnWriteArrayList<String> m_words = new CopyOnWriteArrayList<String>();
-
- /**
- * Our Dictionary language.
- */
- private String m_lang;
-
- /**
- * Our service will be initialized from ConfigAdmin, and we also handle updates in this method.
- * @param config The configuration where we'll lookup our words list (key="words").
- */
- protected void updated(Dictionary<String, ?> config) {
- m_lang = (String) config.get("lang");
- m_words.clear();
- String[] words = (String[]) config.get("words");
- for (String word : words) {
- m_words.add(word);
- }
- }
-
- /**
- * Check if a word exists if the list of words we have been configured from ConfigAdmin/WebConsole.
- */
- public boolean checkWord(String word) {
- return m_words.contains(word);
- }
- }
-
-Our DictionaryImpl class implements a DictionaryService, and our class will be registered
-under that interface (all directly implemented interfaces are used when registering the
-service, but you can select some others using the *provides* attribute).
-The *@FactoryConfigurationAdapterService* annotation will instantiate our service for
-each configuration created from web console (and matching our "DictionaryImplFactoryPid"
-factoryPid).
-
-We also use the *updated* attribute, which specifies a callback method which will handle
-properties configured by ConfigAdmin. The updated callback will also be called when our
-properties are changing. Every properties are propagated to our service properties,
-unless the properties starting with a dot ("."). Configuration properties starting with
-a dot (".") are considered private and are not propagated.
-
-Notice that you can mix standard bnd metatype annotations with DM annotations, in order
-describe configurations meta data (default values, property labels, etc ... see http://bnd.bndtools.org/chapters/210-metatype.html).
-So, let's revisit our DisctionaryImpl service, but this time with meta type support:
-
-First, we define an interface for describing our configuration metadata, with bnd metatype annotations:
-
- :::java
- import java.util.List;
-
- import aQute.bnd.annotation.metatype.Meta.AD;
- import aQute.bnd.annotation.metatype.Meta.OCD;
-
- @OCD(name="Spell Checker Dictionary (annotation)", factory = true, description = "Declare here some Dictionary instances")
- public interface DictionaryConfiguration {
- @AD(description = "Describes the dictionary language", deflt = "en")
- String lang();
-
- @AD(description = "Declare here the list of words supported by this dictionary. This properties starts with a Dot and won't be propagated with Dictionary OSGi service properties")
- List<String> words();
- }
-
-Next, here is our DictionaryImpl that will use the bnd "Configurable" helper in order to retrieve the actual configuration:
-
- :::java
- import org.apache.felix.dm.annotation.api.FactoryConfigurationAdapterService;
- import org.apache.felix.dm.annotation.api.ServiceDependency;
- import org.apache.felix.dm.annotation.api.Start;
- import org.osgi.service.log.LogService;
- import aQute.bnd.annotation.metatype.Configurable;
-
- @FactoryConfigurationAdapterService(factoryPidClass = DictionaryConfiguration.class, propagate = true, updated = "updated")
- public class DictionaryImpl implements DictionaryService {
- private final CopyOnWriteArrayList<String> m_words = new CopyOnWriteArrayList<String>();
- private String m_lang;
-
- protected void updated(Dictionary<String, ?> config) {
- if (config != null) {
- // use bnd "Configurable" helper to get an implementation for our DictionaryConfiguration.
- DictionaryConfiguration cnf =
- Configurable.createConfigurable(DictionaryConfiguration.class, config);
-
- m_lang = cnf.lang();
- m_words.clear();
- for (String word : cnf.words()) {
- m_words.add(word);
- }
- }
- }
-
- public boolean checkWord(String word) {
- return m_words.contains(word);
- }
- }
-
-
-## Providing an Aspect
-
-As we have seen in the previous section, there are many annotations that can be used
-to specify a service. Another one is the *@AspectService* annotation. This annotation
-allows to *decorate* an existing service in order to add certain "capabilities" to it,
-like adding a specific caching mechanism to a storage service or implementing logging.
-Aspects can be plugged to an existing service at runtime, and can also be removed
-dynamically. This is transparent, and the clients using the existing service are not
-interrupted, they are just rebound with the aspect service.
-
-As an example, we go back to our SpellChecker application, and we are now looking at the
-DictionaryAspect class. This class uses the *@Aspect* Service annotation in
-order to add some custom words to an English DictionaryService (with the
-service property lang=en).
-The Extra words to add to the English Dictionary will be configured from
-ConfigAdmin. That's why the class also uses a *@ConfigurationDependency* annotation:
-
- :::java
- @AspectService(ranking = 10, filter = "(lang=en)")
- public class DictionaryAspect implements DictionaryService {
- /**
- * This is the service this aspect is applying to.
- */
- private volatile DictionaryService m_originalDictionary;
-
- /**
- * We store all configured words in a thread-safe data structure, because ConfigAdmin may
- * invoke our updated method at any time.
- */
- private CopyOnWriteArrayList<String> m_words = new CopyOnWriteArrayList<String>();
-
- /**
- * Defines a configuration dependency for retrieving our english custom words (by default,
- * our PID is our full class name).
- */
- @ConfigurationDependency
- protected void updated(Dictionary<String, ?> config) {
- m_words.clear();
- String[] words = (String[]) config.get("words");
- for (String word : words) {
- m_words.add(word);
- }
- }
-
- /**
- * Checks if a word is found from our custom word list. if not, delegate to the decorated
- * dictionary.
- */
- public boolean checkWord(String word) {
- if (m_words.contains(word)) {
- return true;
- }
- return m_originalDictionary.checkWord(word);
- }
- }
-
-The annotation does the following: because our class implements the DictionaryService
-contract, it will instantiate our service each time it finds another existing
-DictionaryService matching the filter attribute we provide in the annotation
-(filter="(lang=en)"). And it will inject the existing service in our
-m_originalDictionary field, by reflection. But we can also specify a field attribute in
-the annotation, if we want to explicitly inject the existing service in a given class
-field. So, any client depending on an English DictionaryService will be transparently
-rebound to our aspect Dictionary.
-
-In the Annotation, also notice the *ranking* attribute: It is the level used to organize
-the aspect chain ordering (multiple aspects may be applied on a given service).
-
-
-The *ConfigurationDependency* is another dependency that we have not seen before: it is
-used to configure the extra English words from ConfigAdmin. This annotation normally
-requires a pid parameter, which is a persistent identifier uniquely identifying our
-component, but by default, the pid is set to the fully qualified name of our class.
-
-## How to run the sample code
-
-Just import the Dependency source distribution in bndtools and check the following samples:
-
-* org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/annot/README
-* org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/api/README
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext
deleted file mode 100644
index e9b9eb9..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext
+++ /dev/null
@@ -1,28 +0,0 @@
-Title: Dependency Manager - Background
-
-## Background
-
-In an OSGi framework, services are deployed using bundles and these bundles feature two types of dependencies:
-
-1. Package dependencies. A bundle can export a package which others import. These dependencies, although dynamic, are relatively easy to handle and the whole resolution process is handled by the OSGi framework for you.
-1. Service dependencies. Services, implemented by components inside of bundles, can have their own life cycle within that of their containing bundle and therefore can be registered and unregistered at any time. Other components often depend on these services and need to deal with changes in their availability.
-
-When you look at dependency management, there are two aspects you need to take into account:
-
-The first is managing software configurations. This means you need to manage the dependencies from a configuration standpoint. What you are managing are bundles, since those are the units of deployment. What you need to manage are the package and service dependencies between bundles. Package dependencies are always visible by examining the bundle manifest and when a bundle is installed the framework will try to resolve such dependencies before that bundle can even be started. Service dep [...]
-
-The second is managing service dependencies at runtime. As mentioned before, a service oriented architecture is dynamic by design, so your implementation should be able to deal with this. Bundles can start in any order and any service can go away or be replaced by a different implementation at any point in time. OSGi itself offers basic assistance for tracking services. You can track them yourself by registering as a service listener. A slightly more advanced way is to create a service t [...]
-
-In real implementations, you are probably going to track multiple services. Using service trackers in such a scenario has the tendency to result in dependency logic that is entangled in the implementation instead of being expressed in a declarative way. Using a declarative way to specify dependencies has clear advantages when it comes to monitoring and managing them, a task that becomes more and more important in modern, federated, service oriented environments.
-
-The Dependency Manager provides you with the right building blocks to declaratively specify dependencies using a straightforward Java API that is easy to maintain and refactor.
-
-## Design Goals
-
-The goals that drove the design of the dependency manager are:
-
-* Provide a clean separation between a component implementation and the "glue" that binds it to the OSGi framework. The component implementation should not have to contain any OSGi specific code. In other words, it should be a POJO (Plain Old Java Object).
-* Minimize the amount of code that needs to be written. The specification and management of dependencies should be automated as much as possible, whilst still providing enough flexibility to customize the system.
-* Be extensible. Even though the core bundle provides a lot of different dependencies already, you should be able to add your own types of dependencies easily.
-* Easy to monitor and debug. Being a dynamic system, it's important to be able to see what the state of all components and dependencies are at any point in time.
-* Supporting powerful high level design patterns. When building real-world applications, more complex patterns need to be used, such as aspects and adapters. Support for these needs to be built into the core.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.mdtext
deleted file mode 100644
index 6a05899..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.mdtext
+++ /dev/null
@@ -1,23 +0,0 @@
-Title: Dependency Manager - Bundles and Dependencies
-
-The dependency manager project consists of the following bundles. For each bundle, we also list its dependencies in the form of package imports, plus a suggestion on a bundle that resolves them.
-
-* `org.apache.felix.dependencymanager` - 4.0.0 - This is the core bundle, containing the code for working with the Java based API.
- * org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework itself
- * org.osgi.util.tracker;version="[1.4,2)" - provided by the OSGi framework itself
- * org.osgi.service.cm;version="[1.3,2)" - provided by Apache Felix Configuration Admin, or the OSGi Compendium bundle
- * org.osgi.service.metatype;version="[1.1,2)" - provided by Apache Felix Metatype, or the OSGi Compendium bundle
-
-* `org.apache.felix.dependencymanager.runtime` - 4.0.0 - This is the runtime bundle that you need, together with the core bundle above, if you want to work with annotations.
- * org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework itself
- * org.osgi.service.packageadmin;version="[1.2,2)" - provided by the OSGi framework itself
- * org.apache.felix.dm;version="[4,5)" - provided by the core bundle
- * org.apache.felix.dm.context;version="[4,5)" - provided by the core bundle
- * org.osgi.service.log;version="[1.3,2)" - provided by Apache Felix Log Service, or the OSGi Compendium bundle
-
-* `org.apache.felix.dependencymanager.shell` - 4.0.0 - This is the shell bundle. It only contains the shell commands, so you need it if you want to use those.
- * org.apache.felix.dm;version="[4.0,5)" - provided by the core bundle
- * org.apache.felix.service.command;version="[0.10,1)";status=provisional
- * org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework itself
-* `org.apache.felix.dependencymanager.annotation` - 4.0.0 - This is not a bundle, but code you need when compiling your bundles that contain annotations. Notice that the annotation jar contains OSGi headers in its manifest, but this bundle is not meant to be included in the OSGi framework runtime
-(the OSGi headers are only present in order to allow you to drag and drop the dependency manager annotation bundle in your buildpath project).
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext
deleted file mode 100644
index 361434f..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext
+++ /dev/null
@@ -1,161 +0,0 @@
-Title: Dependency Manager - Design Patterns
-
-This section lists a couple of design patterns as they can be applied in an OSGi context.
-
-## Singleton Service
-
-Provides a service as long as its dependencies are resolved.
-
-### Motivation
-
-In a dynamic framework, services can come and go. Components that publish a service are often themselves dependent on other services to perform their task. In such cases, they have a dependency on those services and it makes sense to only publish their own services when these dependencies are available. Being able to declare such dependencies in code ensures consistent life cycle behavior.
-
-### Structure
-
-<img src="./diagrams/singleton.png" alt="Singleton" style="width: 190px"/>
-
-### Code Example
-
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createComponent()
- .setInterface(UserStore.class, new Properties() {{ put("store.id", "users"); }})
- .setImplementation(UserStoreImpl.class)
- .add(createServiceDependency()
- .setService(Store.class)
- .setRequired(true)
- )
- .add(createServiceDependency()
- .setService(LogService.class)
- .setRequired(false)
- )
- );
- }
-
- public void destroy(BundleContext context, DependencyManager manager) throws Exception {}
- }
-
-
-## Aspect Service
-
-Provides an aspect on top of a specific type of service.
-
-### Motivation
-
-In aspect oriented programming, supporting functions are isolated from the main application's business logic. This increases modularity at the source level by allowing the separation of cross-cutting concerns. In OSGi we want to extend this modularity to the runtime, therefore we implement aspects to work on certain services, where the aspect itself publishes that same service but (usually) with a higher priority. This allows you to dynamically add and remove aspects.
-
-### Structure
-
-<img src="./diagrams/aspect.png" alt="Aspect" style="width: 190px"/>
-
-### Code Example
-
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createAspectService(Manageable.class, "(monitor=true)", 50)
- .setImplementation(ManageableMonitor.class)
- );
- }
-
- public void destroy(BundleContext context, DependencyManager manager) throws Exception {}
- }
-
- public interface Manageable {
- public void setProperty(String key, String value);
- }
-
- public class ManageableMonitor implements Manageable {
- private volatile Manageable m_manageable;
-
- public void setProperty(String key, String value) {
- System.out.println("Someone set " + key + " to " + value);
- m_manageable.setProperty(key, value);
- }
- }
-
-
-## Adapter Service
-
-Provides an adapter for a specific type of service.
-
-### Motivation
-
-Like with aspects, sometimes you want to create adapters for certain services, which add certain behavior that results in the publication of (in this case) a different service. Adapters can dynamically be added and removed and allow you to keep your basic services implementations clean and simple, adding extra features on top of them in a modular way.
-
-### Structure
-
-<img src="./diagrams/adapter.png" alt="Adapter" style="width: 190px"/>
-
-### Code Example
-
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createAdapterService(Manageable.class, "(publish=servlet)")
- .setInterface(HttpServlet.class.getName(), null)
- .setImplementation(ManageableServlet.class)
- );
- }
-
- public void destroy(BundleContext context, DependencyManager manager) throws Exception {}
- }
-
- public interface Manageable {
- public void setProperty(String key, String value);
- }
-
- public class ManageableServlet implements HttpServlet {
- private volatile Manageable m_manageable;
-
- public void doPost(HttpRequest req, HttpResponse response) {
- String key = req.getProperty("key");
- String value = req.getProperty("value");
- m_manageable.setProperty(key, value);
- }
- }
-
-
-## Resource Adapter Service
-
-Provides an adapter for a specific type of resource.
-
-### Motivation
-
-Resource adapters are similar to normal adapters, but instead of requiring a service, they require a resource and provide a service on top of it. Resources are an abstraction that is introduced by the dependency manager, represented as a URL. They can be implemented to serve resources embedded in bundles, somewhere on a file system or in a content repository or database.
-
-### Structure
-
-<img src="./diagrams/resourceadapter.png" alt="Singleton" style="width: 180px"/>
-
-## Temporal Dependency
-
-Provides a proxy that hides the service dynamics of a dependency, even if it disappears for a short time.
-
-### Motivation
-
-As a service consumer, you sometimes do not want to deal with the dynamics of services and the fact that they tend to go away for short periods of time whilst their hosting bundle gets updated. A temporal dependency provides you with a proxy that hides these dynamics and blocks your calls if you try to invoke a method on a service that is currently "updating". The maximum time to wait is configurable and you will get an exception if no new service becomes available before that time.
-
-### Structure
-
-## Null Object
-
-Provides an implementation of an object that does nothing and can be used in the absence of the real object.
-
-### Motivation
-
-When a component depends on a service, but the dependency is optional, it means that it will use this service when available, but it can still operate if it's not. Constantly checking in your code if a service is actually available tends to lead to code with a lot of "`if (service != null) service.invoke();`" constructions which do not help with code readability. Instead, the dependency manager offers you a mechanism where it will inject null objects for services that are currently not a [...]
-
-### Structure
-
-## Whiteboard
-
-Handles listeners by leveraging the OSGi service registry to publish and look them up.
-
-### Motivation
-
-The traditional model for dealing with listeners in Java needlessly complicates things in an OSGi context. Instead of having listeners registering themselves with the component that will invoke them on any change, a listener simply registers itself in the service registry and the component will do a lookup of all relevant services. This is explained in more detail on the OSGi.org wiki in the ["Listeners considered harmful: the 'whiteboard' pattern"](http://www.osgi.org/wiki/uploads/Links [...]
-
-### Structure
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext
deleted file mode 100644
index 5fac8c8..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext
+++ /dev/null
@@ -1,48 +0,0 @@
-Title: Dependency Manager - Development
-
-When downloading or checking out the source code, please also consult release/resources/src/README.src for up to date instructions on how to build that particular version.
-
-## Prerequisites
-
-If you are using a corporate http proxy, you should set the following environment variables:
-
- $ export GRADLE_OPTS="-Dhttp.proxyHost=<your proxy ip> -Dhttp.proxyPort=<your proxy port> -Dhttps.proxyHost=<your proxy ip> -Dhttps.proxyPort=<your proxy port>"
- $ export http_proxy=<your proxy ip>:<your proxy port>
- $ export https_proxy=<your proxy ip>:<your proxy port>
-
-## Compilation Using gradle:
-
-- Install latest Java 8 (the dm libraries has been built and tested with java 1.8.0_74)
-
-- Compile Dependendency Manager annotations bndtools plugin:
-
- $ ./gradlew org.apache.felix.dependencymanager.annotation:jar
-
-- Compile all other bundles:
-
- $ ./gradlew jar
-
-- Run junit tests:
-
- $ ./gradlew test
-
-- Run integration tests:
-
- $ ./gradlew check
-
-## Compilation Using Eclipse:
-
-- Install Latest Eclipse Mars.
-- Use the dependency manager folder as the root of your workspace.
-- Configure two JREs for Java 8:
- * Go to Windows -> Preferences -> Java -> Installed JREs
- * Add your jdk8 JRE
-- Install BndTools 3.4.0 or later version and (optionally) a subversion plugin for Eclipse.
-- Open BndTools perspective
-- Import Dependency Manager into Eclipse, and compile everything
-- if it's the first time you import the project into eclipse, it may happen that some modules that requires the Dependency Manager Annotations bnd plugin don't compile: It's a know issue. To work around, restart eclipse and rebuild every modules.
-- Click on org.apache.felix.dependencymanager project and run it as "JUnit test".
-- Click on org.apache.felix.dependencymanager.shell and run it as "JUnit test"
-- Click on org.apache.felix.dependencymanager.itest and run it as "Bnd OSGi Test Launcher (Junit)".
-- Click on org.apache.felix.dependencymanager.runtime.itest and run it as ""Bnd OSGi Test Launcer (Junit)".
-- Click on org.apache.felix.dependencymanager.lambda.itest and run it as ""Bnd OSGi Test Launcer (Junit)".
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.mdtext
deleted file mode 100644
index fa2f7c6..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/dm-lambda.mdtext
+++ /dev/null
@@ -1,943 +0,0 @@
-Title: Dependency Manager Lambda
-
-----------
-
-**Welcome to Felix Dependency Manager Lambda.**
-
-## Introduction
-
-Since the R8 version, a new dm-lambda library has been introduced in the DM distribution. This new library allows to programmatically declare OSGi components
-using a new style based on java8 lambda expressions and other goodies like method references.
-
-The new library is based on the `builder` design pattern applied to java8 lambdas. Basically, you call a chain of methods from a
-fluent `builder`, and at the end of the chain, you call "`build()`" which returns the actual DM objects that you already know from
-the original DM API.
-We'll see later that using lambdas avoids to call the last "`build`" method and allows to automatically add the constructed DM Component into the
-DependencyManager object.
-
-Please notice that using the dm-lambda library requires the usage of a recent Java8 jvm (the library has been tested with java version "1.8.0_74").
-
-## Comparing two activators using old and new API:
-
-Before presenting the new API, let's get a jump start and dive into a comparison between the old and new API: assume we have a `ServiceConsumer` which depends on the following services:
-
-- a required dependency on `ServiceProvider` service with a "`(p1=v1)`" filter. The dependency is injected in the "`ServiceConsumer.setProvider()`" method.
-- a Configuration with pid="`org.apache.felix.dm.lambda.samples.hello.ServiceConsumer`".
-
-Now assume we have `ServiceProvider` provided with p1="v1" and p2=123 service properties; and the provider also depends on:
-
-- a required `LogService` service (injected in class fields).
-- a required `EventAdmin` service (injected in class fields).
-
-Then we have the following typical Activator (we define both components in the same Activator for simplicity):
-
- :::java
- import org.apache.felix.dm.DependencyActivatorBase;
- ...
-
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- // Declare our Consumer component
-
- Component consumer = createComponent()
- .setImplementation(ServiceConsumer.class)
- .add(createServiceDependency().setService(ServiceProvider.class, "(p1=v1)").setRequired(true).setCallbacks("setProvider", null))
- .add(createConfigurationDependency().setPid(ServiceConsumer.class.getName()));
- dm.add(consumer);
-
- // Declare our ServiceProvider service component
-
- Properties properties = new Properties();
- Properties.put("p1", "v1");
- properties.put("p2", 123);
- Component provider = createComponent()
- .setImplementation(ServiceProviderImpl.class)
- .setInterface(ServiceProvider.class.getName(), properties)
- .add(createServiceDependency().setService(LogService.class).setRequired(true))
- .add(createServiceDependency().setService(EventAdmin.class, null).setRequired(true));
- dm.add(provider);
- }
- }
-
-Now, let's rework the above example, using the new dm-lambda API:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
- ...
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- // Declare our Consumer component
-
- component(comp -> comp.impl(ServiceConsumer.class)
- .withSvc(ServiceProvider.class, svc -> svc.required().filter("(p1=v1)").add(ServiceConsumer::setProvider))
- .withCnf(ServiceConsumer.class.getName()));
-
- // Declare our ServiceProvider service component:
-
- component(comp -> comp.impl(ServiceProviderImpl.class)
- .provides(ServiceProvider.class, p1 -> "v1", p2 -> 123)
- .withSvc(true, LogService.class, EventAdmin.class));
- }
-
-# Principle
-
-The new API is provided by the `org.apache.felix.dependencymanager.lambda.jar` bundle. The following builders are currently supported:
-
-- ComponentBuilder: it is used to build org.apache.felix.dm.Component from original DM API.
-- ServiceDependencyBuilder: builds org.apache.felix.dm.ServiceDependency from original DM API.
-- ConfigurationDependencyBuiler: builds org.apache.felix.dm.ConfigurationDependency from original DM API.
-- BundleAdapterBuilder: builds a bundle adapter component from the original DM API.
-- ServiceAdapterBuilder.java: builds a DM service adapter from the original DM API.
-- FactoryPidAdapterBuilder: builds a DM factory pid adapter from the original DM API.
-- FutureDependencyBuilder: it's a new feature allowing to "wait for" an asynchronous event represented by a standard jdk8 `CompletableFuture` object.
-
-(There is currently no builders for DM ResourceDependency and ResourceAdapter objects, but they will be supported soon).
-
-There are two ways to use these builders:
-
-You can first instantiate builders using some of the convenient factory methods available from the DependencyManagerActivator class, which is the new base class
-for dm-lambda activators:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
- import org.apache.felix.dm.lambda.ComponentBuilder;
- import org.apache.felix.dm.Component;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- ComponentBuilder builder = component();
- Component comp = builder.impl(Hello.class).build();
- dm.add(comp);
- }
- }
-
-The `component()` method returns a `ComponentBuilder` and the call to `build` at the end of the method calls chain returns the actual DM Component object.
-
-Here is a shorter version:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
- import org.apache.felix.dm.Component;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- Component comp = component().impl(Hello.class).build());
- dm.add(comp);
- }
- }
-
-
-Now, most of the time, in an Activator you usually create a Component and immediately add it to the `dm` object.
-So, in order to reduce the code size, you can then use a component() method that accepts a lambda which takes as
-argument a `Consumer<ComponentBuilder>` parameter.
-So, the lambda has just to invoke the chain of necessary methods from the builder, without having to call the last "`build`" method.
-The constructed Component is then automatically added to the `dm` object.
-
-The following is the same as above, using a `consumer<ComponentBuilder>` lambda expression:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
- import org.apache.felix.dm.lambda.ComponentBuilder;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component((ComponentBuilder comp) -> comp.impl(Hello.class));
- }
- }
-
-Here is a more concise version where the type of the lambda parameter is not declared:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class));
- }
- }
-
-## Dependency default mode (required or optional ?)
-
-When you declare a dependency without explicitly invoking `optional()`, `required()`, or `required(boolean)`, then by default,
-the dependency is assumed to be optional. This is in line with the behavior of the Dependency Manager API.
-
-Now, you can change this default behavior by configuring the "`org.apache.felix.dependencymanager.lambda.defaultRequiredDependency`"
-system property. This property can be set with a list of java package prefixes (comma separated).
-When a component implementation class starts with one of the package prefixes specified in the above property, then dependencies will be
-assumed to be required by default.
-
-## Adding service dependencies injected in class fields.
-
-You can add a dependency using the "`withSvc`" methods available from the ComponentBuilder interface.
-Such methods accept a `Consumer<ServiceDependencyBuilder>` lambda expression, which may then configure the dependency using a chain of method calls (filter/callbacks,autoconfig, etc ...):
-When you don't specify callbacks, services are injected in class fields with compatible service dependency type, but you can specify a field name.
-Unavailable optional dependencies are injected as "`Null Objects`".
-
-The following example adds a service dependency on a LogService with a service filter.
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
- import org.apache.felix.dm.lambda.ServiceDependencyBuilder;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class)
- .withSvc(LogService.class, (ServiceDependencyBuilder svc) -> svc.filter("(vendor=apache)")));
- }
- }
-
-Here is a more concise version where the type of the `svc` lambda parameter is not declared:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class).withSvc(LogService.class, svc -> svc.filter("(vendor=apache)")));
- }
- }
-
-When injecting services in class fields (auto config mode), there are shotcuts that avoid using a lambda when defining a service dependency.
-These shortcuts are available from the ComponentBuilder interface.
-
-Examples:
-
-#### Declaring multiple auto config dependencies in one shot (using varargs of interfaces):
-
- :::java
- component(comp -> comp.impl(Hello.class).withSvc(ConfigurationAdmin.class, EventAdmin.class, MetatypeService.class));
-
-#### Declaring multiple auto config dependencies in one shot with a `required` flag:
-
- :::java
- component(comp -> comp.impl(Hello.class).withSvc(true, ConfigurationAdmin.class, EventAdmin.class, MetatypeService.class));
-
-#### Declaring an autoconfig dependency with a `required` flag:
-
- :::java
- component(comp -> comp.impl(Hello.class).withSvc(ConfigurationAdmin.class, true));
-
-#### Declaring an autoconfig dependency with a `filter ` and `required` flag:
-
- :::java
- component(comp -> comp.impl(Hello.class).withSvc(ConfigurationAdmin.class, "(vendor=apache)", true));
-
-#### Declaring a autoconfig dependency with a `filter `, an explicit class field, and `required` flag:
-
- :::java
- component(comp -> comp.impl(Hello.class).withSvc(ConfigurationAdmin.class, "(vendor=apache)", "configadmin", true));
-
-Dependency services can be injected in the following kind of fields:
-
-- a field having the same type as the dependency. If the field may be accessed by anythread, then the field should be declared
-volatile, in order to ensure visibility when the field is auto injected concurrently.
-- a field which is assignable to an `Iterable<T>` where T must match the dependency type. In this case, an Iterable will be
-injected by DependencyManager before the start callback is called. The Iterable field may then be traversed to inspect the
-currently available dependency services. The Iterable can possibly be set to a final value so you can choose the Iterable implementation of your choice (for example, a CopyOnWrite ArrayList, or a ConcurrentLinkedQueue).
-- a `Map<K,V>` where K must match the dependency type and V must exactly equals Dictionary class. In this case, a
-ConcurrentHashMap will be injected by DependencyManager before the start callback is called.
-The Map may then be consulted to lookup current available dependency services, including the dependency service properties
-(the map key holds the dependency services, and the map value holds the dependency service properties).
-The Map field may be set to a final value so you can choose a Map of your choice (Typically a ConcurrentHashMap).
-A ConcurrentHashMap is "weakly consistent", meaning that when traversing the elements, you may or may not see any concurrent
-updates made on the map. So, take care to traverse the map using an iterator on the map entry set,
-which allows to atomically lookup pairs of Dependency service/Service properties.
-
-## Service Dependency callbacks
-
-You can specify callbacks on the component implementation class using the "`add/change/remove/swap`" `ServiceDependencyBuilder` methods:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class).withSvc(LogService.class, svc -> svc.add("setLog")));
- }
- }
-
-Now you can also use a more type-safe callback using a Java 8 method reference:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class).withSvc(LogService.class, svc -> svc.add(Hello::setLog)));
- }
- }
-
-or:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class).withSvc(LogService.class, svc -> svc.add(Hello::setLog).remove(Hello::unsetLog)));
- }
- }
-
-The following callback methods signatures are supported when using method references:
-
-For add/change/remove method references:
-
- :::java
- method(S service)
- method(S service, ServiceReference<S> serviceRef),
- method(S service, Map<String, Object> serviceProperties)
- method(S service, Dictionary<String, Object> serviceProperties)
- method(S service, Component serviceComponent)
- method(S service, Component serviceComponent, ServiceReference<S> serviceRef)
-
-and for swap method references:
-
- :::java
- method(S oldService, S newService)
- method(S oldService, S newService, Component component))
- method(ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService)
- method(ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService, Component component)
-
-## Defining Service Dependency Object instance callback
-
-Sometimes, you want to inject the dependency to a separate object that is not part of the component implementation classes.
-For example, the following example injects a dependency in a DependencyHandler instance:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- DependencyHandler depHandler = new DependencyHandler();
- component(comp -> comp.impl(Hello.class).withSvc(LogService.class, svc -> svc.add(depHandler, "setLog")));
- }
- }
-
-or using method reference:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- DependencyHandler depHandler = new DependencyHandler();
- component(comp -> comp.impl(Hello.class).withSvc(LogService.class, svc -> svc.add(depHandler::setLog)));
- }
- }
-
-You can chain multiple callbacks:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- DependencyHandler depHandler = new DependencyHandler();
- component(comp -> comp.impl(Hello.class).withSvc(LogService.class, svc -> svc.add(Hello::setLog).add(depHandler::setLog)));
- }
- }
-
-## Providing a service
-
-When a component provides a service with some properties, so far it was necessary to create a Dictionary and pass it to the `Component.setInterface()` method.
-
-Now you can pass properties directly to the `provides` method as varargs of properties (a suite of key-value properties):
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class).provides(HelloService.class, "p1", "v1", "p2", 123));
- }
- }
-
-or if you build your application using the `-parameters` javac option, you can also use the "`FluentProperty`" lambda that allows to declare
-service properties as a suite of "`key -> value`" lambdas, like this:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Hello.class).provides(HelloService.class, p1 -> "v1", p2 -> 123));
- }
- }
-
-**CAUTION**: defining service properties using lambda parameters only works with Java8 , not
-Java9/10/11, and this feature may be removed in next version.
-
-## Depending on a configuration.
-
-Configuration dependency can be defined using the "`withCnf`" ComponentBuilder method.
-Two families of callbacks are supported:
-
-- reflection based callbacks: you specify a callback method name
-- method reference callbacks: you specify a java8 method reference
-
-Callbacks may accept a Dictionary, a Component, or a user defined configuration type interface. If you only specify a pid, by default the callback method name is assumed to be "updated".
-
-### configuration types
-
-Configuration types are a new feature that allows you to specify an interface that is implemented by DM and such interface is then injected to your callback instead of the actual Dictionary. Using such configuration interface provides a way for creating type-safe configurations from a actual Dictionary that is normally injected by Dependency Manager. The callback accepts in argument an interface that you have to provide, and DM will inject a proxy that converts method calls from your con [...]
-As proxies are injected, no implementations of the desired configuration-type are necessary!
-
-The lookups performed are based on the name of the method called on the configuration type. The method names are "mangled" to the following form: [lower case letter] [any valid character]*. Method names starting with get or is (JavaBean convention) are stripped from these prefixes. For example: given a dictionary with the key "foo" can be accessed from a configuration-type using the following method names: foo(), getFoo() and isFoo().
-
-The return values supported are: primitive types (or their object wrappers), strings, enums, arrays of primitives/strings, Collection types, Map types, Classes and interfaces. When an interface is returned, it is treated equally to a configuration type, that is, it is returned as a proxy.
-
-Arrays can be represented either as comma-separated values, optionally enclosed in square brackets. For example: [ a, b, c ] and a, b,c are both considered an array of length 3 with the values "a", "b" and "c". Alternatively, you can append the array index to the key in the dictionary to obtain the same: a dictionary with "arr.0" => "a", "arr.1" => "b", "arr.2" => "c" would result in the same array as the earlier examples.
-
-Maps can be represented as single string values similarly as arrays, each value consisting of both the key and value separated by a dot. Optionally, the value can be enclosed in curly brackets. Similar to array, you can use the same dot notation using the keys. For example, a dictionary with
-
- "map" => "{key1.value1, key2.value2}"
-
-and a dictionary with
-
- "map.key1" => "value1", "map2.key2" => "value2"
-
-result in the same map being returned. Instead of a map, you could also define an interface with the methods getKey1() and getKey2 and use that interface as return type instead of a Map.
-
-In case a lookup does not yield a value from the underlying map or dictionary, the following rules are applied:
-
-- primitive types yield their default value, as defined by the Java Specification;
-- string, Classes and enum values yield null;
-- for arrays, collections and maps, an empty array/collection/map is returned;
-- for other interface types that are treated as configuration type a null-object is returned.
-
-### multiple ways to define a configuration dependency
-
-You can first pass a configuration pid to the `withCnf` method. In this example, the Hello component has an "`updated(Dictionary properties)`" method called when configuration is available or updated.
-
- :::java
- component(comp -> comp.impl(Hello.class).withCnf("my.pid"))
-
-You can pass a "`configuration type`" to the `withCnf` method. The pid is assumed to be the fqdn of the type passed to the `withCnf` method, and the callback is assumed to be "`updated`"
-and to accept as argument an implementation of the specified configuration type:
-
- :::java
- component(comp -> comp.impl(Hello.class).withCnf(MyConfiguration.class))
-
-You can define the updated callback method explicitly using a ConfigurationDependencyBuilder lambda that you can pass to the "`withCnf`"
-method:
-
- :::java
- component(comp -> comp.impl(Hello.class).withCnf((ConfigurationDependencyBuilder cnf) -> cnf.pid("my.pid").update("modified")));
-
-Here is shorter version which does not declare the type of the lambda passed to the `withCnf` method:
-
- :::java
- component(comp -> comp.impl(Hello.class).withCnf(cnf -> cnf.pid("my.pid").update("modified")));
-
-You can also define the callback using a method reference:
-
- :::java
- component(comp -> comp.impl(Hello.class).withCnf(cnf -> cnf.pid("my.pid").update(Hello::modified)));
-
-And finally, you can define a configuration type, and a callback using a method reference. Here, the updated callback has to take
-in argument the configuration type parameter (the pid is assumed to be the fqdn of the configuration type):
-
- :::java
- component(comp -> comp.impl(Hello.class).withCnf(cnf -> cnf.update(MyConfiguration.class, Hello::modified)));
-
- class Hello {
- void modified(MyConfiguration properties) { ... }
- }
-
-#### Configuration Dependency Examples based on method references:
-
-Code example with a component that defines a Configuration Dependency using a specific callback method reference, and the method accepts in argument a configuration type
-(the pid is assumed to be the fqdn of the configuration type):
-
- :::java
- public interface MyConfig {
- String getAddress();
- int getPort();
- }
-
- public class ServiceImpl {
- void updated(MyConfig cnf) {
- if (cnf != null) {
- String addr = cnf.getAddress();
- int port = cnf.getPort();
- ...
- }
- }
- }
-
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(ServiceImpl.class).withCnf(conf -> conf.update(MyConfig.class, ServiceImpl::updated)));
- }
- }
-
-Same example, using a shortcut for the `withCnf` dependency, which is only defining the configuration type
-(the pid is assumed to be the fqdn of the config type, and the callback name is assumed to be "updated"):
-
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(ServiceImpl.class).withCnf(MyConfig.class));
- }
- }
-
-Code example with a component that defines a Configuration Dependency using a specific callback method reference which accepts a Dictionary in argument:
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp
- .impl(ServiceImpl.class)
- .withCnf(conf -> conf.pid("my.pid").update(ServiceImpl::setProperties)));
- }
- }
-
-#### Configuration Dependency Examples based on method reflection:
-
-Code example which defines a configuration dependency injected in the "ServiceImpl.updated(Dictionary)" callback
-(the pid is directly passed in argument to the `withCnf` method):
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(ServiceImpl.class).withCnf("my.pid")));
- }
- }
-
-Code example with a component that defines a Configuration Dependency using a specific callback method name:
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(ServiceImpl.class).withCnf(conf -> conf.pid("my.pid").update("modified")));
- }
- }
-
-
-## Managing components outside of Activators.
-
-You can manage Components outside of the Activator by using some static factory methods from the `DependencyManagerActivator` class.
-
-For example, consider a use case where you want to retrieve some information from some already injected services, and you then want to dynamically add more dependencies from your
-`init` component callback. First let's look at the Activator:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Pojo.class).withCnf("pojo.pid"));
- }
- }
-
-Here, we define a Configuration dependency with a "pojo.pid" configuration pid. So, now, the Pojo will then for example be able to parse an xml from the configuration, and depending on
-what it has parsed, it will possibly add more dependencies, like this:
-
- :::java
- import static org.apache.felix.dm.lambda.DependencyManagerActivator.*;
- import org.apache.felix.dm.Component;
-
- public class Pojo {
- void updated(Dictionary conf) throws Exception {
- parseXml(conf.get("some.xml.configuration"));
- }
-
- void init(Component c) { // lifecycle dm callback that allows you to add more dependencies
- if (xmlConfigurationRequiresEventAdmin) {
- component(c, comp -> comp.withSvc(EventAdmin.class));
- }
- }
- }
-
-The available variety of factory methods allows you to also create some DM objects and add them manually, like:
-
- :::java
- import static org.apache.felix.dm.lambda.DependencyManagerActivator.*;
- import org.apache.felix.dm.Component;
- import org.apache.felix.dm.ServiceDependency;
- import org.apache.felix.dm.DependencyManager;
-
- public class Pojo {
- void updated(Dictionary conf) throws Exception {
- parseXml(conf.get("some.xml.configuration"));
- }
-
- void init(Component c) { // lifecycle dm callback that allows you to add more dependencies
- if (xmlConfigurationRequiresEventAdmin) {
- DependencyManager dm = c.getDependencyManager();
- ServiceDependency dep = serviceDependency(c, EventAdmin.class).filter("(vendor=felix)").build();
- dm.add(dep);
- }
- }
- }
-
-And an example where you create a new DM component from the code:
-
- :::java
- import static org.apache.felix.dm.lambda.DependencyManagerActivator.*;
- import org.apache.felix.dm.DependencyManager;
-
- public class Pojo {
- volatile DependencyManager m_dm;
-
- void createComponent() {
- component(m_dm, comp -> comp.impl(NewComponent.class).withSvc(LogService.Class, EventAdmin.class));
- }
- }
-
-## Component Lifecycle Callbacks
-
-Like with DM API, default lifecycle callbacks are the following:
-
-- "init": the method is called on the component implementation class(es) once all required dependencies declared in the Activator
-have been injected. This method can then be used to possibly add more dependencies dynamically.
-- "start": the method is called on the component implementation class(es) once all required dependencies (including the ones added
-from the "init" callback) have been injected. Then the optional dependency callbacks are invoked (after the start callback).
-- "stop": the method is called on the component implementation class(es) when some required dependencies are being lost
-or when the component's bundle is stopping.
-- "destroy": the component is destroyed and may be re-created and re-initialized in case some required dependencies comes up again.
-
-You can change the callback names using the "init"/"start"/"stop"/"destroy" methods from the ComponentBuilder interface. For example:
-
- :::java
- component(comp -> comp.impl(Pojo.class)
- .init("initialize")
- .start("activate")
- .stop("deactivate")
- .destroy("shutdown"));
-
-Same example, but with some specific callback instance on which the callback should be invoked:
-
- CallbackHandler handler = new CallbackHandler();
- component(comp -> comp.impl(Pojo.class)
- .init(handler, "initialize")
- .start(handler, "activate")
- .stop(handler, "deactivate")
- .destroy(handler, "shutdown"));
-
-When using callback instances, you can also use method references using the callback instance object:
-
- CallbackHandler handler = new CallbackHandler();
- component(comp -> comp.impl(Pojo.class)
- .init(handler::initialize)
- .start(handler::activate)
- .stop(handler::deactivate)
- .destroy(handler::shutdown));
-
-Callbacks are empty-args, or may take a DM Component in argument.
-
-Method Reference for Component implementations class are not supported.
-## Creating Aspect Components
-
-Like with the original DM API, you can create a chain of aspects (service interceptors) ordered by a ranking attribute, using the "`aspect`" factory method.
-This method accepts in argument a ServiceAspectBuilder.
-
-Code example which provides a "LogService" aspect that performs spell-checking of each log message. The aspect decorates a LogService.
-The aspect also depends on a DictionaryService that is internally used to perform log spell checking.
-The LogService and DictionaryService services are injected in the aspect implementation using reflection on class
-fields:
-
- ::::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- aspect(LogService.class, (ServiceAspectBuilder asp) -> asp.impl(SpellCheckLogAspect.class).rank(10).withSvc(DictionaryService.class));
- }
- }
-
-Same more concise example which does not declare the type of the lambda builder argument:
-
- ::::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- aspect(LogService.class, asp -> asp.impl(SpellCheckLogAspect.class).rank(10).withSvc(DictionaryService.class));
- }
- }
-
-Same example, but using callbacks for injecting LogService and DictionaryService in the aspect implementation class:
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- aspect(LogService.class, asp -> asp
- .impl(SpellCheckLogAspect.class).rank(10)
- .add(SpellCheckLogAspect::setLogService)
- .withSvc(DictionaryService.class, svc -> svc.add(SpellCheckLogAspect::setDictionary)));
- }
- }
-
-## Creating Service Adapter Components
-
-DM service adapters allow to create adapter services when a given type of adapted service is found in the OSGI registry.
-Using the "`adapter`" factory method, you can pass to it consumer of an `ServiceAdapterBuilder` that
-can be used to construct a DM adapter component.
-
-Code example that adapts a "Device" service to an HttpServlet service. The adapter is created using a ServiceAdapterBuilder that is passed to the lambda.
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- adapter(Device.class, (ServiceAdapterBuilder adapt) -> adapt.impl(DeviceServlet.class).provides(HttpServlet.class).properties(alias -> "/device");
- }
- }
-
-Same more concise example which does not declare the type of lambda parameter:
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- adapter(Device.class, adapt -> adapt.impl(DeviceServlet.class).provides(HttpServlet.class).properties(alias -> "/device");
- }
- }
-
-## Creating Factory Configuration Adapter Components
-
-A Factory Configuration Adapter allows to create many instances of the same service, each time a configuration instance is created for a given factory pid.
-To declare a factory pid configuration adapter, use the `factoryPid` method available from the DependencyManagerActivator class and pass to it
-a lambda for the FactoryPidAdapterBuilder argument:
-
-Example that defines a factory configuration adapter service for the "foo.bar" factory pid. For each factory pid instance, an instance of the DictionaryImpl component will be created:
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- factoryPidAdapter((FactoryPidAdapterBuilder adapter) -> adapter
- .impl(DictionaryImpl.class).factoryPid("foo.bar").propagate().update(ServiceImpl::updated)
- .withSvc(LogService.class, log -> log.optional()));
- }
- }
-
-Same more concise example that is not declaring the type of the lambda type:
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- factoryPidAdapter(adapter -> adapter
- .impl(DictionaryImpl.class).factoryPid("foo.bar").propagate().update(ServiceImpl::updated)
- .withSvc(LogService.class, log -> log.optional()));
- }
- }
-
-Example that defines a factory configuration adapter using a user defined configuration type (the pid is by default assumed to match the fqdn of the configuration type):
-
- :::java
- public interface DictionaryConfiguration {
- public String getLanguage();
- public List<String> getWords();
- }
-
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- factoryPidAdapter(adapter -> adapter
- .impl(DictionaryImpl.class).propagate().update(DictionaryConfiguration.class, ServiceImpl::updated)
- .withSvc(LogService.class, log -> log.optional()));
- }
- }
-
-## Creating a Bundle Adapter component
-
-A Bundle Adapter is used to create a Component when a bundle that matches a given filter is found.
-To build a DM adapter, you can use the "`bundleAdapter`" factory method: it takes in argument a consumer of a
-BundleAdapterBuilder object, which is used to construct a real DM BundleAdapter component.
-
-Example that creates a BundleAdapter service for each started bundle (the bundle is added using a method reference):
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- bundleAdapter(adapt -> adapt
- .impl(BundleAdapterImpl.class).provides(BundleAdapter.class).mask(Bundle.INSTALLED|Bundle.RESOLVED|Bundle.ACTIVE)
- .add(BundleAdapterImpl::bundleStarted)
- .withSvc(LogService.class, "(vendor=apache)"));
- }
- }
-
-## CompletableFuture dependency.
-
-The new library provides a new feature which allows your component to depend on the result of a jdk8 `CompletableFuture`.
-CompletableFuture java8 class provides an asynchronous event-driven model and you can now define dependencies on any asynchronous events,
-like if they were service dependencies.
-
-Let's explore this new dependency using an advanced example: assume you develop a component that needs to
-track any "Tracked" services registered in the Registry, using a classic whiteboard pattern. But before, you need to
-download a web page at initialization, before you component is started. The downloaded webpage is required to be able to
-handle Tracked services. Now, you don't want to block the initialization of your component because in a reactive word,
-it is forbidden to block on the current thread.
-
-So, you use an `HttpClient` which allows to asynchronously download a web page: this service is assumed to provide a doGET() method
-which does not block the current thread, but instead returns `CompletableFuture<String>`
-which represents the future result of the asynchronously downloaded page.
-
-From your component init() method, you can then declare a FutureDependency on the result of the `CompletableFuture<String>`.
-A Future Dependency can be defined using the "withFuture" method available from the ComponentBuilder interface, and this method takes as argument two args: a CompletableFuture, and a
-`consumer<FutureDependencyBuilder>`. The second arg is a lambda that can be used to configure the callback to invoke when the CF has completed.
-
-And once the result completes, start() will be called, and at this point, the Tracked services will then
-be injected (using DM, optional service callbacks are always invoked after the start() callback, never before).
-
-So, the Activator looks like this:
-
- :::java
- import org.apache.felix.dm.lambda.DependencyManagerActivator;
-
- public class Activator extends DependencyManagerActivator {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- component(comp -> comp.impl(Pojo.class).provides(PojoService)
- .withCnf(cnf -> cnf.pid("foo.pid"))
- .withSvc(HttpClient.class, svc -> svc.required())
- .withSvc(Tracked.class, svc -> svc.optional().add(Pojo::bindTracked));
- }
- }
-
-Now, here is the implementation for our component which downloads the URL from its init method. The init method will declare a "FutureDependency"
-for the result of the `CompletableFuture<String>` returned by the HttpClient. And once the result is injected
-in the setPage callback, then the start() callback will be called, and finally, any registered Tracked services will be
-injected in the "bindTracked" method:
-
- :::java
- import static org.apache.felix.dm.lambda.DependencyManagerActivator.*;
- import org.apache.felix.dm.Component;
-
- public class Pojo implements PojoService {
- HttpClient m_httpClient; // injected.
- String m_url; // the URL to download using the http client.
-
- void updated(Dictionary<String, Object conf) throws Exception {
- m_url = (String) conf.get("download.url");
- }
-
- // lifecycle dm callback that allows you to add more dependencies. start will be called once the webpage has been downloaded.
- void init(Component c) {
- // Let's schedule a download for our web page.
- CompletableFuture<String> futurePage = m_httpClient.doGET(m_url);
-
- // Add a required dependency to the result of the CF, and inject the result in our setPage method.
- component(c, comp -> comp.withFuture(futurePage, future -> future.complete(this::setPage)));
- }
-
- void setPage(String content) {
- // Called when the CompletableFuture has completed
- }
-
- void start() {
- // We have downloaded the page, our component is starting and is about to be registered
- }
-
- void bindTracked(Tracked service) {
- // a Tracked service is injected, we can handle it because we are fully initialized.
- // (optional service callbacks are always invoked after the start callback).
- }
- }
-
-So, using the Future Dependency we can nicely reuse the jdk CompletableFuture as a required dependency. Without using the FutureDependency
-on the CompletableFuture returned by the HttpClient, we would then have to manually register our service using bundleContext.registerService (once the web page has been downloaded), and we
-would then have to check if the webpage has been downloaded each time a Tracked service is injected. And in case the page is not available, we would
-then have to cache the injected Tracked service and process it later, once the page has been downloaded.
-
-Also, notice that when the page is injected in the setPage() method, you absolutely don't need to deal with
-synchronization at all because in DM, all lifecycle and dependency callbacks are safely scheduled in a "serial queue" associated to the
-component.
-
-## Sample codes
-
-many samples codes are available from the distribution source release: Please take a look at the following:
-
-### org.apache.felix.dependencymanager.lambda.samples/src/org/apache/felix/dm/lambda/samples/hello/
-
-This sample provides a DM Activator declaring one service consumer and a service provider. The
-ServiceConsumer is also depending on a configuration pid (see org.apache.felix.dependencymanager.samples.hello.Configurator).
-
-### org.apache.felix.dependencymanager.lambda.samples/src/org/apache/felix/dm/lambda/samples/compositefactory/
-
-This Activator is an example usage of DM composite components. A composite component is implemented
-using a composition of multiple object instances, which are used to implement a given service.
-
-The sample also uses a Factory approach in order to instantiate the composition of objects: A
-"CompositionManager" is first injected with a Configuration that can possibly be used to create
-and configure all the composites.
-
-Dependencies are injected to some of the component implementation instances, using java8 method references. For instance,
-the LogService is only injected in the ProviderImpl and the ProviderComposite1 class and not in the ProviderComposite2 class.
-
-### org.apache.felix.dependencymanager.lambda.samples/src/org/apache/felix/dm/lambda/samples/device/
-
-This is an example showing a Dependency Manager "Adapter" in action. Two kinds of services are
-registered in the registry: some Device, and some DeviceParameter services. For each Device (having
-a given id), there is also a corresponding "DeviceParameter" service, having the same id.
-
-Then a "DeviceAccessImpl" adapter service is defined: it is used to "adapt" the "Device" service to
-a "DeviceAccess" service, which provides the union of each pair of Device/DeviceParameter having the
-same device.id . The adapter also dynamically propagate the service properties of the adapted Device
-service.
-
-### org.apache.felix.dependencymanager.lambda.samples/src/org/apache/felix/dm/lambda/samples/dictionary/
-
-This sample shows a "SpellChecker" application which provides a
-"dictionary:spellcheck" GOGO shell command. The GOGO "dictionary:spellcheck" command accepts a
-string as parameter, which is checked for proper exactness. The SpellChecker class has a
-required/multiple (1..N) dependency over every available "DictionaryService" services, which are
-internally used by the SpellChecker command, when checking word exactness.
-
-A DictionaryService is defined using a FactoryConfigurationAdapterService , allowing to instantiate
-many "DictionaryService" instances for each configuration that are added to the
-factory pid "Spell Checker Configuration" from web console.
-The factory pid configuration metatypes are defined using the bnd "metatype" annotations
-(see DictionaryConfiguration.java).
-
-The DictionaryService is decorated with a DictionaryAspect, which you can instantiate by adding a
-configuration to the "Spell Checker Aspect Dictionary" pid from web console. The
-aspect configuration metatype is also declared using the bnd metatype annotations (see
-DictionaryAspectConfiguration.java).
-
-Before running this sample, go to webconsole, and add some words in the "`Spell Checker Configuration`" factory PID, and
-in the "`Spell Checker Aspect Dictionary`" PID.
-
-Then go to gogo shell, and type dm help. You will normally see the dictionary:spellcheck command.
-Type dictionary:spellcheck with some words configured either in the spell checker configuration, or in the spell checker aspect configuration,
-and the dictionary will check for proper word exactness.
-
-### org.apache.felix.dependencymanager.lambda.samples/src/org/apache/felix/dm/lambda/samples/factory/
-
-This sample is an example usage of DM components that are created using a Factory object.
-The Factory is defined using java8 method references.
-
-### org.apache.felix.dependencymanager.lambda.samples/src/org/apache/felix/dm/lambda/samples/future/
-
-The purpose of this sample is to show an example usage of the new "CompletableFuture" dependency that has been
-added in the dm-lambda library. CompletableFuture java8 class provides functional operations and promotes an asynchronous event-driven model.
-
-In such model, you can use the new dm-lambda library to add dependencies on asynchronous events using the standard JDK CompletableFuture class.
-
-In this example, the Activator first defines a PageLink component that is used to download a given page from the web. The service then parses
-the content of the page and returns all available hrefs (links) found from the web page.
-
-The PageLink is initialized with the Felix web site URL, which is asynchronously downloaded from the PageLink::init method, using a CompletableFuture.
-The CF is then added as a "FutureDependency" in the PageLinkImpl.init() method, and when the CF completes, the PageLinkImpl.start() callback is invoked
-and the service is registered.
-
-The Activator is then getting injected with the PageLink service, and displays the links (hrefs) found from the Felix web site.
-
-Caution: if you are using a corporate http proxy, you have to fix the Activator in order to configure the ip addr and port number of your
-http proxy.
-
-## Javadoc
-
-You can find the javadoc for the new Dependency Manager Lambda library [here](../../../../apidocs/).
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext
deleted file mode 100644
index c151caf..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext
+++ /dev/null
@@ -1,15 +0,0 @@
-Title: Dependency Manager - History
-
-Dependency Manager has quite a long history, that starts over ten years ago.
-
-## The early years
-
-The first version of the Dependency Manager was created when Marcel started working on his first commercial OSGi project back in 2002. At that time, the OSGi specification was still at R2, and the only solution for managing dependencies was "service binder" which did not support the dynamics we needed at that time. Therefore, dependency manager was created, based on a fluent, declarative Java API.
-
-In 2005, after writing a white paper, dependency manager was presented at the OSGi DevCon in Paris. At that time, the project had been open sourced, but not yet at Apache. When the Oscar project finally decided to move to the incubator, where it became Felix, Dependency Manager was one of the subprojects that joined.
-
-## Life at Apache
-
-The move to Apache definitely gave the project a lot more visibility and, besides a larger user base, also attracted a few very talented developers. Xander did a lot of work in getting some of the higher level design patterns implemented, and Pierre added support for annotations and ensured that the code ran well on really big, multi-core systems.
-
-In 2014, after many discussions about new features and improvements we would like to add, we started experimenting with a completely new codebase, redesigning some aspects from the ground up based on all the knowledge and experience that we had gained over the years. About a year later, that lead to the release of Dependency Manager 4.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext
deleted file mode 100644
index 4148ab0..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext
+++ /dev/null
@@ -1,4 +0,0 @@
-Title: Dependency Manager - JavaDocs
-
-The various Dependency Manager JavaDocs for the API, the Annotations, and the Runtime can be found from the [main felix apidocs homepage](http://felix.apache.org/apidocs/).
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext
deleted file mode 100644
index 98b74f2..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext
+++ /dev/null
@@ -1,69 +0,0 @@
-Title: Apache Felix Dependency Manager - Migrating from earlier versions
-
-Below is a guide to help you migrate from version 3. Whilst older versions obviously still exist, we don't think people are still actively using them.
-
-## Migrating from version 3
-
-DependencyManager 4.0 has some API changes that need to be taken into account when migrating from DependencyManager 3.
-
-* A dependency can no longer be shared accross components.
-* You no longer have to call setInstanceBound() when adding a dependency from within the init() method of a component. Therefore the setInstanceBound() method has been removed from all Dependency interfaces.
-* in the Dependency interface, the following method have been removed: isInstanceBound, invokeAdded, invokeRemoved, createCopy.
-* In the Component interface, the "Object Component.getService()" method has been replaced by the "<T> T getInstance()" method.
-* In the Component interface, the "void addStateListener(ComponentStateListener listener) method" has been replaced by the "add(ComponentStateListener listener)" method.
-* In the Component interface, the "start", "stop", "getDependencies" methods have been removed.
-* In the Component interface and in the DependencyManager class, the createTemporalServiceDependency() method is now taking a timeout parameter: createTemporalServiceDependency(long timeout).
-* The ComponentStateListener interface has changed: it is now providing a single "changed(Component c, ComponentState state)" method.
-* The DependencyManager 4 Shell commands are no longer available for framework specific shell implementations, and support the gogo shell only.
-* The TemporalServiceDependency interface has been removed.
-* The Annotations processor is not generating anymore the Import-Service/Export Service by default (no need to specify the "build-import-export-service=false" option in the
-annotations plugin if you don't need to generate automatically the deprecated headers).
-* The Dependency Manager metatype annotations are now deprecated and it is encouraged to use standard bnd metatypes annotation instead.
-See org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/annot/DictionaryConfiguration.java for an example.
-You can also check http://www.aqute.biz/Bnd/MetaType for more information about the bnd metatypes annotations.
-* Dependency Manager is now fully built using bndtools, and there is no Maven annotation plugin anymore. However, the workaround is simply the
-use a "_plugin" option in the pom, and to declare a dependency inside the "plugin" configuration.
-Notice that in the R1 version, we are not pushing DM distribution to maven, so you have to do manually push the DM artifacts in your own nexus server.
-We'll try to release DM artifacts to maven central in the next release (R2).
-
-For example:
-
- :::xml
- <project ...>
- <dependencies>
- ...
- <dependency>
- <groupId>org.apache.felix</groupId>
- <artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
- <version>4.0.0</version>
- </dependency>
- </dependencies>
- <build>
- <plugins>
- ...
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <version>2.5.0</version>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-Name>Test</Bundle-Name>
- <Bundle-SymbolicName>test</Bundle-SymbolicName>
- <Import-Package>*</Import-Package>
- <Private-Package>test.dmannotations.withbndplugininvokedfrompom</Private-Package>
- <_plugin>org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug</_plugin>
- </instructions>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.apache.felix</groupId>
- <artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
- <version>4.0.0</version>
- </dependency>
- </dependencies>
- </plugin>
- </plugins>
- </build>
- </project>
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext
deleted file mode 100644
index 84df34c..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext
+++ /dev/null
@@ -1,2 +0,0 @@
-Title: Dependency Manager - Migrating from other solutions.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext
deleted file mode 100644
index ba1ed3b..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext
+++ /dev/null
@@ -1,37 +0,0 @@
-Title: Dependency Manager - Performance Tuning
-
-To further tune the performance of an application using Dependency Manager and a lot of services, we created the concept of filter indices. They work similarly to the way indices speed up relational database queries and are explained below.
-
-## Filter Indices
-
-Filter indices allow you to speed up the service resolution process by skipping the services registry, in favor of a fast index on given service properties.
-
-The Dependency Manager will look for a set of filter indices in the `org.apache.felix.dependencymanager.filterindex` system property. This system property uses the following syntax,
-
- property-index ::= service-property | service-property ',' property-index
- index ::= '*aspect*' | '*adapter*' | property-index
- indices ::= index | indices ';' index
-
-The implementation ships with three kinds of index implementations.
-
-- *Service property indices* are based on a set of service properties, like a multi-column index in a database.
-- *Aspect indices* work with Dependency Manager Aspect services, and will provide indexing for the specific filters that they use.
-- *Adapter indices* work like Aspect indices, but for Adapter services.
-
-### Performance
-
-The index isn't free, but reduces the linear (and wasteful) filter-based lookup to an indexed log(n) lookup. You can expect noticeable speedup if you have at least several hundred services.
-
-### Examples
-
- -Dorg.apache.felix.dependencymanager.filterindex=objectClass
-Sets an index on `objectClass`, speeding up lookups for any filter that contains an `objectClass` in its filter (all regular services do).
-
- -Dorg.apache.felix.dependencymanager.filterindex=objectClass,id
-This filter helps if you have a lot of similar services, identified by some `id`.
-
- -Dorg.apache.felix.dependencymanager.filterindex=objectClass,id;objectClass,ipAddress
-This is a set of two filter indices, helping when you have one set of services that has an `id`, and another set that uses an `ipAddress` for identification.
-
- -Dorg.apache.felix.dependencymanager.filterindex=*aspect*
-Provides indexing for all Aspect services.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext
deleted file mode 100644
index af1709f..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext
+++ /dev/null
@@ -1,97 +0,0 @@
-Title: Dependency Manager - Resource adapters
-
-Resource adapters are a special type of adapters which can adapt a resource into an OSGi service. These resources can be all kinds of resources, e.g. bundle resources, files, database records, anything as long as it can be resolved though a URL.
-
-The diagram below illustrates the classes involved in the resource adapter pattern:
-
-<img src="./diagrams/resources.png" alt="Resource adapters" style="width: 780px"/>
-
-The yellow elements have to be implemented in order to use the pattern.
-
-A resource adapter is configured as follows:
-
-
- manager.add(createResourceAdapter("*.MF", true, null, "changed")
- .setImplementation(ManifestAdapter.class));
-
-The filter semantics depend on the resource repository. In this example the resource repository will be serving bundle resources, so we're using a standard file wildcard filter. As the filter specifies in this case the resource of interest is the bundle manifest. For each MANIFEST.MF found a new instance of ManifestAdapter will be created and registered. Each instance gets access to the resource by injecting the URL of the resource into the implementation object.
-
- public class ManifestAdapter {
-
- private volatile URL url;
-
- void start() {
- System.out.println("started: " + url);
- }
-
- }
-
-
-But how does DM know where to go looking for manifest files? We'll it does not automatically. It requires you to implement a resource repository component. For each resource adapter service DM launches a ResourceHandler service tracking the resources the resource adapter is interested in. A resource repository is responsible for tracking resources and notifying adding / changing and removal of the resources from the repository. Notifying these resource 'events' is done by invoking the co [...]
-
-We'll explain how to implement a resource repository by an example. The example resource repository is a bundle resource repository which as it's name says, is capable of serving bundle resources.
-
-A simplified bundle resource repository looks as follows:
-
-
- public class BundleResourceRepositoryImpl {
-
- private Map<ServiceReference, ResourceHandler> handlers = new ConcurrentHashMap<>();
- private volatile BundleContext context;
-
- // added callback
- void addHandler(ServiceReference ref, ResourceHandler handler) {
- handlers.put(ref, handler);
- if (ref.getProperty(ResourceHandler.URL) != null) {
- URL url = (URL) ref.getProperty(ResourceHandler.URL);
- notifyMatchingInitialResource(url, handler);
- } else {
- String filter = (String) ref.getProperty(ResourceHandler.FILTER);
- notifyMatchingInitialResources(filter, handler);
- }
- }
-
- // removed callback
- void removeHandler(ServiceReference ref, ResourceHandler handler) {
- handlers.remove(ref);
- }
-
- private void notifyMatchingInitialResource(URL url, ResourceHandler handler) {
- if (bundleContainsResource(url)) {
- handler.added(url, new Hashtable<String, String>());
- }
- }
-
- @SuppressWarnings("unchecked")
- private void notifyMatchingInitialResources(String filter, ResourceHandler handler) {
- Enumeration<URL> entries = context.getBundle().findEntries("/", filter, true);
- while (entries.hasMoreElements()) {
- URL entry = entries.nextElement();
- handler.added(entry, new Hashtable<String, String>());
- }
- }
-
- private boolean bundleContainsResource(URL url) {
- return true; // more specific checks required
- }
- }
-
-
-The resource repository is registered in the bundle activator as follows:
-
-
- manager.add(createComponent().setImplementation(BundleResourceRepositoryImpl.class)
- .add(createServiceDependency().setService(ResourceHandler.class).setCallbacks("addHandler", "removeHandler")));
-
-A resource repository implementation must have a dependency on resource handlers. The ResourceHandler service has two important service properties:
-
-- "filter" (`ResourceHandler.FILTER`)
-- "url" (`ResourceHandler.URL`)
-
-A resource handler service has either one of these properties, not both! A resource handler with a filter can match multiple resources whereas a resource handler with a url only matches a single resource. It's important the resource repository handles both situations.
-
-When a new handler is being added, the resource repository should inform the resource handler on the resources it has that match the handler's filter or url. This is done by invoking the `added(url, properties)` method on the ResourceHandler. This callback results in the ResourceAdapter's ResourceDependency being satisfied, the url being injected into the resource adapter implementation object and the resource adapter implementation component being started.
-
-Besides the added() callback the resource repository is also responsible for handling the changed() and removed() methods on change or removal of the resource from the resource repository. For a bundle resource repository that's not likely to happen, but for a filesystem resource repository this can very well be the case.
-
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew-r15.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew-r15.mdtext
deleted file mode 100644
index 4dacff3..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew-r15.mdtext
+++ /dev/null
@@ -1,199 +0,0 @@
-Title:
-Notice: Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
- .
- http://www.apache.org/licenses/LICENSE-2.0
- .
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-This section describes some enhancements and API modification which have been performed in the dependency manager r15 release.
-Mainly,
-
-- Support for Java 9/10/11
-- annotation API has been simplified
-- support for user-defined annotation property types
-- DM API has been reworked to simplify the definition of aspect and adapters.
-- Lightweight support for OSGI service scopes
-- The dependency manager is now built using bndtools 3.5.0 as well as with bndlib 3.5.0
-- dependencymanager-deps is not used anymore (all required build time binary dependencies are now downloaded from maven central, and the gradle wrapper jar is also downloaded from the gradlew script). Moreover semantic versioning is now using a baseline that is downloaded from maven central.
-
-## API enhancements
-
-Some enhancements have been done in the dm API:
-
-- the api to define aspects and adapters have been reworked (but dm API remains backward compatible)
-- support for [service scopes](http://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager/reference/service-scopes.html)
-- you can now declare multiple property type interfaces when using Configuration Dependency or Factory Components (this was needed to implement the enhancements for the annotations)
-- configuration dependency using metatypes can now declare property types
-- Allow to specify if propagated configuration dependencies must override service service properties (it was not possible to override service properties with propagated service properties so far)
-- Added the following signatures in Component interface:
- * setInterface(Class serviceName, Dictionary properties)
- * setInterface(Class[] serviceNames, Dictionary properties)
-
-### Aspect/Adapters API enhancements
-
-So far, aspects or adapters were defined using many methods from DependencyManager or DependencyActivatorBase classes:
-
-For example, in DependencyManager.java, we have many signatures
-
- :::java
- public class DependencyManager {
- public Component createAdapterService(Class<?> serviceInterface, String serviceFilter) {...}
- public Component createAdapterService(Class<?> serviceInterface, String serviceFilter, String autoConfig) {...}
- public Component createAdapterService(Class<?> serviceInterface, String serviceFilter, String add, String change, String remove) {...}
- public Component createAdapterService(Class<?> serviceInterface, String serviceFilter, String add, String change, String remove, String swap) {...}
- public Component createAdapterService(Class<?> serviceInterface, String serviceFilter, String autoConfig, Object callbackInstance, String add, String change, String remove, String swap, boolean propagate) {...}
-
- public Component createFactoryConfigurationAdapterService(String factoryPid, String update, boolean propagate) {...}
- public Component createFactoryConfigurationAdapterService(String factoryPid, String update, boolean propagate, Object callbackInstance) {...}
- public Component createFactoryConfigurationAdapterService(String factoryPid, String update, boolean propagate, Class<?> configType) {...}
- public Component createFactoryConfigurationAdapterService(String factoryPid, String update, boolean propagate, Object callbackInstance, Class<?> configType) {...}
- public Component createAdapterFactoryConfigurationService(String factoryPid, String update, boolean propagate,String heading, String desc, String localization, PropertyMetaData[] propertiesMetaData) {...}
-
- public Component createBundleAdapterService(int bundleStateMask, String bundleFilter, boolean propagate) {...}
- public Component createBundleAdapterService(int bundleStateMask, String bundleFilter, boolean propagate, Object callbackInstance, String add, String change, String remove) {...}
-
- public Component createResourceAdapterService(String resourceFilter, boolean propagate, Object callbackInstance, String callbackChanged) {...}
- public Component createResourceAdapterService(String resourceFilter, boolean propagate, Object callbackInstance, String callbackSet, String callbackChanged)
- public Component createResourceAdapterService(String resourceFilter, Object propagateCallbackInstance, String propagateCallbackMethod, Object callbackInstance, String callbackChanged) {...}
- public Component createResourceAdapterService(String resourceFilter, Object propagateCallbackInstance, String propagateCallbackMethod, Object callbackInstance, String callbackSet, String callbackChanged) {...}
-
- public Component createAspectService(Class<?> serviceInterface, String serviceFilter, int ranking, String autoConfig) {...}
- public Component createAspectService(Class<?> serviceInterface, String serviceFilter, int ranking) {...}
- public Component createAspectService(Class<?> serviceInterface, String serviceFilter, int ranking, String add, String change, String remove) {...}
- public Component createAspectService(Class<?> serviceInterface, String serviceFilter, int ranking, String add, String change, String remove, String swap) {...}
- public Component createAspectService(Class<?> serviceInterface, String serviceFilter, int ranking, Object callbackInstance, String add, String change, String remove, String swap) {...}
-
-So, in this new release, we have simplified the usage of the aspect/adapters like this:
-instead of having to use some of the many methods from the DependencyManager or DependencyActivatorBase,
-we have added some new interfaces for the aspect and adapters, and these interfaces are extending the Component interface.
-All other existing methods have been moved to DependencyManagerCompat/DependencyActivatorBaseCompat classes and the
-DependencyManager/DependencyActovatorBase classes are now extending the compat classes: this allows to simplify the
-reading of the javadocs for DependencyManager/DependencyActovatorBase.
-
-For example, let's first show how an factory pid component was declared so far (a factory pid component is one which
-can be instantated multiple times using a "factory configuration" created using standard "configuration admin" service):
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- dm.add(createFactoryConfigurationAdapterService("my.factory.pid", "updated", true, MyConfig.class)
- .setInterface(MyService.class.getName(), null)
- .setImplementation(MyServiceImpl.class)
- .add(createServiceDependency().setService(LogService.class))); // NullObject
- }
- }
-
-So, now, there is a new FactoryComponent interface which extends the Component interface and it contains all the
-various parameters used when declaring a factory pid component. So the example above becomes:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- dm.add(createFactoryComponent()
- .setFactoryPid("my.factory.pid")
- .setPropagate(true)
- .setConfigType(MyConfig.class)
- .setInterface(MyService.class.getName(), null)
- .setImplementation(MyServiceImpl.class)
- .add(createServiceDependency().setService(LogService.class))); // NullObject
- }
- }
-
-You will find the javadoc of the new dm api [here](http://felix.apache.org/apidocs/dependencymanager/r15)
-
-### Support for multiple configuration types in callbacks
-
-The ConfigurationDependency and Factory components can now support updated callbacks with multiple configuration types,
-for example, the following Activator defines a factory component (using the enhanced api) and multiple configuration
-types can now be provided:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- Component factoryComponent = createFactoryComponent()
- .setFactoryPid(pid).
- .setConfigType(MyConfig1.class, MyConfig2.class)
- .setImplementation(MyComponent.class);
- dm.add(factoryComponent);
- }
- }
-
- public class MyComponent {
- void updated(MyConfig1 cnf1, MyConfig2 cnf2) { ... }
- }
-
-Moreover, you can define a Dictionary parameter as the first argument in the updated callback, because sometimes,
-it's useful to be injected with the raw dictionary configuration, as well as with the configuration types.
-Example:
-
- :::java
- public class MyComponent {
- void updated(Dictionary<String, Object> rawConfig, MyConfig1 cnf1, MyConfig2 cnf2) { ... }
- }
-
-so, the new signatures for the updated callbacks are now the following (for both ConfigurationDependency and Factory Component):
-
- :::java
- updated(Dictionary cnf)
- updated(Component comp, Dictionary cnf)
- updated(Component comp, Property interfaces ...)
- updated(Property interfaces ...)
- updated(Dictionary cnf, Property interfaces ...)
- updated(Component comp, Dictionary cnf, Property interfaces ...)
-
-## Annotations enhancements and changes
-
-Essentially, the following enhancements and modifications have been done regarding annotations:
-
-- added support for new user defined property type annotations (similar to OSGI R7).
-- annotations using standard r7 @ComponentPropertyType are also supported. Indeed, not only declarative service is using this annotation, other r7 apis like jaxrs whiteboard are also defining some annotations that are themselves annotated with @ComponentPropertyType; so it is important to support this annotation (The dm annotation plugin has been enhanced by reusing some part of the ds annotation scanner from bndlib, which is full of reusable useful code which has been applied to dm (sca [...]
-- Allow ServiceDependency to auto detect the service type when the annotation is applied on a collection class field
-- removed FactoryComponentAdapterService (some attributes have been added in the Component annotation in order to declare factory pid components with the @Component annotation)
-- removed some old annotations / attributes. The attributes and annotations related to metatype have been removed since you can now use the standard metatype annotations. if users need to old version, then they can simply use the previous 4.2.1 from old dm annotation api. Notice that the dm runtime is compatible with old and new annotations version, so you can use latest dm annotation runtime and old annotation api.
-- removed "dereference" attribute in ServiceDependencyAnnotation, because we can now infer if the service dependency callbacks accepts a ServiceReference or a ServiceObjects parameter
-- propagated configuration dependencies are now taking precedence over component service properties, meaning that a component is defined with some service properties, then the service properties which are also found from the propagated configuration will be overriden (by the configuration properties)
-- Since some incompatible changes have been made, the major version of the annotation bundle has been bumped to 5.0.0.
-
-Please check new [dependency manager annotations doc](http://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.html)
-
-### Not backward compatible annotation changes
-
-The following has been removed in the annotation api:
-
-- removed FactoryConfigurationAdapterService annotation, which was too verbose. when you need to define some factory pid component, just reuse the @Component annotation and declare the new factoryPid/propagate/updated attributes that have been added in the @Component annotation
-- Removed PropertyMetadata annotation: it was related to metatypes, but as of today, osgi metatypes can be defined using standard metatype annotations. No need to support this anymore.
-- Removed ResourceAdapterService and ResourceDependency annotations because it was needed to depend on some classes from the dependency manager API. The DM Api should be used directly.
-- Removed the following attributes from the Component annotation: -- FACTORY_NAME -- FACTORY_INSTANCE -- factorySet -- factoryMethod These attributes were used to be able to create component instances multiple times. Now, simply use factoryPid Component attribute and use standard Configuration Admin in order to instantiate multiple instances of a given service (using factory configuration).
-- Removed PropertyMetaData annotation, which was related to osgi metatype. Simply use standard metatype annotation.
-- propagated configuration dependencies are now taking precedence over component service properties, meaning that a component is defined with some service properties, then the service properties which are also found from the propagated configuration will be overriden (by the configuration properties)
-
-## Usage of Java 9/10/11
-
-When using Java 9 / 10 / 11, then you can't use fluent service properties anymore with dm-lambda,
-because in these new jdk versions, the "-parameters" option does not generate lambda parameters
-metadata anymore. So, the following example won't work **using jdk 9/10/11**
-(but still works using Java 8):
-
- :::java
- component(comp -> comp.impl(Foo.class).provides(FooService.class, property -> "service property value"));
-
-With Java 9/10/11, use this instead:
-
- :::java
- component(comp -> comp.impl(Foo.class).provides(FooService.class, "property", "service property value"));
-
-The fluent service properties using lambda expression maybe removed in future DM version if a solution is not found to make it working with Java 9/10/11
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext
deleted file mode 100644
index c6fa07d..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext
+++ /dev/null
@@ -1,68 +0,0 @@
-Title: Dependency Manager - What's new in version 4?
-
-Even though the focus for this version is to completely redo the internals, we also added a few new features to the code. The most important one is the new thread model, described directly below. Apart from that we also added a few smaller features, enumerated below that.
-
-## New thread model
-
-DependencyManager 4 has been significantly reworked to improve support for concurrency. The following principles form the basis of the new concurrency model in DM4.
-
- * All external events that influence the state of dependencies are recorded and given to the serial executor of the component. We record whatever data comes in, so when the actual job is run by the serial executor, we still have access to the original data without having to access other sources whose state might have changed since.
- * The serial executor of a component will execute a job immediately if it is being called by the thread that is already executing jobs.
- * If the serial executor of a component had not yet started a job, it will queue and start it on the current thread.
- * If the serial executor gets invoked from a different thread than the one currently executing jobs, the job will be put at the end of the queue. As mentioned before, any data associated with the event will also be recorded so it is available when the job executes.
- * State in the component and dependency can only be modified via the serial executor thread. This means we don't need explicit synchronization anywhere.
-
-DependencyManager 4 now also supports parallel execution of component wiring.
-
-Added support for parallelism: To allow components to be started and handled in parallel, you can now register in the OSGi service registry a ComponentExecutorFactory service that is used to get an Executor for the management of all components dependencies/lifecycle callbacks. See javadoc from the org.apache.felix.dm.ComponentExecutorFactory interface for more information.
-
-You can also take a look at the the org.apache.felix.dependencymanager.samples project, which is registering a ComponentExecutorFactory from org.apache.felix.dependencymanager.samples.tpool bundle.
-
-See also the following property in the org.apache.felix.dependencymanager.samples/bnd.bnd
-
- org.apache.felix.dependencymanager.parallel=\
- '!org.apache.felix.dependencymanager.samples.tpool, *',\
-
-Here, all components will be handled by Executors provided by the ComponentExecutorFactory, except those having a package starting with "org.apache.felix.dependencymanager.samples.tpool" (because the threadpool is itself defined using the Dependency Manager API).
-
-You will find a full description of the new thread model in the [Reference](../reference/thread-model.html) section.
-
-## New features
-
-In addition, some new features have been implemented in dependency manager:
-
-* Auto Config Iterable fields: AutoConfig dependencies can be applied on Iterable<Service> fields in order to be able to traverse currently injected services safely. The Iterable must be parameterized with the Service type.
-[see this sample code](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/api/SpellChecker.java) from the source distribution samples.
-
-* AutoConfig Map field: AutoConfig dependencies can be applied on a field with a Map<Service, Dictionary> type, allowing to traverse currently injected services safely, including service properties. The Map must be traversed using the Map.Entry iterator.
-See the *ServiceDependency.setAutConfig(boolean autoConfig)* [javadoc](http://felix.apache.org/apidocs/dependencymanager/4.0.0/org/apache/felix/dm/ServiceDependency.html) for more more informations.
-
-* Inject Configuration on separate callback instance (FELIX-2707): Configuration can be injected on a separate callback instance, like a CompositionManager for example.
-See the [composite factory example](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/compositefactory/) example available from the source distribution.
-
-* Added *propagate* flag in service Adapters (FELIX-4600): you can now choose to propagate or not adaptee service properties.
-
-* "Top" command in the shell: a "top" command is now available from the shell and can be used to display all top components sorted by their init/start elapsed time.
-
-* The Annotations plugin can now automatically generate a Require-Capability header on the Dependency Manager Runtime bundle.
-Use "add-require-capability=true" option in the plugin declaration property to enable this new feature (see FELIX-4676):
-
- -plugin: org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin; add-require-capability=true
-
-* The Configuration Dependency annotation now supports a "name" attribute (FELIX-4777): allow to dynamically configure configuration pids from the @Init method.
-
-* Added a benchmark tool for dependency manager (not released, only available from the [trunk](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.benchmark/).
-
-* The Annotations "Factory Sets" are deprecated (FELIX-4684): You can now use a DS-like ComponentFactory API by a nice api which is exported by the runtime bundle.
-See this [example](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/device/annot/DeviceAndParameterFactory.java) from the samples in the source distribution.
-
-* Since the R8 version, a new "`dm-lambda`" library has been introduced in the distribution. This new library allows to programmatically declare OSGi components using a new style based on java8 lambda expressions and other goodies like method references.
-
-* Since the R8 version, you can now provide "configuration types". Configuration types are a new feature that allows you to specify an interface that is implemented by DM and such interface is then injected to your configuration callback instead of an actual configuration dictionary.
-
-# Sample code
-
-The source distribution includes many sample codes which can be run directly under Eclipse and BndTools. The samples are available in the
-org.apache.felix.dependencymanager.samples/ module.
-Some of the samples require that you configure some pids or factory pids from Web Console, which can be accessed using *http://localhost:8080/system/console/configMgr* URL.
-Please consult org.apache.felix.dependencymanager.samples/README.samples for up to date instructions on how to execute the various examples.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.mdtext
deleted file mode 100644
index 5276c3f..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.mdtext
+++ /dev/null
@@ -1,44 +0,0 @@
-Title: Dependency Manager - Adapter
-
-Adapters, like [aspects](component-aspect.html), are used to "extend" existing services, and can publish
-different services based on the existing one. An example would be implementing a management interface.
-
-An adapter will be applied to any service that matches the specified interface and filter.
-For each matching service an adapter will be created based on the adapter implementation class.
-The adapter will be registered with the specified interface and existing properties from the original
-service plus any extra properties you supply here. It will also inherit all dependencies, and if you declare
-the original service as a member it will be injected.
-
-To define an adapter component, you need to create an [AdapterComponent](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/AdapterComponent.html) component
-using the DependencyActivatorBase.createAdapterComponent() or the DependencyManager.createAdapterComponent() method.
-This interface extends the Component interface in order to add extra setters methods needed to define an adapter service component.
-
-## Usage example
-
-Here is a sample showing a HelloServlet adapter component which creates a servlet each time a HelloService is registered in the osgi service registry with the "foo=bar" service property.
-
- :::java
- public class Activator extends DependencyActivatorBase {
- &Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- Component adapterComponent = createAdapterComponent()
- .setAdaptee(HelloService.class, "(foo=bar)")
- .setInterface(HttpServlet.class.getName(), null)
- .setImplementation(HelloServlet.class);
- dm.add(adapterComponent);
- }
- }
-
- public interface HelloService {
- String sayHello();
- }
-
- public class HelloServlet extends HttpServlet {
- volatile HelloService adatpee; // injected
-
- void doGet(HttpServletRequest req, HttpServletResponse resp) {
- ...
- resp.getWriter().println(adaptee.sayHello());
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.mdtext
deleted file mode 100644
index 867050e..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.mdtext
+++ /dev/null
@@ -1,35 +0,0 @@
-Title: Dependency Manager - Aspect
-
-Aspects, as part of aspect oriented programming, can be used in a dynamic environment
-such as OSGi to "extend" existing services and add certain "capabilities" to them.
-Examples of these are adding a specific caching mechanism to a storage service or
-implementing logging. Aspects in OSGi can be applied to services and can be added and
-removed at runtime.
-
-To define an aspect component, you need to create an [AspectComponent](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/AspectComponent.html) component
-using the DependencyActivatorBase.createAspectComponent() or the DependencyManager.createAspectComponent() method.
-This interface extends the Component interface in order to add extra setters methods needed to define an aspect service component.
-
-
-Usage example:
-
-In this example, a "DatabaseCache" aspect service is used to add caching functionality
-to an existing Database service. Here is the DatabaseCache aspect service will sit
-between any Database service consumer and the original Database service:
-
- :::java
- interface Database {
- String get(String key);
- }
-
- public class Activator extends DependencyActivatorBase {
- &Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- Component aspectComponent = createAspectComponent()
- .setAspect(Database.class, null, 10)
- .setImplementation(DatabaseCache.class)
- .add(createServiceDependency().setService(LogService.class).setRequired(false));
- dm.add(aspectComponent);
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.mdtext
deleted file mode 100644
index 9e5ac28..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.mdtext
+++ /dev/null
@@ -1,35 +0,0 @@
-Title: Dependency Manager - Bundle Adapter
-
-Bundle adapters are similar to AdapterService, but instead of adapting a
-service, they adapt a bundle with a certain set of states (STARTED|INSTALLED|...),
-and provide a service on top of it.
-
-The bundle adapter will be applied to any bundle that matches the specified
-bundle state mask and filter conditions, which may match some of the bundle
-OSGi manifest headers. For each matching bundle an adapter will be created
-based on the adapter implementation class. The adapter will be registered
-with the specified interface and with service properties found from the
-original bundle OSGi manifest headers plus any extra properties you supply
-here. If you declare the original bundle as a member it will be injected.
-
-To define a bundle adapter component, you need to create a [BundleComponent](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/BundleComponent.html) component
-using the DependencyActivatorBase.createBundleComponent() or the DependencyManager.createBundleComponent() method.
-
-This interface extends the Component interface in order to add extra setters methods needed to define a bundle adapter service component.
-
-
-## Example usage
-
-In the following example, a "VideoPlayer" Service is registered into the OSGi registry each time an active bundle containing a "Video-Path" manifest header is detected:
-
- :::java
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- Component c = dm.createBundleComponent()
- .setBundleFilter(Bundle.ACTIVE, "(Video-Path=*)")
- .setInterface(VideoPlayer.class.getName(), new Hashtable() {{ put("foo", "bar"); }})
- .setImplementation(VideoPlayerImpl.class);
- dm.add(c);
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.mdtext
deleted file mode 100644
index f633e80..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.mdtext
+++ /dev/null
@@ -1,44 +0,0 @@
-Title: Dependency Manager - Factory Configuration Adapter Service
-
-A factory configuration adapter service creates an adapter for each matching configuration in
-Configuration Admin. For each new factory configuration matching the factoryPid, an adapter will be
-created based on the adapter implementation class. The adapter will be registered with the specified
-interface and with the specified adapter service properties. Depending on the propagate parameter, every
-public factory configuration properties (which don't start with ".") will be propagated along with the
-adapter service properties. It will also inherit all dependencies.
-
-To define an adapter component, you need to create an [FactoryComponent](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/FactoryComponent.html) component
-using the DependencyActivatorBase.createFactoryComponent() or the DependencyManager.createFactoryComponent() method.
-The FactoryComponent interface extends the Component interface in order to add extra setters methods needed to define a factory configuration adapter service component.
-
-
-Example usage:
-
-Here is a sample showing a "MyComponent" component, which can be instantiated multiple times using a factory configuration:
-
- :::java
- public interface MyConfig {
- int getPort();
- String getAddress();
- }
-
- public class MyComponent implements MyService {
- void updated(MyConfig cnf) {
- int port = cnf.getPort();
- String addr = cnf.getAddress();
- ...
- }
- }
-
- public class Activator extends DependencyActivatorBase {
- &Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- Component factoryComponent = createFactoryComponent()
- .setFactoryPid("my.factory.pid")
- .setInterface(MySevice.class.getName(), null)
- .setImplementation(MyComponent.class)
- .setConfigType(MyConfig.class);
- dm.add(factoryComponent);
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.mdtext
deleted file mode 100644
index fbbcd1c..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.mdtext
+++ /dev/null
@@ -1,114 +0,0 @@
-Title: Dependency Manager - Resource Adapter
-
-Resource adapters work just like adapters, but instead of working with services, they work with resources.
-Resources, represented as a URL, are an abstraction introduced to provide a generic way of dealing with
-"blobs" and can be resources inside a bundle, filesystem or some kind of data store.
-
-A resource adapter will be applied to any resource that matches the specified filter condition.
-For each matching resource an adapter will be created based on the adapter implementation class.
-The adapter will be registered with the specified interface and existing properties from the original
-resource plus any extra properties you supply here. It will also inherit all dependencies,
-and if you declare the original service as a member it will be injected.
-
-To define a resource adapter, you first need to create a [ResourceComponent](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/ResourceComponent.html)
-component using the DependencyActivatorBase.createResourceComponent() or the DependencyManager.createResourceComponent() method.
-
-The ResourceComponent extends the [Component](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/Component.html) and provides some additional
-setter methods related to resource adapters.
-
-
-Usage Example:
-
-Here, the "VideoPlayer" service provides a video service on top of any movie
-resources, with service properties "host"/"port"/"protocol"/"path" extracted
-from the resource URL. There will be one VideoPlayerImpl instantiated and started for each
-available URL:
-
- :::java
- public class VideoPlayerImpl implements VideoPlayer {
- // Injected by reflection
- volatile URL resource;
-
- void play() {} // play video referenced by this.resource
- void stop() {} // stop playing the video
- void transcode() {} // ...
- }
-
- public class Activator extends DependencyManagerActivator {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- Component c = manager.createResourceComponent()
- .setResourceFilter("(&(path=/videos/*.mkv)(host=localhost))")
- .setPropate(true)
- .setInterface(VideoPlayer.class.getName(), new Hashtable() {{ put("foo", "bar"); }})
- .setImplementation(VideoPlayerImpl.class);
- dm.add(c);
- }
- }
-
-Notice that resource adapters are only supported with the DM API, not using annotations or using DM lambda.
-
-Now, here is the resource provider, which provides two URLS:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- // add resource provider
- URL[] resourceURLs = new URL[] {
- new URL("file://localhost/path/to/file1.txt"),
- new URL("file://localhost/path/to/file2.txt")
- };
-
- Component resourceProvider = createComponent()
- .setImplementation(new ResourceProvider(ctx, resourceURLs))
- .add(dm.createServiceDependency().setService(ResourceHandler.class).setCallbacks("add", "remove"));
- dm.add(resourceProvider);
- }
- }
-
- class ResourceProvider {
- final URL[] m_resources;
- final BundleContext m_context;
- final Map<ResourceHandler, Filter> m_handlers = new HashMap<>();
-
- ResourceProvider(BundleContext ctx, URL ... resources) {
- m_context = ctx;
- m_resources = resources;
- }
-
- public void add(ServiceReference<?> ref, ResourceHandler handler) {
- String filterString = (String) ref.getProperty("filter");
- Filter filter = null;
- if (filterString != null) {
- try {
- filter = m_context.createFilter(filterString);
- }
- catch (InvalidSyntaxException e) {
- return;
- }
- }
- for (int i = 0; i < m_resources.length; i++) {
- if (filter == null || filter.match((Dictionary<String, ?>) ResourceUtil.createProperties(m_resources[i]))) {
- synchronized (m_handlers) {
- m_handlers.put(handler, filter);
- }
- handler.added(m_resources[i]);
- }
- }
- }
-
- public void remove(ServiceReference<?> ref, ResourceHandler handler) {
- Filter filter;
- synchronized (m_handlers) {
- filter = (Filter) m_handlers.remove(handler);
- }
- if (filter != null) {
- for (int i = 0; i < m_resources.length; i++) {
- if (filter == null || filter.match((Dictionary<String, ?>) ResourceUtil.createProperties(m_resources[i]))) {
- handler.removed(m_resources[i]);
- }
- }
- }
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.mdtext
deleted file mode 100644
index a742373..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.mdtext
+++ /dev/null
@@ -1,63 +0,0 @@
-Title: Dependency Manager - Singleton Component
-
-Components are the main building blocks for OSGi applications. They can publish themselves as a service, and they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.
-
-## Example usage
-
-To define a singleton component, you can use the DependencyActivatorBase.createComponent() or
-the DependencyManager.createComponent() method,
-like in the following example which defines a "TranslationService" osgi service having one required
-dependency on the "LocalizationService" and one optional dependency on a "LogService".
-Dependencies are optional by default, unless you invoke the ServiceDependency.setRequired(boolean) method:
-
- :::java
- public class GoogleBasedTranslationService implements TranslationService {
- volatile LocalizationService m_localizationService; // injected by reflection
- volatile LogService m_log;
-
- ...
- }
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- Component c = createComponent()
- .setInterface(TranslationService.class.getName(), null)
- .setImplementation(GoogleBasedTranslationService.class)
- .add(createServiceDependency()
- .setService(LocalizationService.class, "(language=en)")
- .setRequired(true))
- .add(createServiceDependency()
- .setService(LogService.class)
- .setRequired(false)));
- dm.add(c);
- }
- }
-
-
-You can also inject dependencies using callbacks:
-
- :::java
- public class GoogleBasedTranslationService implements TranslationService {
- volatile LocalizationService m_localizationService; // injected by reflection
- void bind(LogService log {...}
- ...
- }
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- Component c = createComponent()
- .setInterface(TranslationService.class.getName(), null)
- .setImplementation(GoogleBasedTranslationService.class)
- .add(createServiceDependency()
- .setService(LocalizationService.class, "(language=en)")
- .setRequired(true))
- .add(createServiceDependency()
- .setService(LogService.class)
- .setCallbacks("bind", null /* no unbind method */)
- .setRequired(false)));
- dm.add(c);
- }
- }
-
-Notice that when you define an optional dependency without using callbacks, then a "NullObject" method is injected in the class field (by reflection) when the actual optional service is not available. In this case any invocation on the optional service won't do anything.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/components.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/components.mdtext
deleted file mode 100644
index cfe2d2b..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/components.mdtext
+++ /dev/null
@@ -1,227 +0,0 @@
-Title: Dependency Manager - Components
-
-Components are declared by the dependency manager and can be implemented by POJOs that contain no references to the OSGi framework whatsoever. Components are the main building blocks of your OSGi application. They have a life cycle, can register themselves as services and have zero or more dependencies.
-
-You can either use the Java API or the Java Annotations and this reference section describes both.
-
-## Types of Components
-
-There are different types of Dependency Manager components:
-
-* [*Component*](component-singleton.html): Components are the main building blocks for OSGi applications. They can publish themselves as a service, and/or they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.
-* [*Aspect Service*](component-aspect.html): A service that provides a non-functional aspect on top of an existing service. In aspect oriented programming, an aspect, or interceptor can sit between a client and another target service used by the client. An Aspect Service first tracks a target service and is created once the target service is detected. Then the Aspect Service is provided, but with a higher ranking, and the client is transparently updated with the aspect. Aspects can be c [...]
-* [*Adapter Service*](component-adapter.html): A Service that adapts another existing service into a new one. Like with aspects, sometimes you want to create adapters for certain services, which add certain behavior that results in the publication of (in this case) a different service. Adapters can dynamically be added and removed and allow you to keep your basic services implementations clean and simple, adding extra features on top of them in a modular way.
-* [*Bundle Adapter Service*](component-bundle-adapter.html): creates an OSGi service a service on top of a given bundle.
-* [*Resource Adapter Service*](component-resource-adapter.html): creates an OSGi service on top of a specific Resource.
-* [*Factory Configuration Adapter Service*](component-factory-configuration-adapter.html): creates an OSGi service from ConfigAdmin, using a factoryPid, and a ManagedServiceFactory.
-
-## Life cycle
-
-The dependency manager, as part of a bundle, shares the generic bundle life cycle explained in the OSGi specification. The life cycle of the dependency manager itself, and the components it manages, can be located inside the *active* state of the hosting bundle.
-
-Each component you define gets its own life cycle, which is explained in the state diagram below.
-
-<img src="./diagrams/statediagram.png" alt="State diagram" style="width: 430px"/>
-
-A component is associated with an instance. This instance can either be specified directly, or you can specify its class. If you do the latter, the actual instance will be created lazily.
-
-Changes in the state of the component will trigger the following life cycle methods:
-
-* `init`,
-* `start`,
-* `stop` and
-* `destroy`.
-
-The dependency manager will look for methods with these names and one of the following signatures in this order:
-
-* `(Component)`,
-* `()`.
-
-If you don't specify anything, the methods with these names will be invoked on the instance. By using `setCallbacks()` you can however change this behavior: You can change the names of the methods to look for. Any methods that are set to ` null ` will not be invoked at all. Another thing you can do is to specify a different instance to invoke these methods on. If you do that, you will usually want to use the first signature, which gives you a reference to the ` Component ` whose life cyc [...]
-
-Here is a descrition of the component states:
-
-* *Inactive state*: The Component is defined, but not enabled (not yet added to a
-DependencyManager object, or the bundle has been stopped).
-* *Waiting for required* state: The Component is enabled (has been added to a
-DependencyManager object) and the required dependencies declared in the Activator are
-tracked. The component remains in the current state until all required dependencies are
-available.
-* *Instantiated and waiting for required* state: All required dependencies declared
-in the Activator are available. The Component has been instantiated with required dependencies injected,
-and has been invoked in the *init* callback. Now, if some extra required dependencies have
-been dynamically added in the *init* callback, then the component remains in the
-current state until all extra required dependencies become available.
-* *Tracking optional*: All Required dependencies are injected (including the ones
-you dynamically added from the *init* method), the component *start* callback
-is called, the component service is registered in the OSGi registry, and finally the optional dependencies (with callbacks) are
-then tracked.
-
-
-## What happens during component instantiation ?
-
-1. The service is instantiated.
-2. The following special objects are injected through reflection on class fields, if
-they exist (but you can deactivate this behavior from the API):
- * BundleContext
- * ServiceRegistration
- * DependencyManager
- * Component
-3. *autoconfig* dependencies are injected through reflection on class fields, if they exist. If an *autoconfig*
-optional dependency is unavailable, a NullObject is then injected.
-4. Required dependency callbacks defined from the Activator are called.
-5. The component *init* method is called, and from that method you can then dynamically add
-more dependencies by using the Component parameter passed to the init method, or using
-a class field of *Component* type (which in this case has been injected during step 2).
-6. When all required dependencies (including dependencies dynamically added from the *init*
-method) are available, they are injected (using callbacks, or autoconfig).
-7. The component *start* callback is invoked.
-8. Optional dependencies (with callbacks) are then tracked.
-9. The component service(s) is then registered in the OSGi service registry
-
-When using Annotations, there are some specific behaviors:
-
-* The *@init* method may return a Map that contains filters in order to
-dynamically configure dependencies annotated with a *name* attribute, and the dependencies will
-then be injected after the *@init* method (exactly if you would have added the dependencies from the init method using the API).
-* The *@start* method may return a Map in order to dynamically add more service properties (if the component provides some services).
-* The component can be dynamically stopped or restarted using a special *@LifecycleController* annotation.
-
-## Interfaces and properties
-
-Components in the context of the dependency manager can be published as OSGi services under one or more interface names, plus optionally a set of properties. This is no different than a normal OSGi service. It's important to mention that you don't have to register a service. If you don't, you basically created a component that can do work and have dependencies and a managed life cycle.
-
-## Composition
-
-When implementing more complex components, you often find yourself using more than one
-instance. However, several of these instances might want to have dependencies injected.
-In such cases you need to tell the dependency manager which instances to consider.
-This has to be a fixed set of instances however.
-
-We now describe how to declare a service composition using the Api, and the Annotations:
-
-Example:
-
-When using the DependencyManager API, you can use the *Component.setComposition* method to declare a special callback in your component that
-returns the list of object that are part of the component, and all dependencies and lifecycle callbacks will be invoked
-on the objects returned by the method. Let's take an example, with a *ProviderImpl* top-level service implementation
-that is internally implemented using three Pojos: *ProviderImpl*, *ProviderParticipant1*, and
-*ProviderParticipant2*:
-
- :::java
- public class ProviderImpl implements Provider {
- private final ProviderParticipant1 m_participant1 = new ProviderParticipant1();
- private final ProviderParticipant2 m_participant2 = new ProviderParticipant2();
- private volatile LogService m_log; // injected
-
- Object[] getComposition() {
- return new Object[] { this, m_participant1, m_participant2 };
- }
-
- void start() {
- m_log.log(LogService.LOG_INFO, "ProviderImpl.start(): participants=" + m_participant1 + "," + m_participant2
- + ", conf=" + m_conf);
- }
- }
-
- public class ProviderParticipant1 {
- private volatile LogService m_log; // also injected since we are part of the composition
-
- void start() {
- m_log.log(LogService.LOG_INFO, "ProviderParticipant1.start()");
- }
- }
-
- public class ProviderParticipant2 {
- private volatile LogService m_log; // also injected since we are part of the composition
-
- void start() {
- m_log.log(LogService.LOG_INFO, "ProviderParticipant2.start()");
- }
- }
-
-And here is the Activator, which uses the *setComposition* method:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext ctx, DependencyManager m) throws Exception {
- m.add(createComponent()
- .setImplementation(ProviderImpl.class)
- .setComposition("getComposition")
- .add(createServiceDependency().setService(LogService.class).setRequired(true)));
- }
- }
-
-
-## Factories
-
-Out of the box, there already is support for lazy instantiation, meaning that the dependency manager can create component instances for you when their required dependencies are resolved. However, sometimes creating a single instance using a default constructor is not enough. In those cases, you can tell the dependency manager to delegate the creation process to a factory.
-
-Interestingly, you can also mix the usage of a Factory object and a Composition of objects returned by the Factory.
-The following is the same example as in the previous section (Composition), but using a Factory approach in order to instantiate a composition of objects:
-The "ProviderFactory" is first injected with a Configuration that can possibly be used to create
-and configure all the other objects that are part of the composition; each object will also be injected with
-the dependencies defined in the Activator.
-
- :::java
- public class ProviderFactory {
- private ProviderParticipant1 m_participant1;
- private ProviderParticipant2 m_participant2;
- private ProviderImpl m_providerImpl;
- private Dictionary<String, String> m_conf;
-
- public void updated(Dictionary<String, String> conf) throws Exception {
- // validate configuration and throw an exception if the properties are invalid
- m_conf = conf;
- }
-
- /**
- * Builds the composition of objects used to implement the "Provider" service.
- * The Configuration injected by Config Admin will be used to configure the components
- * @return The "main" object providing the "Provider" service.
- */
- Object create() {
- // Here, we can instantiate our object composition based on our injected configuration ...
-
- if ("true".equals(m_conf.get("some.parameter")) {
- m_participant1 = new ProviderParticipant1(); // depenencies and lifecycle callbacks will also be applied
- m_participant2 = new ProviderParticipant2(); // depenencies and lifecycle callbacks will also be applied
- } else {
- // Compose with some other objects ...
- m_participant1 = new ProviderParticipant3(); // depenencies and lifecycle callbacks will also be applied
- m_participant2 = new ProviderParticipant4(); // depenencies and lifecycle callbacks will also be applied
- }
-
- m_providerImpl = new ProviderImpl(m_participant1, m_participant2);
- return m_providerImpl; // Main object implementing the Provider service
- }
-
- /**
- * Returns the list of objects that are part of the composition for the Provider implementation.
- */
- Object[] getComposition() {
- return new Object[] { m_providerImpl, m_participant1, m_participant2 };
- }
- }
-
-
-And here is the Activator: notice the *setFactory* method that specifies the factory to use to create the implementation.
-Also pay attention to the *setComposition* method, which indicates the method to call in order to get all instances that
-are part of a composition and need dependencies injected:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext ctx, DependencyManager m) throws Exception {
- ProviderFactory factory = new ProviderFactory();
- m.add(createComponent()
- .setFactory(factory, "create") // factory.create() will return the implementation instance
- .setComposition(factory, "getComposition")
- .add(createConfigurationDependency()
- .setPid("some.pid")
- .setCallback(factory, "updated")) // will invoke "updated" on the factory instance
- .add(createServiceDependency().setService(LogService.class).setRequired(true)));
- }
- }
-
-You can refer to this [sample code](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/compositefactory/), which is part of the source distribution.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependencies.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependencies.mdtext
deleted file mode 100644
index 1f10d08..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependencies.mdtext
+++ /dev/null
@@ -1,32 +0,0 @@
-Title: Dependency Manager - Dependencies
-
-The dependency manager supports many different types of dependencies, all of which can be required or optional. A dependency can be added to one or more components and it is possible to add them dynamically (even from within the component itself if necessary, which allows for some really dynamic dependency configuration).
-
-## Injection
-
-One way to deal with dependencies is to have them injected into your component instances automatically. All you need to do is simply declare a field of the same type as your dependency, make the member volatile so any changes will become visible immediately and you're done. If a dependency is optional, a null object will be injected if the dependency is not available.
-
-Sometimes you need more control over injection, so optionally you can even specify the name of the field to inject into. This allows you to depend on different dependencies of the same type, or simply to prevent injection into more than one field.
-
-## Callbacks
-
-When keeping track of multiple instances of a dependency, or when you simply want something to happen whenever a dependency becomes (un)available or changes, you can define callbacks, like `added`, `changed` and `removed`. Optionally, you can provide the dependency manager with an instance to invoke these callback methods on. If you don't, they'll be invoked on the component instance.
-
-## Types of Dependencies
-
-Out of the box, several types of dependencies are supported:
-
-* [Service](dependency-service.html)
-* [Configuration](dependency-configuration.html)
-* [Bundle](dependency-bundle.html)
-* [Resource](dependency-resource.html)
-
-However, it's quite easy to add your own custom type of dependency too, as is described below.
-
-## Implementing Your Own Dependency
-
-All dependencies share a common API which you can implement yourself if you need a special type of dependency. Whilst not entirely trivial, this allows you to create your own types of dependencies. This can be useful for various scenarios where you want to have components that depend on things that are not services, bundles or configuration.
-
-An example implementation can be found in the samples available in the source distribution.
-In the org.apache.felix.dependencymanager.samples module, you can refer to src/org/apache/felix/dependencymanager/samples/customdep/README file,
-which describes a custom "PathDependency" that tracks files that are added or removed from /tmp/ directory.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.mdtext
deleted file mode 100644
index 66412d5..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.mdtext
+++ /dev/null
@@ -1,34 +0,0 @@
-Title: Dependency Manager - Bundle Dependency
-
-A bundle dependency allows you to depend on a bundle in a certain set of states, as indicated by a state mask.
-You can also use a filter condition that is matched against all manifest entries. Finally you can provide a
-reference to an existing bundle.
-
-To define a bundle dependency, you need to use the [BundleDependecy](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/BundleDependency.html) interface.
-This interface can be created using DependencyActivatorBase.createBundleDependency() or DependencyManager.createBundleDependency() methods;
-
-Here is an example of a component which tracks all ACTIVE bundles having a Service-Component header in the manifest:
-
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- Component scr = createComponent()
- .setImplementation(ScrRuntime.class)
- .add(createBundleDependency().setFilter("(Service-Component=*").setStateMask(Bundle.ACTIVE).setCallbacks("bind", "unbind"));
- }
- }
-
- public class ScrRuntime {
- void bind(Bundle bundle) {
- // load SCR descriptors from the starting bundle
- }
-
- void unbind(Bundle bundle) {
- // unload SCR descriptors from the starting bundle
- }
- }
-
-The dependency is optional by default, and will invoke the ScrRuntime.bind callback each time a bundle containing some Declarative Service component is started.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.mdtext
deleted file mode 100644
index f42cbf1..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.mdtext
+++ /dev/null
@@ -1,105 +0,0 @@
-Title: Dependency Manager - Configuration Dependency
-
-A configuration dependency is always required, and allows you to depend on the availability of a valid
-configuration for your component. Configuration dependency is required by default.
-
-To define a configuration dependency, you need to use the [ConfigurationDependency](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/ConfigurationDependency.html) interface.
-This interface can be created using DependencyActivatorBase.createConfigurationDependency() or DependencyManager.createConfigurationDependency() methods.
-
-
-The dependency injects by default the configuration in an "updated" callback which can accept the following parameters:
-
-- `updated(Dictionary)`
-- `updated(Component, Dictionary)`
-- `updated(<ConfigurationType>)`
-- `updated(Component, <ConfigurationType>)`
-
-If you only specify a pid, by default the callback method name is assumed to be "updated".
-
-Configuration types are a new feature that allows you to specify a Java interface that is implemented by DM and such interface is then injected to your callback instead of the actual Dictionary. Using such configuration interface provides a way for creating type-safe configurations from a actual Dictionary that is normally injected by Dependency Manager. The callback accepts in argument an interface that you have to provide, and DM will inject a proxy that converts method calls from your [...]
-As proxies are injected, no implementations of the desired configuration-type are necessary!
-
-The lookups performed are based on the name of the method called on the configuration type. The method names are "mangled" to the following form: [lower case letter] [any valid character]*. Method names starting with get or is (JavaBean convention) are stripped from these prefixes. For example: given a dictionary with the key "foo" can be accessed from a configuration-type using the following method names: foo(), getFoo() and isFoo().
-
-The return values supported are:
-
-- primitive types (or their object wrappers);
-- strings;
-- enums;
-- arrays of primitives/strings;
-- Collection types;
-- Map types;
-- Classes and interfaces.
-
-When an interface is returned, it is treated equally to a configuration type, that is, a proxy is returned.
-
-Arrays can be represented either as comma-separated values, optionally enclosed in square brackets. For example: `[ a, b, c ]` and `a, b,c` are both considered an array of length 3 with the values "a", "b" and "c". Alternatively, you can append the array index to the key in the dictionary to obtain the same: a dictionary with "arr.0" => "a", "arr.1" => "b", "arr.2" => "c" would result in the same array as the earlier examples.
-
-Maps can be represented as single string values similarly as arrays, each value consisting of both the key and value separated by a dot. Optionally, the value can be enclosed in curly brackets. Similar to array, you can use the same dot notation using the keys. For example, a dictionary with:
-
- map={key1.value1,key2.value2}
-
-and a dictionary with:
-
- map.key1=value1
- map.key2=value2
-
-result in the *same* map being returned. Instead of a map, you could also define an interface with the methods `getKey1()` and `getKey2()` and use that interface as return type instead of a Map.
-
-In case a lookup does not yield a value from the underlying map or dictionary, the following rules are applied:
-
-- primitive types yield their default value, as defined by the Java Specification;
-- string, Classes and enum values yield `null`;
-- for arrays, collections and maps, an *empty* array/collection/map is returned;
-- for other interface types that are treated as configuration type a Null-object is returned.
-
-Here is a component depends on a configuration:
-
- :::java
- public class ServiceImpl {
- void updated(Dictionary<String, Object> cnf) {
- if (cnf != null) {
- String addr = (String) cnf.get("address");
- int port = Integer.valueOf(cnf.get("port");
- ...
- }
- }
- }
-
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- dm.add(createComponent()
- .setImplementation(ServiceImpl.class)
- .add(createConfigurationDependency().setPid(ServiceImpl.class.getName()));
- }
- }
-
-Here is the same example, but a custom configuration type interface is used
-(by default, the FQDN of the configuration type is assumed to be the configuration pid):
-
- :::java
- public interface MyConfig {
- String getAddress();
- int getPort();
- }
-
- public class ServiceImpl {
- void modified(MyConfig cnf) {
- if (cnf != null) {
- String addr = cnf.getAddress();
- int port = cnf.getPort();
- ...
- }
- }
- }
-
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- dm.add(createComponent()
- .setImplementation(ServiceImpl.class)
- .add(createConfigurationDependency().setCallback("modified", MyConfig.class);
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-resource.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-resource.mdtext
deleted file mode 100644
index dec0c2e..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-resource.mdtext
+++ /dev/null
@@ -1,93 +0,0 @@
-Title: Dependency Manager - Resource Dependency
-
-A resource dependency allows you to depend on a resource. A resource is a URL and you can use a filter
-condition based on protocol, host, port, path and URL.
-
-To define a resource dependency, you need to use the [ResourceDependecy](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/ResourceDependency.html) interface.
-This interface can be created using DependencyActivatorBase.createResourceDependency() or DependencyManager.createResourceDependency() methods;
-
-Here is an example where a bundle activation declares a VideoPlayer component which depends on a resource URL.
-The component uses an optional dependency callback, which is invoked each time an URL is registered.
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- Component videoPlayer = createComponent()
- .setImplementation(VideoPlayer.class)
- .add(createResourceDependency().setFilter("(&(path=/path/to/*.txt)(host=localhost))").setCallbacks("play", null));
- dm.add(videoPlayer);
- }
- }
-
- public class VideoPlayer {
- void play(URL url) {
- System.out.println("play: " + url);
-
- }
- }
-
-
-And here is a component which registers some URL resources:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext ctx, DependencyManager dm) throws Exception {
- // add resource provider
- URL[] resourceURLs = new URL[] {
- new URL("file://localhost/path/to/file1.txt"),
- new URL("file://localhost/path/to/file2.txt")
- };
-
- Component resourceProvider = createComponent()
- .setImplementation(new ResourceProvider(ctx, resourceURLs))
- .add(dm.createServiceDependency().setService(ResourceHandler.class).setCallbacks("add", "remove"));
- dm.add(resourceProvider);
- }
- }
-
- class ResourceProvider {
- final URL[] m_resources;
- final BundleContext m_context;
- final Map<ResourceHandler, Filter> m_handlers = new HashMap<>();
-
- ResourceProvider(BundleContext ctx, URL ... resources) {
- m_context = ctx;
- m_resources = resources;
- }
-
- public void add(ServiceReference<?> ref, ResourceHandler handler) {
- String filterString = (String) ref.getProperty("filter");
- Filter filter = null;
- if (filterString != null) {
- try {
- filter = m_context.createFilter(filterString);
- }
- catch (InvalidSyntaxException e) {
- return;
- }
- }
- for (int i = 0; i < m_resources.length; i++) {
- if (filter == null || filter.match((Dictionary<String, ?>) ResourceUtil.createProperties(m_resources[i]))) {
- synchronized (m_handlers) {
- m_handlers.put(handler, filter);
- }
- handler.added(m_resources[i]);
- }
- }
- }
-
- public void remove(ServiceReference<?> ref, ResourceHandler handler) {
- Filter filter;
- synchronized (m_handlers) {
- filter = (Filter) m_handlers.remove(handler);
- }
- if (filter != null) {
- for (int i = 0; i < m_resources.length; i++) {
- if (filter == null || filter.match((Dictionary<String, ?>) ResourceUtil.createProperties(m_resources[i]))) {
- handler.removed(m_resources[i]);
- }
- }
- }
- }
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.mdtext
deleted file mode 100644
index 015725d..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.mdtext
+++ /dev/null
@@ -1,35 +0,0 @@
-Title: Dependency Manager - Service Dependency
-
-A service dependency allows you to depend on a service, either by type or by using an additional filter
-condition. You can even depend on an existing service directly by providing a reference to it.
-
-To define a service dependency, you need to use the [ServiceDependecy](http://felix.apache.org/apidocs/dependencymanager/r13/org/apache/felix/dm/ServiceDependency.html) interface.
-This interface can be created using DependencyActivatorBase.createServiceDependency() or DependencyManager.createServiceDependency() methods;
-
-Service dependencies can be injected on fields or using callbacks, can be required or optional, and NullObject pattern is supported for optional dependencies applied on class fields.
-
-Example:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createComponent()
- .setImplementation(DataGenerator.class)
- .add(createServiceDependency()
- .setService(Store.class)
- .setRequired(true)
- )
- );
- }
- }
-
- public class DataGenerator {
- private volatile Store m_store;
-
- public void generate() {
- for (int i = 0; i < 10; i++) {
- m_store.put("#" + i, "value_" + i);
- }
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.mdtext
deleted file mode 100644
index 7b30e7e..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.mdtext
+++ /dev/null
@@ -1,1611 +0,0 @@
-Title: Dependency Manager Annotations
-
-[TOC]
-
-This section presents an overview and a reference guide of the capabilities and usage of the
-DependencyManager annotations.
-
-# Overview
-
-Instead of writing Activators which extends the DependencyActivatorBase class, service
-components can also be annotated using the annotations provided by the
-*org.apache.felix.dependencymanager.annotation* bundle. Annotations are not reflectively
-parsed at runtime; but we use a BND plugin which scans annotations at compilation phase
-and generates a compact json metadata file in the bundle's META-INF/dependencymanager
-subdirectory. This has the following benefits: JVM startup speed is not affected, and class files
-are not parsed when the framework is starting. Moreover, since the annotations are not retained
-by the VM at runtime, it is not necessary to load the annotation API bundle at runtime.
-
-At runtime, the metadata generated during the compilation phase are processed by a
-specific DependencyManager Runtime bundle, which is in charge of managing the service
-component lifecycle and dependencies. This Runtime bundle actually uses the
-DependencyManager programmatic API in order to manage the annotated components.
-Annotated components can then be inspected with the DependencyManager Gogo shell, as it is
-the case with DM components declared through the programmatic DM API.
-
-To register a service, your can annotate your class with a *@Component* annotation, and
-an instance of your class will be registered under all directly implemented interfaces
-into the OSGi registry. You can however take control on the interfaces to be exposed, and
-in this case, you can use the *provides* attribute, which takes a list of classes to
-expose from the registry:
-
- :::java
- @Component
- class WebServiceImpl implements WebService {
- ...
- }
-
-To illustrate this, we are now introducing a SpellChecker application which provides a
-Felix "spellcheck" Gogo shell command. Our "spellcheck" command is implemented by the
-SpellChecker component which accepts a string as parameter. This string is then checked for proper existence.
-To do the checking, the SpellChecker class has a required/multiple (1..N) dependency over
-every available DictionaryService services. Such DictionaryService represents a real
-dictionary for a given language (it has a *lang* service property).
-
-Now we have introduced the background, let's define our SpellChecker component:
-
- :::java
- @Component(provides=SpellChecker.class)
- @Property(name=CommandProcessor.COMMAND_SCOPE, value="dmsample.annotation")
- @Property(name=CommandProcessor.COMMAND_FUNCTION, values={"spellcheck"})
- public class SpellChecker {
- // --- Gogo Shell command
-
- public void spellcheck(String word) {
- // Check the proper existence of the word parameter, using injected DictionaryService instances
- // ...
- }
- }
-
-
-In the code above, you see that the SpellCheck is annotated with the *@Component*
-annotation. Gogo runtime does not required shell commands to implement a specific
-interface. Commands just have to register some Pojos in the OSGi registry, but the only
-thing required is to provide the Pojos with two service properties ( COMMAND_SCOPE, and
-COMMAND_FUNCTION) which will be used by the Gogo runtime when instropecting the Pojo
-for invoking the proper functions.
-
-So, coming back to the sample code, the SpellChecker class registers itself into the OSGi registry, using the *provides* attribute, which just refer to our SpellChecker class, and the two mandatory Gogo service properties are also specified using the *@Property* annotation. It is not shown here, but service properties can also be provided dynamically from a method that can return a Map, and annotated with the *@Start* lifecycle callback, but we will see this feature in a another section.
-
-Our SpellChecker component can expose itself as a Gogo shell command, but before being
-registered into the OSGi registry, we also need to be injected with two dependencies:
-one required dependency (at minimum) on a DictionaryService, and another optional one on
-a LogService. First, let's look at the DictionaryService, which is a simple interface:
-
- :::java
- public interface DictionaryService {
- /**
- * Check for the existence of a word.
- * @param word the word to be checked.
- * @return true if the word is in the dictionary, false otherwise.
- */
- public boolean checkWord(String word);
- }
-
-And here is our previous SpellChecker component, augmented with two new ServiceDependency
-annotations:
-
- :::java
- @Component(provides=SpellChecker.class)
- @Property(name=CommandProcessor.COMMAND_SCOPE, value="dmsample.annotation")
- @Property(name=CommandProcessor.COMMAND_FUNCTION, values={"spellcheck"})
- public class SpellChecker {
- @ServiceDependency(required = false)
- private LogService m_log;
-
- private final CopyOnWriteArrayList<DictionaryService> m_dictionaries = new CopyOnWriteArrayList<DictionaryService>();
-
- @ServiceDependency(removed = "removeDictionary")
- protected void addDictionary(DictionaryService dictionary) {
- m_dictionaries.add(dictionary);
- }
-
- protected void removeDictionary(DictionaryService dictionary) {
- m_dictionaries.remove(dictionary);
- }
-
- // --- Gogo Shell command
-
- public void spellcheck(String word) {
- m_log.log(LogService.LOG_INFO, "Checking spelling of word \"" + word
- + "\" using the following dictionaries: " + m_dictionaries);
-
- for (DictionaryService dictionary : m_dictionaries) {
- if (dictionary.checkWord(word)) {
- System.out.println("word " + word + " is correct");
- return;
- }
- }
- System.err.println("word " + word + " is incorrect");
- }
- }
-
-There are many things to describe in the code above:
-
-First, we define an optional dependency on the LogService, by defining a
-*@ServiceDependency(required=false)* annotation on our m_logService field: This
-means that our component will be provided into the OSGi registry even if there
-is no available LogService, and in this case, a NullObject will be injected in
-our class field;
-This will avoid to check for nullability, when using the m_logService field.
-All optional dependencies applied on class fields are injected with a
-NullObject (when not available).
-The NullObject can be invoked and will do nothing. For a lot of cases that is
-good enough to handle optional dependencies. But when you really want to check
-if an optional service is there or not, then you have to apply the optional
-dependency on a callback method, which will be called when the optional
-service is available.
-
-Next comes the dependency on the DictionaryService. Here, we use a *ServiceDependency*
-annotation, but this time we apply it on a method (*add/removeDictionary*). There is no
-need to specify the "*required=true*" flag because it is the default value. Notice that
-this behavior is different from the API, where service dependencies are optional by default
-. We use a callback method, because we just need to register all available
-DictionaryService services in our dictionary list, which is used when checking word
-existence. This list is a copy on write list because the dependency may be injected at
-any time, possibly from another thread. So, using a copy on write list avoid us to use
-synchronized methods.
-
-Notice that the @ServiceDependency could also have been applied on the m_dictionaries field,
-and in this case, no need to define callback methods (addDictionary/removeDictionary).
-So, in this case the dictionaries will be automatically added in the collection field.
-
-# Component types
-
-The following types of components are supported when using annotations:
-
-- Component: Allows to define osgi services
-- Aspect Service: A service that provides a non-functional aspect on top of an existing service
-- Service Adapter: A Service that adapts another existing service into a new one
-- Bundle Adapter: Allows to provide an osgi service on top of an existing bundle
-
-## Component
-
-Components are the main building blocks for OSGi applications and can be annotated with @Component. They can publish themselves as a
-service, and/or they can have dependencies. These dependencies will influence their life cycle as component
-will only be activated when all required dependencies are available. To define a component, you can use the @Component annotation
-(see [@Component javadoc](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Component.html)).
-
-Applying this annotation on top of a java class let it be a service component. All directly implemented
-interfaces will be registered in the osgi registry, but you can control the provided interfaces using the `provides` attribute.
-Sometimes, your class implements some interfaces, but yet you don't want them to be registered, in this case, declaring `provides={}` ensures that
-no services will be registered. However, the component can still define service dependencies and it will be invoked in the @Start callback when all required
-dependencies are satisfied.
-
-The default public constructor is used to initialize the component, but you can also specify a static method that will be used to instantiate the component (using the
-`factoryMethod` attribute). This allows for example to create the component instance using a dynamic proxy.
-
-Here is a sample showing a Hello component:
-
- :::java
- /**
- * This component will be activated once the bundle is started.
- */
- @Component
- class Hello implements HelloService {
- @Start
- void start() {
- // Our component is starting and is about to be registered in the OSGi registry as a HelloService service.
- }
- }
-
-By default, components are created automatically, when the Components' bundle is started and when the Component
-dependencies are satisfied. But certain software patterns require the creation of Services on demand.
-For example, a Service could represent an application that can be launched multiple times and each Service
-instance can then quit independently. Such a pattern requires a factory that creates the instances, and
-`Managed Service Factories` can be used to implement this use case. it is based on OSGi Configuration Admin service.
-Using the configuration admin service, you can create multiple dictionaries , and for each one a new service will be created
-The mapping between the dictionaries and the services are done using a so called `PID`.
-So, if you need your component to be instantiated multiple times, you first need to define the PID using the `factoryPid` attribute.
-
-Example:
-
- :::java
- /**
- * All component instances will be created/updated/removed by the "HelloFactory" component
- */
- @Component(factoryPid="my.factory.pid")
- class Hello implements HelloService {
- void updated(Dictionary conf) {
- // Configure or reconfigure our component. The conf is provided by the factory,
- }
-
- @Start
- void start() {
- // Our component is starting and is about to be registered in the OSGi registry as a Hello service.
- }
- }
-
- /**
- * This class will instantiate some Hello component instances
- */
- @Component
- class HelloFactory {
- @ServiceDependency
- void bind(ConfigurationAdmin cm) {
- // instantiate a first instance of Hello component
- Configuration c1 = cm.createFactoryConfiguration("my.factory.pid", "?");
- Hashtable props = new Hashtable();
- props.put("key", "value1");
- c1.update(props);
-
- // instantiate another instance of Hello component
- Configuration c2 = cm.createFactoryConfiguration("my.factory.pid", "?");
- props = new Hashtable();
- props.put("key", "value2");
- c2.update(props);
-
- // destroy the two instances of X component
- c1.delete();
- c2.delete();
- }
- }
-
-In the above example, the PID is "my.factory.pid", and the HelloFactory component uses the `ConfigurationAdmin`
-service in order to create some factory configurations using the "my.factory.pid". This pattern allows to
-programatically create/update/remove multiple instances of the same Component.
-
-By default, the HelloComponent can define an `updated(Dictionary)` callback: it will be called when the component
-is created, but you can override the method which receives the configuraiton using the `updated` attribute.
-
-When you want to propagate the configuration to the provided service properties, you can also define the `propagate` attribute.
-Notice that when you propagate the configuration to the provided service properties, then the the configuration takes precedence
-over the service properties, meaning that if a given property is declared in the service properties, then it
-will be overriden if the configation also contains the property.
-
-## Aspect component
-
-An aspect service in DM provides a non-functional aspect on top of an existing service.
-In aspect oriented programming, an aspect, or interceptor can sit between a client and another target service
-used by the client. An Aspect Service first tracks a target service and is created once the target service is
-detected. Then the Aspect Service is provided, but with a higher ranking, and the client is transparently
-updated with the aspect. Aspects can be chained and may apply to the same target service (and in this case,
-the ranking of the Aspect service is used to chain aspects in the proper order).
-
-You can define an aspect service using the @AspectService annotation (see
-[@AspectService javadoc](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/AspectService.html)).
-
-Usage example:
-
-Here, the `Aspect` class is registered into the OSGI registry each time an
-InterceptedService is found from the registry.
-
- :::java
- @AspectService(ranking=10))
- class Aspect implements InterceptedService {
- // The service we are intercepting (injected by reflection)
- volatile InterceptedService intercepted;
-
- public void doWork() {
- intercepted.doWork();
- }
- }
-
-The Aspect class intercepts the original InterceptedService, and decorates its "doWork()" method.
-This aspect uses a rank with value "10", meaning that it will intercept some other eventual aspects with
-lower ranks. It will also inherit of the original InterceptedService service properties.
-
-## Adapter component
-
-An adapter service component (@AdapterService) adapts another existing service into a new one. Like with aspects,
-sometimes you want to create adapters for certain services, which add certain behavior that results in
-the publication of (in this case) a different service. Adapters can dynamically be added and removed
-and allow you to keep your basic services implementations clean and simple, adding extra features on top of
-them in a modular way.
-
-You can define an aspect service using the @AdapterService annotation (see
-[@AdapterService javadoc](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/AdapterService.html)).
-
-Here, the AdapterService is registered into the OSGI registry each time an AdapteeService is
-found from the registry.
-
- :::java
- interface AdapteeService {
- void method1();
- void method2();
- }
-
- @Component
- @Property(name="p1", value="v1")
- class Adaptee implements AdapteeService {
- ...
- }
-
- interface AdapterService {
- void doWork();
- }
-
- @AdapterService(adapteeService = AdapteeService.class)
- @Property(name="p2", value="v2")
- class AdapterImpl implements AdapterService {
- // The service we are adapting (injected by reflection)
- volatile AdapteeService adaptee;
-
- public void doWork() {
- adaptee.method1();
- adaptee.method2();
- }
- }
-
-The AdapterImpl class adapts the AdapteeService to the AdapterService.
-The AdapterService will also have the following service property: p1=v1, p2=v2 :
-
-## Bundle adapter component
-
-Bundle adapters are similar to Adapter Components, but instead of adapting a service, they adapt a bundle
-with a certain set of states (STARTED|INSTALLED|...), and provide a service on top of it.
-
-You can define a bundle adapter service using the @BundleAdapterService annotation (see
-[@BundleAdapterService javadoc](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/BundleAdapterService.html)).
-
-The bundle adapter will be applied to any bundle that matches the specified bundle state mask and
-filter conditions, which may match some of the bundle OSGi manifest headers. For each matching bundle an
-adapter will be created based on the adapter implementation class. The adapter will be registered with the
-specified interface and with service properties found from the original bundle OSGi manifest headers plus any
-extra properties you supply here. If you declare the original bundle as a member it will be injected.
-
-In the following example, a "VideoPlayer" Service is registered into the OSGi registry each time an active bundle containing a "Video-Path" manifest header is detected:
-
- :::java
- @BundleAdapterService(filter = "(Video-Path=*)", stateMask = Bundle.ACTIVE, propagate=true)
- public class VideoPlayerImpl implements VideoPlayer {
- volatile Bundle bundle; // Injected by reflection
-
- void play() {
- URL mpegFile = bundle.getEntry(bundle.getHeaders().get("Video-Path"));
- // play the video provided by the bundle ...
- }
- }
-
-# Component lifecycle
-
-A component has a lifecycle that controls when it is started or stopped.
-A bundle must be started before the DM Runtime can process its components.
-When the bundle is started, the DM Runtime then parses a specific
-*DependencyManager-Component* manifest header, which points to a list of descriptors
-describing all annotated components. Such descriptors are actually generated at
-compilation time, and annotation are not reflectively parsed at runtime.
-Only the descriptor is used to process the components.
-
-For each component, the DM Runtime first ensures that all dependencies are satisfied before
-activating it. Likewise, the component is deactivated when some of the required dependencies
-are not available anymore or when the bundle is stopped. Unless the bundle is stopped, components may be deactivated
-and reactivated, depending on the departure and arrival of required dependencies. The
-manager which is in charge of maintaining the state of components is implemented in the
-DM Runtime bundle (org.apache.felix.dm.runtime bundle).
-
-
-
-So, during activation, the component goes through a number of states, where each transition
-includes the invocation of the following lifecycle method callbacks on the service implementation:
-
-- [@Init](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Init.html):
-this callback is invoked after all required dependencies have been injected. In this method, you can
-yet add more dynamic dependencies using the DM API, or you can possibly configure other dependencies filter and required flags
-(see [Dynamic dependency configuration](## Dynamic dependency configuration)).
-
-- [@Start](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Start.html):
-this callback is invoked after all required dependencies added in the @Init method have been injected.
-
-- [@Registered](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Registered.html):
-this callback is invoked after the service component is registered (if the component provides a service).
-The callback can takes as argument a ServiceRegistration parameter.
-
-- [@Stop](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Stop.html):
-this method is called when a required dependency is lost or when the bundle is stopped
-
-- [@Destoy](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Destroy.html) annotations:
-the component is about to be destroyed
-
-## Component activation
-
-Activating a component consists of the following steps:
-
-1) Wait for all required dependencies to be available. When all required dependencies are
-available:
-
-- instantiate the component
-- inject all required dependencies (on class fields using reflection, or by invoking callback methods)
-- inject all optional dependencies defined on class fields, possibly with a *NullObject* if the
-dependency is not available.
-- call the component init method (annotated with *@Init*, see (see
-[@Init javadoc](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Init.html)).).
-In the init method, you are yet allowed to add some additional dependencies using the Dependency
-Manager API or DM Lambda). Alternatively, you can also configure some dependencies dynamically
-(explained later, in [Dynamic Dependency Configuration](##dynamic-dependency-configuration).
-
-2) Wait for extra required dependencies optionally configured from the init() method. When all extra
-required dependencies are available:
-
-- inject extra required dependencies (if some were defined in init() method).
-- invoke the start method annotated with [@Start annotation](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Start.html).
-The start method may return a Map<String, Object> that will
-be appended to the provided service properties (the the component provides a service).
-- start tracking optional dependencies applied on method callbacks (invoke optional dependency callbacks).
-Notice that NullObject pattern is not applied to optional callback dependencies.
-In other words, if the dependency is not there, your callback won't be invoked at all.
-If you need the NullObject pattern, then apply optional dependencies on class fields, not on
-callback methods.
-- register the OSGi service, if the component provides one.
-- invoke the method annotatated with [@Registered annotation](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Registered.html).
-The method, if declared, takes as argument a `ServiceRegistration` which corresponds to the registered service.
-
-
-
-## Component deactivation
-
-Deactivating a component consists of the following steps:
-
-If the bundle is stopped or if some required dependencies are unavailable, or if the component
-has declared a factoryPid and the factory configuration has been delete, then:
-
-- Unbind optional dependencies (defined on callback methods).
-Notice that any optional dependency unavailability does not trigger the component deactivation;
-the *removed* callbacks are just invoked, if declared in the annotation.
-- Invoke the stop method (annotated wit *@Stop*), and unregister some OSGi services
-(if the components provides some services).
-- invoke destroy method (annotated with *@Destroy*).
-- invoke *removed* callbacks for required dependencies, if any.
-
-## Example
-
-The following example shows a basic component, which uses the @Start annotation:
-
- :::java
- /**
- * A Component Using lifecyce callbacks
- */
- @Component
- class X implements Y {
- @ServiceDependency
- void bindOtherService(OtherService other) {
- // Will be injected before we are started (because it's a required dependency).
- }
-
- @Start
- void start() {
- // All required dependencies are injected: initialize our component.
- }
- }
-
-The following example shows a component, which returns some service properties from its start method,
-and the component also defines the @Registered annotation in order to get the actual ServiceRegistration
-for the provided service:
-
- :::java
- /**
- * A Component Using lifecyce callbacks
- */
- @Component
- @Property(name="p1", value="v1") // service properties
- class X implements Y {
- @ServiceDependency
- void bindOtherService(OtherService other) {
- // Will be injected before we are started (because it's a required dependency).
- }
-
- @Start
- Map<String, Object> start() {
- // All required dependencies are injected: initialize our component.
- // Once we return, our Y service will be published in the OSGi registry, using the following
- // service properties appended to the ones specified on top of the class with the @Property
- // annotation (notice that returning a map is optional and our start() method could be
- // declared as void).
- Map<String, Object> additionalServiceProperties = new HashMap<>();
- additionalServiceProperties.put("p2", "v2");
- return additionalServiceProperties;
- }
-
- @Registered
- void registered(ServiceRegistration registration) {
- // once our service is registered, we can obtainer here the corresponding ServiceRegistration ...
- }
- }
-
-## Lifecycle control
-
-As explained in the *Component Activation* section, a component which provides a service
-is automatically registered into the OSGi registry, after the @Start method returns.
-But it is sometimes required to control when the service is really started/published or
-unpublished/stopped.
-
-This can be done using the [@LifecycleController](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/LifecycleController.html) annotation.
-This annotation injects a Runnable object that can be invoked when you want to trigger your service
-startup and publication. The @LifecycleController is like a required dependency and is injected before
-the @Init method is called.
-
-For instance, imagine that your component publishes an OSGi service, but before, it needs to
-register into a DHT (Distributed Hash Table), whose API is asynchronous: that is:
-the DHT API will callback you once you are inserted into a node in the DHT.
-In this case, what you would like to do is to publish your OSGi service, but only after you are
-inserted into the DHT (when the DHT callbacks you) ...
-Such a case is supported using the @LifecyceController annotation, which gives you
-full control of when your component is *started/published* and *unpublished/stopped*.
-
-Let's illustrate this use case with a concrete example: First here is the DHT asynchronous API:
-
- :::java
- /**
- * This is an element which can be inserted into the distributed hash table.
- */
- public interface DHTElement {
- void inserted(); // callback used to notify that the element is inserted into the DHT
- }
-
- /**
- * This is the DHTService, which registers a DHTElement asynchronously.
- */
- public interface DHTService {
- void insert(DHTElement element); // will callback element.inserted() later, once registered into the DHT.
- }
-
-Next, here is our service, which uses the @LifecycleController in order to take control of when the service is published into the OSGi registry:
-
- :::java
- @Component(provides={MyService.class})
- public class MyServiceImpl implements MyService, DHTElement {
- @ServiceDependency
- DHTService m_dht;
-
- @LifecycleController
- Runnable m_start; // will fire component startup, once invoked.
-
- @Init
- void init() {
- m_dht.insert(this); // asynchronous, will callback once registered into the DHT
- }
-
- public void inserted() {
- // We are inserted into the DHT: we can now trigger our component startup.
- // We just invoke the runnable injected by our @LifecycleController annotation, which will trigger our
- // service publication (we'll be called in our @Start method before)
- m_start.run();
- }
-
- @Start
- void start() {
- // method called only once we invoke our trigger Runnable (see inserted method).
- // Our Service will be published once this method returns.
- }
- }
-
-Same example as above, using java8 method reference:
-
- :::java
- @Component
- public class MyServiceImpl implements MyService {
- @ServiceDependency
- DHTService m_dht;
-
- @LifecycleController
- Runnable m_start; // will fire component startup, once invoked.
-
- @Init
- void init() {
- m_dht.insert(m_start::run); // asynchronous, will callback m_registered.run() once registered into the DHT
- }
-
- @Start
- void start() {
- // method called after the m_dht service has called the m_registered.run() method.
- }
- }
-
-
-# Dependencies
-
-## Service dependencies
-
-Service Dependencies can be defined using the [@ServiceDependency](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/ServiceDependency.html) annotation.
-
-Dependencies can either be required or optional. Required dependencies need to be resolved before
-the service can even become active. Optional dependencies can appear and disappear while the service
-is active. **Please notice that, unlike with the DM API, service dependencies are required by default.**
-
-### Field injection
-
-The dependency manager will automatically fill in any references
-to required @ServiceDependency that are applied on attributes. The same
-goes for optional dependencies if they are available. If not, those will
-be implemented by a null object [NULLOBJ]. In short, this allows
-you to simply use these interfaces as if they were always available.
-A good example of this is the LogService. If it’s available, we want
-to use it for logging. If not, we want to simply ignore log messages.
-Normally, you’d need to check a reference to this service for null
-before you can use it. By using a null object, this is not necessary
-anymore.
-
-When the @ServiceDependency annotation is defined on a class field, the following field
-types are supported:
-
-- a field having the same type as the dependency. If the field may be accessed by any thread,
-then the field should be declared volatile, in order to ensure visibility when the field is auto
-injected concurrently.
-
-- a field which is assignable to an `Iterable<T>` where T must match the dependency type.
-In this case, an Iterable will be injected by DependencyManager before the start callback is called.
-The Iterable field may then be traversed to inspect the currently available dependency services.
-The Iterable can possibly be set to a final value so you can choose the Iterable implementation
-of your choice (for example, a CopyOnWrite ArrayList, or a ConcurrentLinkedQueue).
-
-- a Map<K,V> where K must match the dependency type and V must exactly equals Dictionary class. In this case, a ConcurrentHashMap will be injected by DependencyManager before the start callback is called. The Map may then be consulted to lookup current available dependency services, including the dependency service properties (the map key holds the dependency services, and the map value holds the dependency service properties). The Map field may be set to a final value so you can choose [...]
-
-This is an example where you inject a `Dependency` service on a class field:
-
- :::java
- @Component
- class MyComponent {
- @ServiceDependency
- volatile Dependency m_dependency;
- }
-
-
-Another example, were we inject multiple dependencies to an Iterable field
-
- :::java
- @Component
- class MyComponent {
- @ServiceDependency
- final Iterable<Dependency> dependencies = new CopyOnWriteArrayList<>();
- }
-
-And next, we inject multiple dependencies to a Map field, allowing to inspect service
-dependency properties (the keys hold the services, and the values hold the associated service
-properties):
-
- :::java
- @Component
- class MyComponent {
- @ServiceDependency
- final Map<MyDependency, Dictionary<String, Object>> dependencies = new ConcurrentHashMap<>;
- }
-
-Optional dependencies applied on class fields will inject a NullObject when the dependency is unavailable. This allows you to avoid to check if the optional
-dependency is not null using a "if" statement, and invoking the NullObject will result in a No Op method call. When the optional dependency type is not an interface, then NullObject won't work because
-internally, the NullObject is implemented using a dynamic proxy. In this case you can use the
-ServiceDependency.defaultImpl attribute which allows to specify a default implementation when the optional dependency is unavailable.
-
-Example:
-
- :::java
- @Component
- public class MyComponent {
- @ServiceDependency(required=false, defaultImpl=MyDefaultImpl.class)
- volatile Dependency m_dependency;
- }
-
-in the above example, the MyDefaultImpl class will be injected on the m_dependency class field in case the dependency is unavailable.
-
-### Callback injection
-
-Optionally, a service can define callbacks for each dependency. These
-callbacks are invoked whenever a new dependency is discovered or
-an existing one is disappearing. They allow you to track these dependencies.
-This can be very useful if you, for example, want to implement the white board pattern.
-
-The callbacks allows to get notified when a service is added, and support the following signatures:
-
- (Component comp, ServiceReference ref, Service service)
- (Component comp, ServiceReference ref, Object service)
- (Component comp, ServiceReference ref)
- (Component comp, Service service)
- (Component comp, Object service)
- (Component comp)
- (Component comp, Map properties, Service service)
- (ServiceReference ref, Service service)
- (ServiceReference ref, Object service)
- (ServiceReference ref)
- (Service service)
- (Service service, Map properties)
- (Map properties, Service, service)
- (Service service, Dictionary properties)
- (Dictionary properties, Service service)
- (Object service)
- (ServiceReference<T> service)
- (ServiceObjects<T> service)
-
-Example:
-
- :::java
- @Component
- class MyComponent {
- @ServiceDependency
- void bind(MyDependency dependency) {}
- }
-
-Same example as before, but the callback signatures includes service properties:
-
- :::java
- @Component
- class MyComponent {
- @ServiceDependency
- void bind(MyDependency dependency, Map<String, Object> serviceProperties) {}
- }
-
-Same example as before, but this time we track service change:
-
- :::java
- @Component
- class MyComponent {
- @ServiceDependency(change="updated")
- void bind(MyDependency dependency, Map<String, Object> serviceProperties) {}
-
- void updated(MyDependency dependency, Map<String, Object> serviceProperties) {}
- }
-
-Example where you track added/changed/removed service:
-
- :::java
- @Component
- class MyComponent {
- @ServiceDependency(change="updated", remove="unbind")
- void bind(MyDependency dependency, Map<String, Object> serviceProperties) {}
-
- void updated(MyDependency dependency, Map<String, Object> serviceProperties) {}
-
- void unbind(MyDependency dependency, Map<String, Object> serviceProperties) {}
- }
-
-### Whiteboard pattern
-
-Required service dependency are always invoked before the start (@Start) callback is
-invoked.
-However, Optional dependency **callbacks** are always invoked **after** the start (@Start) callbacks.
-This allows to easily implement the whiteboard patter, because you can first make sure your component
-is fully initialized before it can start to track other services (whiteboard pattern).
-
-For example, assume you write a `TaskExecutor` component which tracks `Task` services. So, each time
-a Task is found from the registry, then you want to schedule the Task in an Executor, and you also
-want to maitain statistics on executed tasks. So, your `TaskExecutor` depends on two required services:
-an `Executor` service (used to schedule the tasks), as well as a `TaskMetrics` service which is used to
-maintain Task execution statistics. So what you need is to make sure your are injected with the TaskMetrics
-and the Executor service before you can actually start to handle Tasks.
-To do so, simply define two required dependencies on the `Executor` and the `TasksMetrics`, and
-define an optional dependency on the Task services. This will ensure that the Tasks callbacks are
-invoked after your component is started:
-
- :::java
- interface Task extends Runnable {
- }
-
- @Component
- TaskExecutor {
- @ServiceDependency
- volatile Executor m_executor;
-
- @ServiceDependency
- volatile TaskMetrics m_taskMetrics;
-
- @Start
- void start() {
- // at this point, all required dependencies have been injected and we can now start to track
- // the Task services
- }
-
- @ServiceDependency(required=false)
- void bind(Task task) {
- m_executor.execute(task);
- m_taskMetrics.taskScheduled();
- }
- }
-
-### Tracking any services matching a given filter
-
-Sometimes, you may want to be injected with any service objects matching a given filter,
-without any additional filter on the class service interface.
-In this case, you need to use the `service=ServiceDependency.ANY` attribute
-
-
-For example:
-
- :::java
- import org.apache.felix.dm.annotation.ServiceDependency;
- import org.apache.felix.dm.annotation.api.ServiceDependency.Any;
-
- @Component
- public class MyService {
- @ServiceDependency(service=Any.class, filter="(property=true)")
- void bind(Object allServices) {
- }
- }
-
-### Service dependency properties propagation
-
-It is possible to propagate the dependency service properties, using the ServiceDependency.propagate attribute.
-When the service dependency properties are propagated, they will be appended to the component service properties,
-but won't override them (the component service properties takes precedence over the propagated service dependencies).
-
-Example:
-
- :::java
- @Component
- @Properties(name="p1", value="v1")
- public class MyServiceImpl implements MyService {
- @ServiceDependency(propagate=true)
- void bind(OtherService other) {
- }
- }
-
-The service above will be registered with the p1=v1 service properties, as well as with any service properties which come from the Service Dependency.
-
-### defining a swap aspect callback
-
-When you define a service dependency, it is possible to define a swap callback in case an original service dependency is replaced by an aspect, and you
-then want to be called back at the time the service dependency is replaced.
-
-Example:
-
- :::java
- @Component
- public class MyServiceImpl {
- @ServiceDependency(swap="swap")
- void bind(OtherService other) {
- }
-
- void swap(OtherService old, OtherService replace) {
- }
- }
-
-So, if an aspect service is registered for the OtherService service, then your swap method will be called so you can take the service replacement into account.
-
-The swap callback supports the following signatures:
-
- :::java
- (Service old, Service replace)
- (Object old, Object replace)
- (ServiceReference old, Service old, ServiceReference replace, Service replace)
- (ServiceReference old, Object old, ServiceReference replace, Object replace)
- (Component comp, Service old, Service replace)
- (Component comp, Object old, Object replace)
- (Component comp, ServiceReference old, Service old, ServiceReference replace, Service replace)
- (Component comp, ServiceReference old, Object old, ServiceReference replace, Object replace)
- (ServiceReference old, ServiceReference replace)
- (Component comp, ServiceReference old, ServiceReference replace)
- (ServiceObjects old, ServiceObjects replace)
- (Component comp, ServiceObjects old, ServiceObjects replace)
-
-### Blocking a service invocation while it is updating.
-
-When an injected service dependency is an interface, it is possible to block the service invocation
-while it is being updated.
-Only useful for required stateless dependencies that can be replaced transparently.
-A Dynamic Proxy is used to wrap the actual service dependency (which must be an interface).
-When the dependency goes away, an attempt is made to replace it with another one which satisfies
-the service dependency criteria. If no service replacement is available, then any method invocation
-(through the dynamic proxy) will block during a configurable timeout. On timeout, an unchecked
-IllegalStateException exception is raised (but the service is not deactivated).
-
-To use this feature, you need to specify a `timeout` attribute like this:
-
- :::java
- @Component
- class MyServer implements Runnable {
- @ServiceDependency(timeout=15000)
- MyDependency dependency;.
-
- @Start
- void start() {
- (new Thread(this)).start();
- }
-
- public void run() {
- try {
- dependency.doWork();
- } catch (IllegalStateException e) {
- t.printStackTrace();
- }
- }
- }
-
-Notice that the changed/removed callbacks are not used when the timeout parameter is greater
-than -1. -1 means no timeout at all (default). 0 means that invocation on a missing service will
-fail immediately. A positive number represents the max timeout in millis to wait for the service
-availability.
-
-## Configuration dependencies
-
-A configuration dependency is required by default, and allows you to depend on
-the availability of a valid configuration for your component. Use the
-[@ConfigurationDependency annotation](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/ConfigurationDependency.html) to define a configuration dependency.
-
-This dependency requires the OSGi Configuration Admin Service.
-Configuration Dependency callback is always invoked before any service dependency
-callbacks, and before init/start callbacks.
-The annotation can be applied on a callback method which accepts the following
-parameters:
-
- callback(Dictionary)
- callback(Component, Dictionary)
- callback(Component, Configuration ... configTypes) // type safe configuration interface(s)
- callback(Configuration ... configTypes) // type safe configuration interface(s)
- callback(Dictionary, Configuration ... configTypes) // type safe configuration interfaces(s)
- callback(Component, Dictionary, Configuration ... configTypes) // type safe configuration interfaces(s)
-
-Configuration can be simply injected in the form of dictionaries, or in the form of type-safe configuration
-interfaces.
-
-the annotation attributes are the following:
-
-* pid: Returns the pid for a given service (by default, the pid is the service class name).
-* propagate: Returns true if the configuration properties must be published along with the service. The configuration properties takes precedence over the component service properties.
-* pidClass: Returns the pid from a class name.
-* required: Sets the required flag which determines if this configuration dependency is required or not.
-* name: used to dynamically configure the pid from an @Init method.
-
-### Type safe configuration
-
-Configuration types allows you to specify a Java interface that is implemented by
-DM and such interface is then injected to your callback instead of the actual Dictionary.
-Using such configuration interface provides a way for creating type-safe configurations
-from a actual Dictionary that is normally injected by Dependency Manager.
-The callback accepts in argument an interface that you have to provide, and
-DM will inject a proxy that converts method calls from your configuration-type
-to lookups in the actual map or dictionary. The results of these lookups are then
-converted to the expected return type of the invoked configuration method.
-As proxies are injected, no implementations of the desired configuration-type are
-necessary!
-
-The lookups performed are based on the name of the method called on the configuration
-type. The method names are "mangled" to the following form:
-
- [lower case letter] [any valid character]*.
-
-Method names starting with get or is (JavaBean convention) are stripped from these
-prefixes. For example: given a dictionary with the key "foo" can be accessed from a
-configuration-type using the following method names:
-
- foo(), getFoo() and isFoo().
-
-The return values supported are:
-
-* primitive types (or their object wrappers);
-* strings;
-* enums;
-* arrays of primitives/strings;
-* Collection types;
-* Map types;
-* Classes and interfaces.
-
-When an interface is returned, it is treated equally to a configuration type, that is,
-a proxy is returned.
-
-Arrays can be represented either as comma-separated values, optionally enclosed in
-square brackets. For example: [ a, b, c ] and a, b,c are both considered an array of
-length 3 with the values "a", "b" and "c".
-Alternatively, you can append the array index to the key in the dictionary to obtain
-the same: a dictionary with "arr.0" => "a", "arr.1" => "b", "arr.2" => "c" would result
-in the same array as the earlier examples.
-
-Maps can be represented as single string values similarly as arrays, each value
-consisting of both the key and value separated by a dot. Optionally, the value can be
-enclosed in curly brackets. Similar to array, you can use the same dot notation using
-the keys. For example, a dictionary with:
-
- map={key1.value1, key2.value2}
-
-and a dictionary with:
-
- map.key1=value1
- map.key2=value2
-
-result in the same map being returned.
-Instead of a map, you could also define an interface with the methods getKey1()
-and getKey2() and use that interface as return type instead of a Map.
-
-In case a lookup does not yield a value from the underlying map or dictionary,
-the following rules are applied:
-
-* primitive types yield their default value, as defined by the Java Specification;
-* string, Classes and enum values yield null;
-* for arrays, collections and maps, an empty array/collection/map is returned;
-* for other interface types that are treated as configuration type a Null-object is returned.
-
-### Examples
-
-In the following example, the "Printer" component depends on a configuration with
-"org.apache.felix.sample.Printer" PID:
-
- :::java
- package org.apache.felix.sample;
-
- @Component
- public class Printer {
- @ConfigurationDependency
- void updated(Dictionary config) {
- // load printer ip/port from the provided dictionary.
- }
- }
-
-Here is the same example using a type safe configuration:
-
- :::java
- package sample;
-
- public interface PrinterConfiguration {
- String ipAddress();
- int portNumber();
- }
-
- @Component
- public class Printer {
- @ConfigurationDependency // Will use pid "sample.PrinterConfiguration"
- void updated(PrinterConfiguration cnf) {
- if (cnf != null) {
- // load configuration from the provided dictionary, or throw an exception of any configuration error.
- String ip = cnf.ipAddress();
- int port = cnf.portNumber();
- ...
- }
- }
- }
-
-## Bundle dependency
-
-A bundle dependency allows you to depend on a bundle in a certain set of states
-(INSTALLED\|RESOLVED\|STARTED\|...), as indicated by a state mask.
-You can also use a filter condition that is matched against all manifest entries.
-When applied on a class field, optional unavailable dependencies are injected with a
-NullObject.
-
-Use the [@BundleDependency annotation](http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/BundleDependency.html) to define a bundle dependency.
-
-Attributes:
-
-* changed: Returns the callback method to be invoked when the service have changed.
-* removed: Returns the callback method to invoke when the service is lost.
-* required: Returns whether the dependency is required or not.
-* filter: Returns the filter dependency
-* stateMask: Returns the bundle state mask (Bundle.INSTALLED \| Bundle.ACTIVE etc ...).
-* propagate: Specifies if the manifest headers from the bundle should be propagated to the service properties.
-* name: The name used when dynamically configuring this dependency from the init method.
-Specifying this attribute allows to dynamically configure the dependency filter and
-required flag from the Service's init method.
-All unnamed dependencies will be injected before the init() method;
-so from the init() method, you can then pick up whatever information needed from
-already injected (unnamed) dependencies, and configure dynamically your named
-dependencies, which will then be calculated once the init() method returns.
-
-
-In the following example, the "SCR" Component allows to track all bundles containing a
-specific "Service-Component" OSGi header, in order to load and manage all
-Declarative Service components specified in the SCR xml documents referenced by the
-header:
-
- :::java
- @Component
- public class SCR {
- @BundleDependency(required = false,
- removed = "unloadServiceComponents",
- filter = "(Service-Component=*)"
- stateMask = Bundle.ACTIVE)
- void loadServiceComponents(Bundle b) {
- String descriptorPaths = (String) b.getHeaders().get("Service-Component");
- // load all service component specified in the XML descriptorPaths files ...
- }
-
- void unloadServiceComponents(Bundle b) {
- // unload all service component we loaded from our "loadServiceComponents" method.
- }
- }
-
-## Dynamic dependency configuration
-
-We have seen that a component may declare some dependencies and is started when all required
-dependencies are available. But there are some cases when you may need to define some dependencies
-filters (and required flag) dynamically, possibly from data picked up from other dependencies.
-
-So, all this is possible using *named* dependencies: When you assign a name to a dependency;
-for instance *@ServiceDependency(name="foo")*, then this has an impact on how the dependency
-is handled.
-Indeed, all named dependencies are calculated *after* the @Init method returns.
-So from your @Init method, you can then configure your named dependencies, using data provided
-by already injected dependencies.
-
-To do so, your @Init method is allowed to return a Map containing the filters and required flags
-for each named dependencies.
-For a given named dependency, the corresponding filter and required flag must be stored in
-the Map, using the "*filter*" and "*required*" keys, prefixed with the name of the dependency.
-
-For instance, if you define a Dependency like this:
-
- :::java
- @ServiceDependency(name="foo")
- FooService fooService;
-
-Then you can return this map from your @Init method:
-
- :::java
- @Init
- Map init() {
- Map m = new HashMap();
- m.put("foo.filter", "(foo=bar)");
- m.put("foo.required", "false");
- return m;
- }
-
-So, after the init method returns, the map will be used to configure the dependency named "foo", which will then be evaluated.
-And once the dependency is available, then it will be injected and your @Start callback will be invoked.
-
-Usage example of a dynamic dependency:
-
-In this sample, the "PersistenceImpl" component dynamically configures the "storage"
-dependency from the "init" method. The dependency "required" flag and filter string are derived
-from an xml configuration that is already injected before the init method.
-
- :::java
- @Component
- public class PersistenceImpl implements Persistence {
- // Injected before init.
- @ConfigurationDependency
- void updated(Dictionary conf) {
- if (conf != null) {
- _xmlConfiguration = parseXmlConfiguration(conf.get("xmlConfiguration"));
- }
- }
-
- // Parsed xml configuration, where we'll get our storage service filter and required dependency flag.
- XmlConfiguration _xmlConfiguration;
-
- // Dynamically configure the dependency declared with a "storage" name.
- @Init
- Map<String, String> init() {
- Map<String, String> props = new HashMap<>();
- props.put("storage.required", Boolean.toString(_xmlConfiguration.isStorageRequired()))
- props.put("storage.filter", "(type=" + _xmlConfiguration.getStorageType() + ")");
- return props;
- }
-
- // Injected after init (dependency filter is defined dynamically from our init method).
- @ServiceDependency(name="storage")
- Storage storage;
-
- // All dependencies injected, including dynamic dependencies defined from init method.
- @Start
- void start() {
- log.log(LogService.LOG_WARNING, "start");
- }
-
- @Override
- void store(String key, String value) {
- storage.store(key, value);
- }
- }
-
-
-Notice that you can also add dynamic dependencies using the Dependency Manager API, or using DM-Lambda.
-In this case, no need to define service dependencies with annotations. Here is the same example as above,
-but this time, the dependency on the Storage service is defined from the init method using the DM API:
-
- :::java
- @Component
- public class PersistenceImpl implements Persistence {
- // Injected before init.
- @ConfigurationDependency
- void updated(Dictionary conf) {
- if (conf != null) {
- _xmlConfiguration = parseXmlConfiguration(conf.get("xmlConfiguration"));
- }
- }
-
- // Parsed xml configuration, where we'll get our storage service filter and required dependency flag.
- XmlConfiguration _xmlConfiguration;
-
- // Dynamically configure the dependency declared with a "storage" name.
- @Init
- void init(org.apache.felix.dm.Comppnent myComponent) {
- boolean required = _xmlConfiguration.isStorageRequired();
- String filter = _xmlConfiguration.getStorageType();
- DependencyManager dm = myComponent.getDependencyManager();
- myComponent.add(dm.createServiceDependency().setService(Storage.class, filter).setRequired(required));
- }
-
- // Injected after init, later, when the dependency added from the init() method is satisfied
- volatile Storage storage;
-
- // All dependencies injected, including dynamic dependencies defined from init method.
- @Start
- void start() {
- log.log(LogService.LOG_WARNING, "start");
- }
-
- @Override
- void store(String key, String value) {
- storage.store(key, value);
- }
- }
-
-Same example as above, but this time the dependency is added from the init method using the
-Dependency Manager Lambda API:
-
- :::java
- import static org.apache.felix.dm.lambda.DependencyManagerActivator.component;
-
- @Component
- public class PersistenceImpl implements Persistence {
- // Injected before init.
- @ConfigurationDependency
- void updated(Dictionary conf) {
- if (conf != null) {
- _xmlConfiguration = parseXmlConfiguration(conf.get("xmlConfiguration"));
- }
- }
-
- // Parsed xml configuration, where we'll get our storage service filter and required dependency flag.
- XmlConfiguration _xmlConfiguration;
-
- // Dynamically configure the dependency declared with a "storage" name.
- @Init
- void init(org.apache.felix.dm.Comppnent myComponent) {
- boolean required = _xmlConfiguration.isStorageRequired();
- String filter = _xmlConfiguration.getStorageType();
- component(myComponent, comp -> comp.withSvc(Storage.class, filter, required));
- }
-
- // Injected after init, later, when the dependency added from the init() method is satisfied
- volatile Storage storage;
-
- // All dependencies injected, including dynamic dependencies defined from init method.
- @Start
- void start() {
- log.log(LogService.LOG_WARNING, "start");
- }
-
- @Override
- void store(String key, String value) {
- storage.store(key, value);
- }
- }
-
-# Component Composition
-
-When implementing more complex services, you often find yourself using more than one instance for a given service.
-However, several of these instances might want to have dependencies injected. In such cases you need to tell the
-dependency manager which instances to consider. Within a Component (or an Aspect/Adapter), you can annotate a method
-with the @Composition annotation. This method is meant to return such composition of service instances, and the objects
-will be considered as part of the service implementation. So, all dependencies, as well as lifecycle annotations
-(@Init, @Start, @Stop, @Destroy) will be applied on every objects returned by the method annotated with the @Composition annotation.
-
-The following example illustrates a composition of two object instances, which are part of the implementation of a *MyService* service:
-
- :::java
- /**
- * Main implementation for the MyService Service
- */
- @Component
- public class MyServiceImpl implements MyService {
- // This object instance is also used to implement the service.
- private Helper helper = new Helper();
-
- // MyServiceImpl, and Helper objects are part of the composition
- @Composition
- Object[] getComposition() {
- return new Object[] { this, helper };
- }
-
- // This dependency is also applied to the Helper
- @ServiceDependency
- Dependency dep;
-
- // Same thing for this dependency
- @ServiceDependency
- void bind(Dependency2 dep2) {}
-
- // Lifecycle callbacks also applied on the Helper ...
-
- @Start
- void start() {}
-
- }
-
- public class Helper {
- // Also injected, since we are part of the composition
- volatile Dependency dep;
-
- // But since we are not interested by the Dependency2, we don't have to declare the bind(Dependency2) method ...
-
- // We only specify the start lifecycle callback because we need to return some extra service properties which will be published
- // along with the provided service ...
-
- Map start() {
- Map extraServiceProperties = new HashMap();
- extraServiceProperties.add("foo", "bar");
- return extraServiceProperties;
- }
- }
-
-Here, MyServiceImpl is the main component implementation, but is composed of the Helper object
-instance. So all Dependencies defined in MyServiceImpl
-will be also injected to the Helper (if the Helper declares the fields or methods).
-The Helper may also define annotated lifecycle callbacks (optionally).
-
-# Service scopes
-
-By default service providers are registered once in the osgi registry, and all service consumers share the same service provider instance.
-Now, you can control the scope of the provided services: From the provider side, a "scope" parameter
-is available for all types of DM components and allows to define the scope of the registered service.
-
-The `scope` attribute has three enum values: SINGLETON, BUNDLE, PROTOTYPE
-
-- SINGLETON: it's as before: your registered service is a singleton, meaning that the service must be
-instantiated and registered once, and all using services will share the same service instance of your component.
-- BUNDLE: the service will be registered as a ServiceFactory, meaning an instance of the component must be
-created for each bundle using the service.
-- PROTOTYPE: the service will be registered as a PrototypeServiceFactory, meaning the service is registered as
-a prototype scope service and an instance of the component must be created for each distinct service requester.
-
-Scoped Services are supported by all kind of DM service components:
-
-- Component
-- Aspect Service
-- Adapter Service
-- Bundle Adapter service
-
-When a consumer requests a service (using ServiceDependency), then DM will automatically
-dereference the service like this:
-
-- if the service has a SERVICE_SCOPE service property matching SCOPE_PROTOTYPE, the DM will
-internally derefence the service using the ServiceObject API: so, the consumer will get its own copy
-of the requested service instance.
-- else, DM will internally dereference the service, as before.
-When defining scoped component implementation, you can optionally define two special class fields
-in order to get injected with the client Bundle requesting the service, and the ServiceRegisgtration
-Object. Just use @Inject annotations in order to get injected with the client
-Bundle or the ServiceRegistration. You can also define a constructor which takes as argument the
-client bundle as well as the service registration.
-
-Example:
-
-Here is a MyService component with PROTOTYPE scope, each requester will get its own copy of
-MyService instance, and the MyServiceImpl.start() method will be called for each instance:
-
-
- :::java
- import org.apache.felix.dm.annotation.api.Component;
- import org.apache.felix.dm.annotation.api.ServiceScope;
-
- @Component(scope=ServiceScope.PROTOTYPE)
- public class MyServiceImpl implements MyService {
- @Start
- void start() {
- // called on each MyService instance
- }
- }
-
-The above service will then automatically be instantiated for each service requester:
-
- :::java
- import org.apache.felix.dm.annotation.api.Component;
- import org.apache.felix.dm.annotation.api.ServiceScope;
-
- @Component
- public class Client1 {
- @ServiceDependency
- void bind(MyService service) {
- // Client1 will be injected with its own MyService instance
- }
- }
-
- @Component
- public class Client2 {
- @ServiceDependency
- void bind(MyService service) {
- // Client2 will be injected with its own MyService instance
- }
- }
-
-The two Client1/Client2 above will be injected with two distinct component instances for the
-MyService service (each MyServiceImpl instance will be invoked in its start callback).
-Now, if you want to control the creation of the MyService, you can then define a bind method which
-takes as argument a ServiceObjects parameter like this:
-
- :::java
- import org.apache.felix.dm.annotation.api.Component;
- import org.apache.felix.dm.annotation.api.ServiceScope;
-
- @Component
- public static class Client {
- @ServiceDependency
- void bind(ServiceObject<MyService> serviceObjects) {
- MyService service;
- try {
- service = serviceObjects.getService();
- } finally {
- serviceObjects.ungetService(service);
- }
- }
- }
-
-Internally, DM will use the
-PrototypeServiceFactory.getService(Bundle clientBundle, ServiceRegistration reg) method in order to
-instantiate the MyServiceImpl component. So, the MyServiceImpl component can optionally use the
-@Inject annotation in order to get injected with the clientBundle and/or the service registration,
-like this:
-
- :::java
- import org.apache.felix.dm.annotation.api.Component;
- import org.apache.felix.dm.annotation.api.ServiceScope;
-
- @Component(scope=ServiceScope.PROTOTYPE)
- public static class MyServiceImpl implements MyService {
-
- @Inject
- Bundle m_clientBundle;
-
- @Inject
- ServiceRegisration m_registration;
-
- @Start
- void start() {
- // called on each MyService instance.
- }
- }
-
-The Bundle and ServiceRegistration can also be injected in the component Constructor:
-
- :::java
- import org.apache.felix.dm.annotation.api.Component;
- import org.apache.felix.dm.annotation.api.ServiceScope;
-
- @Component(scope=ServiceScope.PROTOTYPE)
- public static class MyServiceImpl implements MyService {
-
- public MyServiceImpl(Bundle clientBundle, ServiceRegistration registration) {
- ...
- }
-
- @Start
- void start() {
- // called on each MyService instance.
- }
- }
-
-**Notice that when defining a scoped service with annotations, it is not possible to return service
-properties dynamically from the start method (annotated with @Start).**
-
-# Service property types
-
-So far, you could define component service properties using DM @Property annotation,
-and component configuration could be declared as user defined interfaces.
-You can now declare user-defined annotations which can be used to specify both service
-properties and component configuration.
-It means that instead of declaring service properties using @Property annotation,
-you can now use your own annotations (which must be annotated with the new
-@PropertyType annotation, or possibly using the standard @ComponentPropertyType
-annotation).
-
-Usage example:
-
-Let’s assume your write an OSGi r7 jaxrs servlet context which needs the two
-following service properties:
-
-- `osgi.http.whiteboard.context.name`
-- `osgi.http.whiteboard.context.path`
-
-Then you can first define your own annotation (but you could also reuse the default
-annotations provided by the new upcomming jaxrs whiteboard r7 api, from the
-org.osgi.service.jaxrs.whiteboard.propertytypes package):
-
- :::java
- import org.apache.felix.dependencymanager.annotation.PropertyType;
-
- @PropertyType
- @interface ServletContext {
- String osgi_http_whiteboard_context_name() default AppServletContext.NAME;
- String osgi_http_whiteboard_context_path();
- }
-
-In the above, the underscore is mapped to ".", and you can apply the above annotation on
-top of your component like this:
-
- :::java
- @Component
- @ServletContext(osgi_http_whiteboard_context_path="/game")
- public class AppServletContext extends ServletContextHelper {
- }
-
-You can also use configuration admin service in order to override the default s
-ervice properties:
-
- :::java
- @Component
- @ServletContext(osgi_http_whiteboard_context_path="/game")
- public class AppServletContext extends ServletContextHelper {
- @ConfigurationDependency(propagate=true, pid="my.pid")
- void updated(ServletContext cnf) {
- // if some properties are not present in the configuration, then the ones used in the
- // annotation will be used.
- // The configuration admin properties, if defined, will override the default configurations
- // defined in the annotations
- }
- }
-
-You can also define multiple property type annotations, and possibly single valued
-annotation, like it is the case with standard r7 DS. In this case, you can use the
-standard R7 PREFIX_ constants in order to specify the property prefix, and the property
-name will be derived from the single valued annotation (using camel case convention):
-
- :::java
- @PropertyType
- @interface ContextName { // will map to "osgi.http.whiteboard.context.name" property name
- String PREFIX_="osgi.http.whiteboard.";
- String value();
- }
-
- @PropertyType
- @interface ContextPath { // will map to "osgi.http.whiteboard.context.path" property name
- String PREFIX_="osgi.http.whiteboard.";
- String value();
- }
-
- @Component
- @ContextName(AppServletContext.NAME)
- @ContextPath("/game")
- public class AppServletContext extends ServletContextHelper {
- }
-
-Same example as above, but also using configuration admin service in order to override
-default service properties: Here, as in OSGi r7 declarative service, you can define a
-callback method which accepts as arguments all (or some of) the defined property types:
-
- :::java
- @Component
- @ContextName(AppServletContext.NAME)
- @ContextPath("/game")
- public class AppServletContext extends ServletContextHelper {
- @ConfigurationDependency(propagate=true, pid="my.pid")
- void updated(ContextName ctxName, ContextPath ctxPath) {
- // if some properties are not present in the configuration, then the ones used in the annotation will be used.
- // The configuration admin properties, if defined, will override the default configurations defined in the annotations
- }
- }
-
-The following is the same example as above, but this time the configuration callback can also define a Dictionary in the first argument (in case you want to also get the raw configuration dictionary:
-
- :::java
- @Component
- @ContextName(AppServletContext.NAME)
- @ContextPath("/game")
- public class AppServletContext extends ServletContextHelper {
- @ConfigurationDependency(propagate=true, pid="my.pid")
- void updated(Dictionary<String, Object> rawConfig, ContextName ctxName) {
- // if some properties are not present in the configuration, then the ones used in the annotation will be used.
- // The configuration admin properties, if defined, will override the default configurations defined in the annotations
- }
- }
-
-Empty Marker annotations can also be used: when you define an empty annotation, it will be mapped to a java.lang.Boolean property type with Boolean.TRUE value. For example, the following component will be registered with "osgi.jaxrs.resource" service property with Boolean.TRUE value:
-
- :::java
- @PropertyType
- @interface JaxrsResource { // will map to "osgi.jaxrs.resource" property name
- String PREFIX_="osgi.";
- }
-
- @Component(provides = MyResource.class)
- @JaxrsResource
- public class MyResource {
- @Path(“foo”)
- @GET
- public void getFoo() {
- ...
- }
- }
-
-User defined property types can also be applied on factory components, for example,
-in the following, the service properties are declared using the user-defined annotations
-(they will be overriden from the factory configuratin, if present in the config):
-
- :::java
- @Component(factoryPid="my.factory.pid", propagate=true)
- @ContextName(AppServletContext.NAME)
- ContextPath("/game")
- class Hello implements HelloService {
- void updated(ContextName ctxName, ContextPath ctxPath) {
- // Configure or reconfigure our component. the default service
- // properties will be overriden by the factory configuration (if the
- // service properties are defined in the config)
- }
- }
-
-
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.mdtext
deleted file mode 100644
index 604ef31..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.mdtext
+++ /dev/null
@@ -1,7 +0,0 @@
-Title: Dependency Manager - External Links
-
-This page regroups Dependency Manager external articles and related links:
-
-* [BndTools based demo of Dependency Manager annotations](https://bitbucket.org/marrs/bndtools-dmdemo)
-* [Introduction to Dependency Manager](http://arnhem.luminis.eu/introduction-apache-felix-dependency-manager)
-* [Introduction to Dependency Manager, part II](http://arnhem.luminis.eu/introduction-apache-felix-dependencymanager-part-2)
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/service-scopes.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/service-scopes.mdtext
deleted file mode 100644
index c34da95..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/service-scopes.mdtext
+++ /dev/null
@@ -1,221 +0,0 @@
-Title:
-Notice: Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
- .
- http://www.apache.org/licenses/LICENSE-2.0
- .
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Dependency Manager - Service Scopes
-
-By default service providers are registered once in the osgi registry, and all service consumers share the same service provider instance.
-Now, you can control the scope of the provided services: From the provider side, a "scope" parameter
-is available for all types of DM components and allows to define the scope of the registered service.
-
-The `scope` attribute has three enum values: SINGLETON, BUNDLE, PROTOTYPE
-
-- SINGLETON: it's as before: your registered service is a singleton, meaning that the service must be
-instantiated and registered once, and all using services will share the same service instance of your component.
-- BUNDLE: the service will be registered as a ServiceFactory, meaning an instance of the component must be
-created for each bundle using the service.
-- PROTOTYPE: the service will be registered as a PrototypeServiceFactory, meaning the service is registered as
-a prototype scope service and an instance of the component must be created for each distinct service requester.
-
-Scoped Services are supported by all kind of DM service components:
-
-- Component
-- Aspects
-- Adapters
-- Bundle Adapters
-- Resource Adapters
-
-When a consumer requests a service (using ServiceDependency), then DM will automatically
-dereference the service like this:
-
-- if the service has a SERVICE_SCOPE service property matching SCOPE_PROTOTYPE, the DM will
-internally derefence the service using the ServiceObject API: so, the consumer will get its own copy
-of the requested service instance.
-- else, DM will internally dereference the service, as before.
-When defining scoped component implementation, you can optionally define two special class fields
-in order to get injected with the client Bundle requesting the service, and the ServiceRegisgtration
-Object. Just use @Inject annotations in order to get injected with the client
-Bundle or the ServiceRegistration. You can also define a constructor which takes as argument the
-client bundle as well as the service registration.
-
-# Examples
-
-So, here is a MyService component with PROTOTYPE scope, and each requester will get its own copy
-of MyService instance (the MyServiceImpl.start() method will be called for each MyServiceImpl
-instance):
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- dm.add(createComponent()
- .setScope(ServiceScope.PROTOTYPE)
- .setInterface(MyService.class.getName(), null)
- .setImplementation(MyServiceImpl.class));
- }
- }
-
- public class MyServiceImpl implements MyService {
- void start() {
- // called on each MyService instance
- }
- }
-
-The MyServiceImpl, like with annotations, can define a constructor in order to be injected with
-the client bundle invoking the service and also the service Registration:
-
- :::java
- public class MyServiceImpl implements MyService {
- public MyServiceImpl(Bundle clientBundle, ServiceRegistration reg) { ... }
- void start() {
- // called on each MyService instance
- }
- }
-
-(if you want to auto configure the client Bundle, and the ServiceRegistration, then simply define class fields, they will be auto injected, unless you disable auto configuraiton for Bundle/ServiceRegistration using Component.setAutoConfig(Class, boolean) methods.
-
-Here is a Client component which simply depends on the MyService service using a basic DM
-activator (nothing special to do):
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- dm.add(createComponent()
- .setImplementation(Client.class)
- .add(createServiceDependency()
- .setService(MyService.class, null).setRequired(true).setCallbacks("bind", "unbind"));
- }
- }
-
- public class Client {
- void bind(MyService service) {
- // our client is injected with a specific instance of the MyService component
- // that is created for our Client.
- // If another component defines a service dependency on MyService, then the other
- // component will get its own private copy of MyService component instance
- }
- }
-
-# Example using ServiceObjects API
-
-If now you want to control the creation of the MyService using raw OSGI ServiceObjects API,
-you can also do it like this:
-
-
- :::java
- public class Client {
- void bind(ServiceObjects<MyService> so) {
- MyService s1 = so.getService();
- MyService s2 = so.getService();
- ...
- so.ungetService(s1); // will deactivate the MyService s1 instance
- so.ungetService(s2); // will deactivate the MyService s2 instance
- }
- }
-
-# Scoped services and init/destroy callbacks
-
-When you need to specify dynamic required dependencies from your component.init() method,
-the following mechanism will be used:
-
-First, if your component defines an init callback, then one single component prototype instance singleton is created, as if the component is declared with SCOPE=SINGLETON.
-So, the prototype instance will be invoked in the init callback, but won't be called in start()/stop().
-And when all dependencies are satisfied and injected (including the dynamic dependencies defined in the init method),
-then the ServiceFactory (or PrototypeServiceFactory) is registered.
-And when one client will request a component instance, then a clone will be created and returned.
-
-Example of a scoped component which defines an init method:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- dm.add(createComponent()
- .setScope(ServiceScope.PROTOTYPE)
- .setInterface(MyService.class.getName(), null)
- .setImplementation(MyServiceImpl.class));
- }
- }
-
- public static class MyServiceImpl implements MyService {
- void init(Component comp) {
- // add required dependencies dynamically
- }
-
- void start() {
- // only called on clone, not on the prototype instance singleton
- }
-
- void stop() {
- // called on each clone, not on the prototype instance singleton
- }
- }
-
-So, if you don't specify an init callback then the prototype instance singleton won't be instantiated. Also,
-
-# Limitation when using DM ServiceDependency from API and ServiceObjects
-
-When using DependencyManager ServiceDependency from the DM API (not using annotations),
-you have to know that the ServiceDependency always internally dereferences the
-service dependency, even if you specify a ServiceObjecs
-parameter in your bind method. If now you really want to disable the auto-deref ServiceDependency
-(because you want to directly use the ServiceObjects API), you must then use the
-"setDereference(false") method on your ServiceDependency: in this way, you tell DM to never
-dereference internally the scoped service. Here is an example:
-
- :::java
- public class Activator extends DependencyActivatorBase {
- @Override
- public void init(BundleContext context, DependencyManager dm) throws Exception {
- dm.add(createComponent()
- .setImplementation(Client.class)
- .add(createServiceDependency()
- .setService(MyService.class, null).setRequired(true).setCallbacks("bind", "unbind")
- .setDereference(false));
- }
- }
-
- public class Client {
- void bind(ServiceObjects<MyService> so) {
- MyService s1 = so.getService();
- MyService s2 = so.getService();
- ...
- so.ungetService(s1); // will deactivate the MyService s1 instance
- so.ungetService(s2); // will deactivate the MyService s2 instance
- }
- }
-
-In the above example, the Activator defines the ServiceDependency using the
-ServiceDependency.setDereference(false) method because it's the Client.bind method which will
-create the MyService instances manually.
-
-In the future, I will try to auto detect the signatures of the Client.bind method in order to
-never auto-dereference the injected service in case the bind method takes as argument a
-ServiceObjects (or a ServiceReference) method.
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.mdtext
deleted file mode 100644
index 3a0e732..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.mdtext
+++ /dev/null
@@ -1,113 +0,0 @@
-Title: Dependency Manager - Thread Model
-
-This section gives a brief overview of the default thread model used by Dependency Manager, and also explains how to start and handle components concurrently.
-
-## Default thread model
-
-By default, Dependency Manager uses a lock-free/single thread model:
-
-* When an external event that influence the state of a Component is taking place (for example, when a service dependency on which the Component is depending on is registered in the
-registry by a given thread), then DependencyManager does not perform any locking for the handling of the event. Instead of that, a job that will handle the event is inserted in an internal
-lock-free Serial Queue which is internally maintained in each Component.
-* All jobs scheduled in the Serial Queue are then executed in FIFO order, by the first thread which has triggered the first event. This avoid to use some blocking locks in DM internals, and
-also it simplifies the development of DM components, because all lifecycle callbacks (init/start/stop/destroy) and dependency injections are scheduled through the Serial Queue: This means
-that your component is not concurrently called in lifecycle callbacks and in dependency injection methods.
-* Now let's describe which thread is executing the jobs scheduled in a Component Serial Queue: When a job (J1) is scheduled in the queue while it is empty, then the current thread becomes
-the "master" and will immediately execute the Serial Queue tasks (synchronously). And if another thread triggers another event concurrently while the "master" thread is executing the job J1,
-then a job (J2) for this new event is just enqueued in the Serial Queue, but the other thread returns immediately to the caller, and the job J2 will then be executed by the "master" thread
-(after J1).
-
-This mechanism allows to serially handle all Component events (service dependencies) in FIFO order without maintaining any locks.
-
-The following diagram illustrates the thread model we just described:
-
-<img src="./diagrams/serial-queue.png" alt="Serial Queue" style="width: 600px"/>
-
-## Enabling parallelism with a *ComponentExecutorFactory*
-
-As described above, all the external events that influence the state of a given component are handed by jobs scheduled in the Serial Queue of the Component, and the jobs are getting
-executed serially by a single "master" thread. So usually, bundles are started from a single thread, meaning that all Components are then activated synchronously.
-
-But when you register in the OSGi service registry a ComponentExecutorFactory, that factory will be used by DependencyManager to create an Executor of your choice for each Component,
-typically a shared threadpool configured by yourself. And all the Component Serial Queues will be executed using the Executor returned by the getExecutorFor(Component) method. However,
-jobs scheduled in the Serial Queue of a given Component are still executed one at a time, in FIFO order and the Component remains single threaded, and independent Components may then each
-be managed and activated concurrently with respect to each other.
-
-Here is a diagram which illustrates all this:
-
-<img src="./diagrams/concurrent-serial-queue.png" alt="Concurrent Serial Queue" style="width: 600px"/>
-
-If you want to ensure that all Components are initialized after the ComponentExecutorFactory is registered in the OSGI registry, you can use the "org.apache.felix.dependencymanager.parallel"
-OSGi system property which specifies the list of components which must wait for the ComponentExecutorFactory service. This property value can be set to a wildcard ("*"), or a list of
-components implementation class prefixes (comma separated). So, all components whose class name starts with the specified prefixes will be cached until the ComponentExecutorFactory service
-is registered (In this way, it is not necessary to use the StartLevel service if you want to ensure that all components are started concurrently).
-
-Some class name prefixes can also be negated (using "!"), in order to exclude some components from the list of components using the ComponentExecutorFactory service.
-
-Notice that if the ComponentExecutorFactory itself and all its dependent services are defined using the Dependency Manager API, then you have to list the package of such components with a
-"!" prefix, in order to indicate that those components must not wait for a ComponentExecutorFactory service (since they are part of the ComponentExecutorFactory implementation !).
-
-
-### Examples usage of the *org.apache.felix.dependencymanager.parallel* property:
-
- org.apache.felix.dependencymanager.parallel=*
- -> means all components must be cached until a ComponentExecutorFactory comes up.
-
- org.apache.felix.dependencymanager.parallel=foo.bar, foo.zoo
- -> means only components whose implementation class names are starting with "foo.bar" or "foo.zoo"
- must be handled using an Executor returned by the ComponentExecutorFactory service. Other Components
- will be handled normally, as when there is no ComponentExecutorFactory available.
-
- org.apache.felix.dependencymanager.parallel=!foo.threadpool, *
- -> means all components must be delayed until the ComponentExecutorFactory comes up, except the
- components whose implementations class names are starting with "foo.threadpool" prefix).
-
-
-### Examples of a ComponentExecutorFactory that provides a shared threadpool:
-
-First, we define the OSGi bundle context system property to enable parallelism for all DM Components excepts the one which declares the ComponentExecutorFactory:
-
- org.apache.felix.dependencymanager.parallel=!com.acme.management.threadpool, *
-
-
-Next, here is the Activator which declares the ComponentExecutorFactory:
-
- :::java
- package com.acme.management.threadpool;
- import org.apache.felix.dm.*;
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager mgr) throws Exception {
- mgr.add(createComponent()
- .setInterface(ComponentExecutorFactory.class.getName(), null)
- .setImplementation(ComponentExecutorFactoryImpl.class)
- .add(createConfigurationDependency()
- .setPid("com.acme.management.threadpool.ComponentExecutorFactoryImpl")));
- }
- }
-
-
-And here is the implementation for our ComponentExecutorFactory:
-
- package com.acme.management.threadpool;
- import org.apache.felix.dm.ComponentExecutorFactory;
-
- public class ComponentExecutorFactoryImpl implements ComponentExecutorFactory {
- volatile Executor sharedThreadPool;
-
- void updated(Dictionary conf) {
- int size = Integer.parseInt((String) conf.get("threadpool.size"));
- sharedThreadPool = Executors.newFixedThreadPool(size);
- }
-
- @Override
- public Executor getExecutorFor(Component component) {
- return sharedThreadPool; // Use a shared threadpool for all Components
- }
- }
-
-You will find a live example in the source distribution [sample codes](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/):
-
-* [see the bnd.bnd](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/bnd.bnd) which configures the org.apache.felix.dependencymanager.parallel in the *-runproperties* option.
-* [see the executor factory](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/tpool/) sample code and README file to up-to-date informations.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.mdtext
deleted file mode 100644
index d01cc07..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.mdtext
+++ /dev/null
@@ -1,195 +0,0 @@
-Title: Dependency Manager - Getting Started
-
-When developing an OSGi bundle that has dependencies and possibly registers services, there are two classes in particular we need to implement:
-
-1. The bundle activator which controls the life-cycle of the bundle.
-1. The actual component, which can be a POJO.
-
-When using the dependency manager, your bundle activator is a subclass of `DependencyActivatorBase`. It needs to implement the `init` life cycle method and can optionally also implement a `destroy` method. Both methods take two arguments: `BundleContext` and `DependencyManager`. The latter is your interface to the declarative API you can use to define your components and dependencies.
-
-The following paragraphs will show various examples that explain how to do this. Subsequently, some more advanced scenarios will be covered that involve listening to dependency and component state changes and interacting with the OSGi framework from within your component implementation.
-
-To use the dependency manager, you should put the `org.apache.felix.dependencymanager.jar` in your classpath while compiling and in your OSGi framework when running.
-
-A recent java 8 jdk is required since the dependency manager r8 (the dm r8 release has been built and tested using java version 1.8.74).
-
-## Registering a service
-
-The first example is about registering a service. We extend `DependencyActivatorBase` and in the `init` method we use the reference to the `DependencyManager` to create and add a component. For this component we subsequently set its service interface and implementation. In this case the interface is the `Store` interface, the second parameter, `null`, allows you to provide properties along with the service registration. For the implementation, we only mention the `Class` of the implement [...]
-
-Notice that the dependency manager API uses method chaining to create a more or less "fluent" API that, with proper indentation, is very easy to read.
-
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createComponent()
- .setInterface(Store.class, null)
- .setImplementation(MemoryStore.class)
- );
- }
- }
-
-
-This is the service interface. Nothing special here.
-
-
- public interface Store {
- public void put(String key, Object value);
- public Object get(String key);
- }
-
-
-And finally the implementation. Again, this is just a POJO, there is no reference here to any OSGi or dependency manager specific class or annotation.
-
-
- public class MemoryStore implements Store {
- private Map m_map = new HashMap();
-
- public Object get(String key) {
- return m_map.get(key);
- }
-
- public void put(String key, Object value) {
- m_map.put(key, value);
- }
- }
-
-
-## Depending on a service
-
-Our second example is that of a component that depends on two other services: our `Store` from the previous example and the standard OSGi `LogService`. Looking at the code, there is a small but important difference between the two: `Store` is a required dependency and `LogService` is not. This means that our component really needs a store to work, but if there is no logging available, it can work without. Also note that this component has no `setInterface` method, which simply means it i [...]
-
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createComponent()
- .setImplementation(DataGenerator.class)
- .add(createServiceDependency()
- .setService(Store.class)
- .setRequired(true)
- )
- .add(createServiceDependency()
- .setService(LogService.class)
- .setRequired(false)
- )
- );
- }
- }
-
-
-Now let's look at our POJO. There are a couple of interesting things to explain. First of all, our dependencies are declared as fields, and they don't even have setters (or getters). When the dependency manager instantiates our class, it will (through reflection) inject the dependencies so they are just available for our class to use. That is also the reason these fields are declared as volatile: to make sure they are visible to all threads traversing our instance.
-
-One final note, since we defined our `LogService` dependency as optional, it might not be available when we invoke it. Still, the code does not contain any checks to avoid a null pointer exception. It does not need to, since the dependency manager makes sure to inject a null object when the real service is not available. The null object can be invoked and will do nothing. For a lot of cases that is good enough, but for those cases where it is not, our next example introduces callbacks th [...]
-
-
- public class DataGenerator {
- private volatile Store m_store;
- private volatile LogService m_log;
-
- public void generate() {
- for (int i = 0; i < 10; i++) {
- m_store.put("#" + i, "value_" + i);
- }
- m_log.log(LogService.LOG_INFO, "Data generated.");
- }
- }
-
-
-## Tracking services with callbacks
-
-Sometimes, simply injecting services does not give you enough control over a dependency because you might want to track more than one, or you might want to execute some code on changes. For all those cases, callbacks are your friends. Since one of our goals is to not introduce any kind of API in our POJO, callbacks are declared by specifying their method names instead of through some interface. In this case, we have a dependency on `Translator` services, and we define `added` and `remove [...]
-
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createComponent()
- .setImplementation(DocumentTranslator.class)
- .add(createServiceDependency()
- .setService(Translator.class)
- .setRequired(false)
- .setCallbacks("added", "removed")
- )
- );
- }
- }
-
-
-This is the actual `Translator` service, which, for the purpose of this example, is not that important.
-
-
- public interface Translator {
- public boolean canTranslate(String from, String to);
- public Document translate(Document document, String from, String to);
- }
-
-
-Finally, here's our implementation. It declares the callback methods with one parameter: the `Translator` service. Actually, the dependency manager will look for several different signatures (all explained in more detail in the reference section).
-
-
- public class DocumentTranslator {
- private List<Translator> m_translators = new ArrayList<Translator>();
-
- public void added(Translator translator) {
- m_translators.add(translator);
- }
-
- public void removed(Translator translator) {
- m_translators.remove(translator);
- }
-
- public Document translate(Document document, String from, String to) {
- for (Translator translator : m_translators) {
- if (translator.canTranslate(from, to)) {
- return translator.translate(document, from, to);
- }
- }
- return null;
- }
- }
-
-## Depending on a configuration
-
-Not all dependencies are on services. There are several other types of dependencies
-that are supported, one of them is the configuration dependency.
-When defining the dependency, you must define the persistent ID of the service.
-The component will not become active until the configuration you depend on is available
-*and* is valid. The latter can be checked by your implementation as we will see below.
-
-
- public class Activator extends DependencyActivatorBase {
- public void init(BundleContext context, DependencyManager manager) throws Exception {
- manager.add(createComponent()
- .setImplementation(Task.class)
- .add(createConfigurationDependency()
- .setPid("config.pid")
- )
- );
- }
- }
-
-
-Here's our code that implements `ManagedService` and has an `updated` method.
-This method checks if the provided configuration is valid and throw a
-`ConfigurationException` if it is not. As long as this method does not accept the
-configuration, the corresponding component will not be activated.
-Notice that your component does not necessarily implement the ManagedService interface, and the updated callback
-can also throw any exceptions:
-
-
- public class Task implements ManagedService {
- private String m_interval;
-
- public void execute() {
- System.out.println("Scheduling task with interval " + m_interval);
- }
-
- public void updated(Dictionary properties) throws ConfigurationException {
- if (properties != null) {
- m_interval = (String) properties.get("interval");
- if (m_interval == null) {
- throw new ConfigurationException("interval", "must be specified");
- }
- }
- }
- }
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.mdtext
deleted file mode 100644
index 872353e..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.mdtext
+++ /dev/null
@@ -1,97 +0,0 @@
-Title: Dependency Manager - Leveraging the shell
-
-The shell bundle for the dependency manager extends the gogo shell with one new command called "dm". This command can be used to get insight in the actual components and services in a running OSGi framework.
-
-Typing help ```help dm``` in the gogo shell gives an overview of the available command options.
-
- dm - List dependency manager components
- scope: dependencymanager
- flags:
- compact, cp Displays components using a compact form
- nodeps, nd Hides component dependencies
- notavail, na Only displays unavailable components
- stats, stat, st Displays components statistics
- wtf Detects where are the root failures
- options:
- bundleIds, bid, bi, b <List of bundle ids or bundle symbolic
- names to display (comma separated)> [optional]
- componentIds, cid, ci <List of component identifiers to display
- (comma separated)> [optional]
- components, c <Regex(s) used to filter on component
- implementation class names (comma separated), can be
- negated using "!" prefix> [optional]
- services, s <OSGi filter used to filter some service
- properties> [optional]
- top <Max number of top components to display (0=all)> This
- command displays components callbacks (init/start)
- times> [optional]
- parameters:
- CommandSession
-
-## Usage examples
-Below are some examples for typical usage of the dependency manager shell commands. The examples are based on a simple component model with a dashboard which has a required dependency on four probes (temperature, humidity, radiation, pressure). The radiation probe requires a Sensor service but this sensor is not available.
-
-__List all dependency manager components__
-
-```dm```
-
-Sample output:
-
- [9] dm.demo
- [6] dm.demo.Probe(type=radiation) unregistered
- dm.demo.Sensor service required unavailable
- [7] dm.demo.Probe(type=humidity) registered
- [9] dm.demo.impl.Dashboard unregistered
- dm.demo.Probe (type=temperature) service required available
- dm.demo.Probe (type=radiation) service required unavailable
- dm.demo.Probe (type=humidity) service required available
- dm.demo.Probe (type=pressure) service required available
- [5] dm.demo.Probe(type=temperature) registered
- [8] dm.demo.Probe(type=pressure) registered
-
-All components are listed including the dependencies and the availability of these dependencies. The top level element is the bundle and below are the components registered with that bundle's bundle context. The lowest level is that of the component's dependencies.
-
- [bundleid] bundle
- [component id] component interfaces (service properties)
- dependency <availability>
-
-The following flags can be used to tailor the output:
-
-* ```compact, cp``` shortens package names and dependencies and therefore gives a more compressed output.
-* ```nodeps, nd``` omits the dependencies from the output.
-* ```notavail, na``` filters out all components that are registered wich results in the output only containing those components that are in the unregistered state due to one or more unsatisfied required dependencies. This is the command option most used when using the dependency manager shell commands.
-
-Sample output for ```dm na```:
-
- [9] dm.demo
- [14] dm.demo.impl.Dashboard unregistered
- dm.demo.Probe (type=radiation) service required unavailable
- [11] dm.demo.Probe(type=radiation) unregistered
- dm.demo.Sensor service required unavailable
-
-The flags can be used in conjunction with the other command options.
-
-__Find all components for a given classname__
-
-```dm c .*ProbeImpl```
-
-`dm c` or `components` finds all components for which the classname of the implementation matches the regular expression.
-
-__Find all services matching a service filter__
-
-```dm s "(type=temperature)"```
-
-`dm s` allows finding components based on the service properties of their registered services in the service registry using a standard OSGi service filter.
-
-__Find out why components are not registered__
-
-```dm wtf```
-
-Sample output:
-
- 2 missing dependencies found.
- -----------------------------
- The following service(s) are missing:
- * dm.demo.Sensor is not found in the service registry
-
-`wtf` gives the root cause for components not being registered and therefore their services not being available. In a typical application components have dependencies on services implemented by components that have dependencies on services etcetera. This transitivity means that an entire chain of components could be unregistered due to a (few) root dependencies not being satisfied. `wtf` is about discovering those dependencies.
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/sample-code.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/sample-code.mdtext
deleted file mode 100644
index 8b45f8f..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/sample-code.mdtext
+++ /dev/null
@@ -1,63 +0,0 @@
-Title: Dependency Manager sample projects
-
-You can download this [archive](dm.hello.tgz) which contains the following directories:
-
-- felix-framework-6.0.1/ -> this is a felix framework with pre-installed dependency manager r13 artifacts, as well as with
-configadmin and metatype bundles (these dependencies are required by dm)
-- hello.api/ -> provides a sample component using the dependency manager API.
-- hello.lambda/ -> provides a sample component using the dependency manager Lambda API.
-- hello.annotations -> provides a sample component using the dependency manager annotations.
-
-All samples can be built using either gradle or maven.
-To build with gradle, simply type "./gradlew jar", and to build with maven, type "mvn clean install".
-If you are using an http proxy, you must set the following environment:
-
-- for gradle: export GRADLE_OPTS="-Dhttp.proxyHost=<ip> -Dhttp.proxyPort=<port> -Dhttps.proxyHost=<ip> -Dhttps.proxyPort=<port>
-- for maven, you must setup your http proxy in your ~/.m2/settings.xml
-
-Once built, the three jars for all hello projects can be put in the felix-framework-6.0.1/bundles/ directory.
-Now start felix like this:
-
- cd felix-framework-6.0.1
- java -jar bin/felix.jar
-
-You should then see the following logs displayed to stdout:
-
- HelloComponent started using Dependency Manager API
- HelloComponent started using Dependency Manager Lambda
- HelloComponent started using Dependency Manager Annotations
-
-You can also play with the dm shell commands. First, type "help dm":
-
- g! help dm
-
- dm - List dependency manager components
- scope: dependencymanager
- flags:
- compact, cp Displays components using a compact form
- nodeps, nd Hides component dependencies
- notavail, na Only displays unavailable components
- stats, stat, st Displays components statistics
- wtf Detects where are the root failures
- options:
- bundleIds, bid, bi, b <List of bundle ids or bundle symbolic names to display (comma separated)> [optional]
- componentIds, cid, ci <List of component identifiers to display (comma separated)> [optional]
- components, c <Regex(s) used to filter on component implementation class names (comma separated), can be negated using "!" prefix> [optional]
- services, s <OSGi filter used to filter some service properties> [optional]
- top <Max number of top components to display (0=all)> This command displays components callbacks (init/start) times> [optional]
-
-Now type "dm" in order to see all dependency manager components:
-
- g! dm
- [1] hello.annotations
- [3] hello.HelloComponent registered
- [2] hello.api
- [0] hello.HelloComponent registered
- [3] hello.lambda
- [1] hello.HelloComponent registered
- [10] org.apache.felix.dependencymanager.runtime
- [2] org.apache.felix.dm.runtime.DependencyManagerRuntime registered
- active (DependencyManager-Component=*) bundle optional available
- org.osgi.service.packageadmin.PackageAdmin service required available
- org.osgi.service.log.LogService service optional unavailable
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/working-with-annotations.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/working-with-annotations.mdtext
deleted file mode 100644
index 09164c8..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-dependency-manager/tutorials/working-with-annotations.mdtext
+++ /dev/null
@@ -1,214 +0,0 @@
-Title: Dependency Manager - Annotations
-
-The Dependency Manager provides a compact and versatile Java API that allows you to declaratively and programmatically register, acquire, and manage dynamic OSGi components. This has many advantages, but also means you need to implement your own `BundleActivator`. In cases where your dependencies are not that dynamic, an alternative is to use annotations on your component.
-
-This tutorial outlines how to setup and use such annotations to describe your components and dependencies. We present a simple "Hello World" component defined using annotations, and also explain how to build the bundle using either Bnd, Ant, or Maven.
-
-## Hello World Component
-
- package org.apache.felix.dependencymanager.samples.annotation.hello;
-
- import org.apache.felix.dm.annotation.api.Component;
- import org.apache.felix.dm.annotation.api.Start;
-
- @Component
- public class HelloWorld {
- @Start
- public void activate() {
- System.out.println("Hello world !");
- }
- }
-
-## Compiling with BndTools:
-
-This section is a step-by-step tutorial showing how to create a "greeting" project under BndTools and how to use Dependency Manager annotations.
-BndTools is a nice Eclipse plugin on top of the popular "Bnd" builder tool ([See The BndTools home page](http://bndtools.org/)).
-
-It is assumed that you have installed bndtools with a properly configured cnf project (using Bundle-Hub configuration).
-
-### Add DM annotation.jar to the build repository and to the buildpath
-
-Before creating a project that uses the DM annotations, you first have to add the DM annotation jar in the "cnd/buildrepo".
-(In the future, we'll push the DM annotation.jar to the Felix OBR, so you will then simply only have to create
-a bndtools remote repository that will point to the remote Felix OBR).
-
-* Select the "Repositories" Window
-* Select the "Build" repository
-* Then click on the "Add Bundles to Repository" -> "Add External Jar" and point the org.apache.felix.dependencymanager.anntation.jar.
-* Then click on "Finish" button
-
-Now, declare the DM annotation plugin in the BndTools plugin path:
-
-* Select "BndTools/Open ext/pluginpaths.bnd
-* Select the "+" button of the "Plugin Path" section, and select "buildrepo/org.apache.felix.dependencymanager.annotation/org.apache.felix.dependencymanager.annotation-X.Y.Z.jar (replace X.Y.Z by the actual version)
-* Then press "Ctrl-s" to save the configuration
-
-### Create the greeting project
-
-Now we have properly configured the DM annotation plugin in bndtools, we can then create our "greeting" project.
-
-* From the File menu, select "New -> Bndtools OSGi Project" for creating an empty project, and call it "greeting".
-* Click on bnd.bnd file of the greeting project, and click on the "Build" tab, then click on the "+" button, near the "Build Path" section.
-* Then select "Build/org.apache.felix.dependencymanager.annotation" bundle and click on "Add -->".
-* Click on Finish, and save the project (press Ctrl-s).
-
-### Creating the HelloWorld component
-
-Since we have configured the buildpath, we are now ready to create our first HelloWorld component using annotations.
-Create the following class in the greeting project:
-
- :::java
- package greeting;
-
- import org.apache.felix.dm.annotation.api.Component;
- import org.apache.felix.dm.annotation.api.Start;
-
- @Component
- public class HelloWorld {
- @Start
- void start() {
- System.out.println("Hello World");
- }
- }
-
-### Finalize the bnd configuration
-
-We have created our first HelloWorld component. We now have to finish the bnd configuration by specifying a Private-Package directive,
-and we also add the -plugin bnd directive in order to ask bnd to call the DM annotation plugin during compilation:
-
-* Click on the bnd.bnd file of the greeting project
-* Click on Contents and add the "greeting" package in the Private Packages
-* Finally, declare the DM annotation plugin by clicking on the "source" tab, and add the following:
- * -plugin org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug
-* Save configuration (Press Ctrl-s)
-* Click on "Build" and on "Rebuild"
-
-The greeting.jar should now be generated with a META-INF/dependencymanager/ directory. The plugin logs debug messages in /tmp/dmplugin/*
-
-So, the final bnd.bnd file should look like this:
-
- Bundle-Version: 0.0.0.${tstamp}
- -buildpath: org.apache.felix.dependencymanager.annotation
- Private-Package: greeting
- -plugin org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug
-
-### Testing the bundle under bndtools:
-
-We are now going to execute a Felix framework under Eclipse/BndTools, and run our HelloWorld example.
-
-First, install the following necessary bundles in the "Local" repository:
-(in the future, we'll release the DM bundles in the Felix OBR, so you will only have to declare a remote repository, instead of doing this):
-
-* Click on Repositories
-* Add the following DM bundles in the "Local" Repository:
- * org.apache.felix.dependencymanager.jar
- * org.apache.felix.dependencymanager.shell.jar
- * org.apache.felix.dependencymanager.runtime.jar
-
-Now, configure the Felix framework, as well as the list of the bundles to be executed:
-
-* Click on the bnd.bnd file of the greeting project
-* Click on the "Run" tab
-* In the Core Runtime, Select the latest version of Felix currently available
-* Select Execution Env=JavaSE-1.7
-* In the "Run Bundles" section, add the following list:
- * org.apache.felix.configadmin.jar
- * org.apache.felix.metatype.jar
- * org.apache.felix.log.jar
- * org.apache.felix.gogo.command
- * org.apache.felix.gogo.runtime
- * org.apache.felix.gogo.shell
- * org.apache.felix.dependencymanager
- * org.apache.felix.dependencymanager.runtime
- * org.apache.felix.dependencymanager.shell
-* Then save the configuration (Press Ctrl-s).
-
-Now, Click on "Run OSGi". You should now see in the Console the Gogo Shell prompt with the
-message displayed by the HelloWorld component:
-
- Hello World
- Welcome to Apache Felix Gogo
- g!
-
-Just type "dm" in the console, and you should see:
-
- [2] org.apache.felix.dependencymanager.runtime
- [0] org.apache.felix.dm.runtime.DependencyManagerRuntime registered
- active (DependencyManager-Component=*) bundle optional available
- org.osgi.service.packageadmin.PackageAdmin service required available
- org.osgi.service.log.LogService service optional available
- [10] greeting
- [1] greeting.HelloWorld registered
-
-The bundle [2] is the dependency manager runtime bundle that is in charge of managing all bundles containing annotated components.
-And the bundle [10] is our greeting bundle (and the "greeting.HelloWorld" component is registered).
-
-## Compiling with Ant:
-
-Since Bnd provides a Ant task, you can use the bnd directives above with the following build.xml:
-(it is assumed that directives.bnd, bnd.jar, json-20070829.jar and org.apache.felix.dependencymanager.annotation.jar are in the current directory)
-
- <project name="TestDM" default="bnd">
- <property name="bnd" value="bnd.jar" />
- <property name="json" value="json-20070829.jar" />
- <property name="dmannot" value="org.apache.felix.dependencymanager.annotation.jar" />
-
- <target name="compile">
- <delete dir="target/classes" quiet="yes" />
- <mkdir dir="target/classes" />
- <javac srcdir="src/main/java" destdir="target/classes" classpath="${dmannot}" />
- </target>
-
- <target name="bnd" depends="compile">
- <taskdef resource="aQute/bnd/ant/taskdef.properties" classpath="${dmannot}:${bnd}:${json}" />
- <bnd classpath="target/classes" eclipse="false" files="directives.bnd" output="org.apache.felix.dependencymanager.samples.annotation.hello.jar" />
- </target>
- </project>
-
-
-## Compiling with Maven:
-
-When compiling with Maven, you have to invoke the Dependency Manager Bnd plugin, using the special "_plugin" directive.
-In the R1 Dependency Manager distribution, the bundles are not published to maven central, and you
-have to manually install the org.apache.felix.dependencymanager.annotation.jar file to your local repository, or to your own corporate nexus server.
-([See this link](http://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html) to manually install the dm annotation jar to your local repository.)
-
- :::xml
- <project ...>
- <dependencies>
- ...
- <dependency>
- <groupId>org.apache.felix</groupId>
- <artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
- <version>4.0.0</version>
- </dependency>
- </dependencies>
- <build>
- <plugins>
- ...
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <version>2.5.0</version>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-Name>Test</Bundle-Name>
- <Bundle-SymbolicName>test</Bundle-SymbolicName>
- <Import-Package>*</Import-Package>
- <Private-Package>test.dmannotations</Private-Package>
- <!-- when setting log=debug, logs are writen to /tmp/dmplugin/ directory -->
- <_plugin>org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug</_plugin>
- </instructions>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.apache.felix</groupId>
- <artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
- <version>4.0.0</version>
- </dependency>
- </dependencies>
- </plugin>
- </plugins>
- </build>
- </project>
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-deployment-admin.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-deployment-admin.mdtext
deleted file mode 100644
index 76e8ae9..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-deployment-admin.mdtext
+++ /dev/null
@@ -1,4 +0,0 @@
-Title: Apache Felix Deployment Admin
-
-This project implements the OSGi Deployment Admin specification; please consult the OSGi Compendium Specification chapter 114 for more information.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-event-admin.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-event-admin.mdtext
deleted file mode 100644
index 4bb41a7..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-event-admin.mdtext
+++ /dev/null
@@ -1,225 +0,0 @@
-Title: Apache Felix Event Admin
-
-The Event Admin Service Specification, part of the OSGi Compendium specification, defines a general inter-bundle communication mechanism. The communication conforms to the popular publish/subscribe paradigm and can be performed in a synchronous or asysnchronous manner.
-
-The main components in a publish/subscribe communication are:
-
-* *Event Publisher* - sends events or messages related to a specific *topic*
-* *Event Handler* (or *Subscriber*) - expresses interest in one or more topics and receives all the messages belonging to such topics.
-
-Events are composed of two attributes:
-
-* a *topic* defining the nature of the event; topic names are usually arranged in a hierarchical namespace, where slashes are used to separate the levels (i.e. "org/osgi/framework/FrameworkEvent/STARTED") and
-* a set of *properties* describing the event.
-
-## Creating an Event Publisher
-
-An event publisher is a simple Java class that creates events and sends them using the `EventAdmin` service interface, for example:
-
-
- public void reportGenerated(Report report, BundleContext context)
- {
- ServiceReference ref = context.getServiceReference(EventAdmin.class.getName());
- if (ref != null)
- {
- EventAdmin eventAdmin = (EventAdmin) context.getService(ref);
-
- Dictionary properties = new Hashtable();
- properties.put("title", report.getTitle());
- properties.put("path" , report.getAbsolutePath());
- properties.put("time", System.currentTimeMillis());
-
- Event reportGeneratedEvent = new Event("com/acme/reportgenerator/GENERATED", properties);
-
- eventAdmin.sendEvent(reportGeneratedEvent);
- }
- }
-
-
-The `EventAdmin.sendEvent()` method sends the `Event` object synchronously. To send it asynchronously, use the `EventAdmin.postEvent()` method, such as:
-
-
- //..
- Event reportGeneratedEvent = new Event("com/acme/reportgenerator/GENERATED", properties);
- eventAdmin.postEvent(reportGeneratedEvent);
-
-
-## Creating an Event Handler
-
-Creating an event handler is as simple as implementing the `EventHandler` interface:
-
-
- public class ReportEventHandler implements EventHandler
- {
- public void handleEvent(Event event)
- {
- String reportTitle = (String) event.getProperty("title");
- String reportPath = (String) event.getProperty("path");
-
- sendReportByEmail(reportTitle, reportPath);
- }
-
- //..
-
-
-## Registering an Event Handler
-
-To receive event notifications, the event handler must be registered as a OSGi service under the object class `org.osgi.service.event.EventHandler`. When registering the service, a `String\[\]({{ refs..path }})` property named `*EVENT_TOPIC*` must be specified; this property describes the list of topics in which the event handler is interested. For example:
-
-
- String[] topics = new String[] {
- "com/acme/reportgenerator/GENERATED"
- };
-
- Dictionary props = new Hashtable();
- props.put(EventConstants.EVENT_TOPIC, topics);
- bundleContext.registerService(EventHandler.class.getName(), new ReportEventHandler() , props);
-
-
-It is possible to use '*' as a wildcard in the final character of the EVENT_TOPIC, like in this example:
-
-
-
- String[] topics = new String[] {
- "com/acme/reportgenerator/*"
- };
-
- Dictionary props = new Hashtable();
- props.put(EventConstants.EVENT_TOPIC, topics);
- bundleContext.registerService(EventHandler.class.getName(), new ReportEventHandler() , props);
-
-
-Finally, it is possible to specify an additional `EVENT_FILTER` property to filter event notifications; the filter expression follows, the normal LDAP syntax:
-
-
- String[] topics = new String[] {
- "com/acme/reportgenerator/GENERATED"
- };
-
- Dictionary props = new Hashtable();
- props.put(EventConstants.EVENT_TOPIC, topics);
- props.put(EventConstants.EVENT_FILTER, "(title=samplereport)");
- bundleContext.registerService(EventHandler.class.getName(), new ReportEventHandler() , props);
-
-
-## OSGi Events
-
-Every OSGi framework sends (asynchronously) a number of events that can be captured by any bundle.
-
-### Framework Events
-
-* org/osgi/framework/BundleEvent/STARTED
-* org/osgi/framework/BundleEvent/ERROR
-* org/osgi/framework/BundleEvent/PACKAGES_REFRESHED
-* org/osgi/framework/BundleEvent/STARTLEVEL_CHANGED
-* org/osgi/framework/BundleEvent/WARNING
-* org/osgi/framework/BundleEvent/INFO
-
-### Bundle Events
-
-* org/osgi/framework/BundleEvent/INSTALLED
-* org/osgi/framework/BundleEvent/STARTED
-* org/osgi/framework/BundleEvent/STOPPED
-* org/osgi/framework/BundleEvent/UPDATED
-* org/osgi/framework/BundleEvent/UNINSTALLED
-* org/osgi/framework/BundleEvent/RESOLVED
-* org/osgi/framework/BundleEvent/UNRESOLVED
-
-The followig properties are always present in a bundle event object:
-
-* *bundle.id*
-* *bundle.symbolicName*
-
-### Service Events
-
-* org/osgi/framework/ServiceEvent/REGISTERED
-* org/osgi/framework/ServiceEvent/MODIFIED
-* org/osgi/framework/ServiceEvent/UNREGISTERING
-
-The following properties are always present in a service event object:
-
-* *service*
-* *service.id*
-* *service.pid*
-
-Each of the aforementioned events actually contains a wider set of properties. Check the OSGi Compendium specification, section 113.6, for a complete list.
-
-## Configuration
-
-The Apache Felix Event Admin implementation is trying the deliver the events as fast as possible. Events sent from different threads are sent in parallel. Events from the same thread are sent in the order they are received (this is according to the spec).
-A timeout can be configured which is used for event handlers. If an event handler takes longer than the configured timeout to process an event, it is denied. Once a handler is in a denylist, it doesn't get sent any events anymore.
-The Felix Event Admin can be configured either through framework properties or through the configuration admin using PID `org.apache.felix.eventadmin.impl.EventAdmin`. This is a list of configuration properties:
-
-----
-**Thread Pool Size**
-
-*Property*: org.apache.felix.eventadmin.ThreadPoolSize
-*Default*: 20
-*Type*: Integer
-
-The size of the thread pool used for event delivery. The default value is 20. Increase in case of a large amount of events. A value of less then 2 triggers the default value. If the pool is exhausted, event delivery is blocked until a thread becomes available from the pool. Each event is delivered in a thread from the pool unless the ignore timeouts is configured for the receiving event handler.
-
-----
-
-**Async/sync Thread Pool Ratio**
-
-*Property*: org.apache.felix.eventadmin.AsyncToSyncThreadRatio
-*Since*: Release 1.4.2
-*Default*: 0.5
-*Type*: Double
-
-The ratio of asynchronous to synchronous threads in the internal thread pool. Ratio must be positive and may be adjusted to represent the distribution of post to send operations. Applications with higher number of post operations should have a higher ratio.
-
-----
-
-**Timeout**
-
-*Property*: org.apache.felix.eventadmin.Timeout
-*Default*: 5000
-*Type*: Integer
-
-The deny-listing timeout in milliseconds. The default value is 5000. Increase or decrease at own discretion. A value of less then 100 turns timeouts off. Any other value is the time in milliseconds granted to each event handler before it gets denied.
-
-----
-
-**Require Topic**
-
-*Property*: org.apache.felix.eventadmin.RequireTopic
-*Default*: true
-*Type*: Boolean
-
-Are event handlers required to be registered with a topic? This is enabled by default. The specification says that event handlers must register with a list of topics they are interested in. Disabling this setting will enable that handlers without a topic are receiving all events (i.e., they are treated the same as with a topic=*).
-
-----
-
-**Ignore Timeouts**
-
-*Property*: org.apache.felix.eventadmin.IgnoreTimeout
-*Default*: empty
-*Type*: String
-
-Configure event handlers to be called without a timeout. If a timeout is configured by default all event handlers are called using the timeout. For performance optimization it is possible to configure event handlers where the timeout handling is not used - this reduces the thread usage from the thread pools as the timout handling requires an additional thread to call the event handler. However, the application should work without this configuration property. It is a pure optimization! Th [...]
-
-----
-
-**Ignore Topics**
-
-*Property*: org.apache.felix.eventadmin.IgnoreTopic
-*Since*: Release 1.4.0
-*Default*: empty
-*Type*: String
-
-For performance optimization it is possible to configure topics which are ignored by the event admin implementation. In this case, a event is not delivered to registered event handlers. The value is a list of strings (separated by comma). " +If a single value ends with a dot, all topics in exactly this package are ignored. If a single value ends with a star, all topics in this package and all sub packages are ignored. If a single value neither ends with a dot nor with a start, this is as [...]
-
-----
-
-**Log Level**
-
-*Property*: org.apache.felix.eventadmin.LogLevel
-*Note*: This property can't be set through the OSGi configuration.
-*Default*: 2 (=WARNING)
-*Type*: Integer
-
-This sets the log level used for messages outputted by the event admin implementation. Valid values are 1 (=ERROR), 2 (=WARNING), 3 (=INFO), and 4 (=DEBUG). The default is 2 and an invalid value sets the level to the default value.
-
-----
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-file-install.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-file-install.mdtext
deleted file mode 100644
index 514f0c7..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-file-install.mdtext
+++ /dev/null
@@ -1,104 +0,0 @@
-Title: Apache Felix File Install
-
-File Install is a directory based OSGi management agent. It uses a directory in the file system to install and start a bundle when it is first placed there. It updates the bundle when you update the bundle file in the directory and, when the file is deleted, it will stop and uninstall the bundle.
-
-File Install can do the same for configuration configuration files. This surprisingly simple bundle is very powerful because there are so many programs that work with the file system. For example:
-
-* If you use Ant, you can just copy the resulting bundle to the watched directory.
-* You can download bundles from the web and directly install them without any extra effort.
-* You can easily drag and drop bundles in and out of the framework.
-
-## Setup
-
-The bundle runs on any framework. For its configuration, it will use the following system properties:
-
-|Property|Default|Description|
-|--|--|--|
-|`felix.fileinstall.poll`|2000 ms|Number of milliseconds between 2 polls of the directory|
-|`felix.fileinstall.dir`|./load|The name of the directory to watch. Several directories can be specified by using a comma separated list.|
-|`felix.fileinstall.log.level`|1|Threshold of logging information|
-|`felix.fileinstall.log.default`|stdout|Possible values are `stdout`, `jul`. Defines where to log when the OSGi LogService is not available.|
-|`felix.fileinstall.bundles.new.start`|true|Automatically start newly discovered bundles|
-|`felix.fileinstall.filter`| |A regular expression to be used to filter file names|
-|`felix.fileinstall.tmpdir`| |The name of the temporary directory to use with exploded or transformed bundles (defaults to the temporary dir for the JVM)|
-|`felix.fileinstall.noInitialDelay`|false|Determines if File Install waits `felix.fileinstall.poll` milliseconds before doing an initial scan or not.|
-|`felix.fileinstall.bundles.startTransient`|false|If `true`, File Install will start the bundles transiently.|
-|`felix.fileinstall.bundles.startActivationPolicy`|true|Start bundles with their default activation policy or not|
-|`felix.fileinstall.start.level`|0|If set to a value different from `0`, File Install will set the start level for deployed bundles to that value. If set to `0`, the default framework bundle start level will be used.|
-|`felix.fileinstall.active.level`|0|FileInstall won't scan for files unless the active framework start level is greater than this value|
-|`felix.fileinstall.enableConfigSave`|true|If `false`, File Install will not write back in the file configurations changes. Note that this setting is global and can not be modified per polled directory.|
-|`felix.fileinstall.configEncoding`|ISO-8859-1|The encoding used to read and write configuration files.|
-|`felix.fileinstall.bundles.updateWithListeners`|false|If `true`, FileInstall will update managed bundles when a new version of an artifact handler is detected. This detection is performed based on the last modification date of the bundle registering the handler.|
-|`felix.fileinstall.optionalImportRefreshScope`|all|Possible values are `none`, `managed`, `all`. Defines which bundles can be elected for refresh.|
-|`felix.fileinstall.fragmentRefreshScope`|all|Possible values are `none`, `managed`, `all`. Defines which bundles can be elected for refresh.|
-|`felix.fileinstall.disableNio2`|false|If `true`, File Install will not use NIO2 to scan directory and files.|
-|`felix.fileinstall.subdir.mode`|jar|Possible values are `jar`, `skip`, `recurse`. Defines the behavior for sub directories.|
-
-
-Once started, the values of these properties are printed to the console.
-
-## Configurations
-
-Configuration files are plain property files (`java.util.Property`). The format is simple:
-
-
- file ::= ( header | comment ) *
- header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
- comment ::= '#' <any>
-
-
-Notice that this model only supports string properties. For example:
-
-
- # default port
- ftp.port = 21
-
-
-Configuration file names are related to the PID and factory PID. The structure of the file name is as follows:
-
-
- filename ::= <pid> ( '-' <subname> )? '.cfg'
-
-
-If the form is `<pid>.cfg`, the file contains the properties for a Managed Service. The `<pid>` is then the PID of the Managed Service. See the Configuration Admin service for details.
-
-When a Managed Service Factory is used, the situation is different. The `<pid>` part then describes the PID of the Managed Service Factory. You can pick any `<subname>`, this bundle will then create an instance for the factory for each unique name. For example:
-
-
- com.acme.xyz.cfg // configuration for Managed Service
- // com.acme.xyz
- com.acme.abc-default.cfg // Managed Service Factory,
- // creates an instance for com.acme.abc
-
-
-If a configuration managed by File Install is modified, File Install will write the configuration back to a property file to ensure peristence across restarts.
-
-## Property substitution in configuration files
-
-It is possible to use system properties to specify the values of properties in configuration files. This is achieved through system property substitution, which is instigated by using `$\{<property>\`} syntax, where <property> is the name of a system property to substitute. Bundle context properties will take precedence over system properties if available.
-Example:
-
-
- ftp.port = ${system.ftp.port}
-
-
-## Watching multiple directories with File Install
-
-Starting with version 3.1.0 it is possible to specify several directories to watch with the system property `felix.fileinstall.dir`; this property can either point to a single directory or a comma separated list of directories. In addition, Apache Felix File Install provides a ManagedServiceFactory to create multiple instances of File Install. Asuming you have a File Install bundle watching a `bundles` folder, creating a new instance is as simple as creating a new configuration file `org [...]
-
- felix.fileinstall.poll=2000
- felix.fileinstall.dir=/configDir
- felix.fileinstall.debug=-1
- felix.fileinstall.filter=.*\\.cfg
- felix.fileinstall.bundles.new.start=false
-
-
-## Exploded bundles
-
-Apache Felix File Install has the ability to watch for exploded bundles and automatically update such bundles if the content is changed in any way. If a watched directory contains a sub directory, its content will be jar'ed and deployed to the OSGi framework. Any change to a file in this directory or one of its subdirectories will result in the directory to be jar'ed again and the corresponding bundle to be updated.
-
-## Custom artifacts
-
-Apache Felix File Install can support deployment of custom artifacts. By default, configurations and plain OSGi bundles are supported, but other kind of artifacts can be deployed through custom artifact handlers.
-
-To add support for a custom artifact, a service implementing one of `org.apache.felix.fileinstall.ArtifactListener`'s sub interfaces must be registered in the OSGi registry.
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework-security.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-framework-security.mdtext
deleted file mode 100644
index f384b1d..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework-security.mdtext
+++ /dev/null
@@ -1,50 +0,0 @@
-Title: Apache Felix Framework Security
-
-The Felix Framework Security subproject is an implementation of the security part of the OSGi R4.2 core specification.
-
-# Installing
-
-Support for the OSGi R4.2 security specifications including `PermissionAdmin` and `ConditionalPermissionAdmin` is provided by the framework.security extension bundle. The bundle provides both, the packages as well as the services when it is installed.
-
-All that needs to be done is to install the `org.apache.felix.framework.security` bundle into the framework.
-
-# Using security
-
-Besides installing the security bundle three properties should be specified:
-
- - `org.osgi.framework.security="osgi"`
- - `java.security.policy=all.policy`
- - `org.osgi.framework.trust.repositories=<list of keystores>`
-
-The first installs a security manager on framework init (which in combination with the installed security bundle enables security).
-
-The second points to a security policy file (`all.policy`) that gives all permission like so:
-
- grant {
- permission java.security.AllPermission;
- };
-
-
-The third allows to specify a `File.pathSeparator` separated list of JKS keystores without a password. The certificates found inside the keystores are the trusted root certificates of the framework (setting this property is optional).
-
- $ java -Djava.security.policy=all.policy -Dorg.osgi.framework.security="osgi" -jar bin/felix.jar
-
- Welcome to Felix
- ================
-
- -> install file:org.apache.felix.framework.security.jar
- -> inspect s c 0
- System Bundle (0) provides services:
- ------------------------------------
- objectClass = org.osgi.service.startlevel.StartLevel
- service.id = 1
- ----
- objectClass = org.osgi.service.packageadmin.PackageAdmin
- service.id = 2
- ----
- objectClass = org.osgi.service.permissionadmin.PermissionAdmin
- service.id = 3
- ----
- objectClass = org.osgi.service.condpermadmin.ConditionalPermissionAdmin
- service.id = 4
-
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-framework.mdtext
deleted file mode 100644
index a7d586f..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework.mdtext
+++ /dev/null
@@ -1,8 +0,0 @@
-Title: Apache Felix Framework
-
-The Felix Framework subproject is an implementation of the OSGi R6 core framework specification.
-
-## Framework documentation
-
-{% for label, page in children %}* [{{ page.headers.title }}]({{ page.path }})
-{% endfor %}
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-bundle-cache.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-bundle-cache.mdtext
deleted file mode 100644
index 14ec36a..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-bundle-cache.mdtext
+++ /dev/null
@@ -1,66 +0,0 @@
-Title: Apache Felix Framework Bundle Cache
-
-* [Introduction]({{ refs.-introduction.path }})
-* [Default Behavior]({{ refs.-default-behavior.path }})
-* [Configuring Default Behavior]({{ refs.-configuring-behavior.path }})
-
-
-
-# Introduction
-
-The OSGi specification states that the framework must cache bundles and their run-time state, but it does not explicitly define how this should be done. As a result, each OSGi framework implementation is likely to cache bundles differently. This document describes in detail how the Felix framework handles bundle caching by default and also describes the mechanisms to modify this default behavior.
-
-
-
-# Default Behavior
-
-Since the OSGi R4.2 specification, the standard framework launching and embedding API requires that frameworks should use "reasonable defaults" for all configuration properties so it is possible to start a framework without any configuration. One such default value is the location of the framework bundle cache. When the Felix framework is start, it creates a bundle cache directory, called `felix-cache`, in the current working directory by default. All bundle information is saved inside t [...]
-
-The structure of a bundle cache directory is reasonably simple; it contains a directory for each bundle, where the directory name corresponds to the bundle identifier number. Each bundle directory contains a file for the bundle's location, identifier, start level, state, and a directory containing the bundle JAR file and any extracted embedded JAR files or native libraries if any exist. As an example, the bundle cache directory for a bundle containing an embedded JAR file and a native li [...]
-
-
- ${user.dir}
- felix-cache/
- bundle4/
- bundle.id
- bundle.lastmodified
- bundle.location
- bundle.startlevel
- bundle.state
- data/
- version0.0/
- revision.location
- bundle.jar
- bundle.jar-embedded/
- embedded.jar
- bundle.jar-lib/
- 0/
- libnative.so
-
-
-The above directory structure indicates that the imaginary bundle is cached in the `felix-cache` in the current working directory and "4" is its bundle identifier. Additionally, besides the bundle JAR file, the bundle has one embedded JAR file and one native library. The naming convention is rather straightforward and consistent, although the directory structure may seem rather indirect. The precise details behind the rationale for the directory structure around embedded JAR files and na [...]
-
-All cached bundle directories will follow the basic pattern displayed above, except for the names of the embedded JAR files and native libraries. Embedded JAR files and native libraries use the names specified in the bundle manifest and may also include sub-directories to avoid name clashes. The naming convention for the directory containing the bundle JAR file, `version0.0`, requires further explanation.
-
-The bundle JAR directory uses a numbering scheme to keep track of the number of times a bundle is updated and the number of times it is refreshed; the name of the directory maps like this: `version<refresh-count>.<revision-count>`. The reasoning behind this is tricky. It is necessary to keep track of the revision count because the OSGi specification requires when a bundle is updated that the update takes effect immediately. However, it also requires that old packages from older revisions [...]
-
-For example, if a bundle provides package `foo` and it is updated and now provides packages `foo` and `bar`, then after the update `foo` will be supplied from the older revision and `bar` will be supplied from the newer revision. This is possible for any number of updates, thus the bundle JAR directory must keep each revision around until a refresh is performed. Such "revision directories" are generally only run-time directories and are removed when the framework is shutdown or refreshed [...]
-
-To illustrate, upon initial installation, the bundle JAR file is placed into a revision directory named `revision0.0`. When an update is performed, the updated bundle JAR file is placed in a directory named `revision0.1`. If another update is performed without a refresh of the framework, the newer revision will be placed into a directory named `revision0.2` and so on. When the framework is refreshed or shutdown, all revision directories are purged from the bundle cache and only the most [...]
-
-Simply purging the old revision directories may appear adequate for refreshing the framework, but it is not due to how the JVM handles native libraries. When a native library is loaded it is associated with a specific class loader; no other class loader can load the same native library. The uniqueness of a native library is determined by its absolute path in the file system. Consequently, when the framework is refreshed, it is necessary to recreate the class loaders for all refreshed bun [...]
-
-After purging all old revision directories, the current revision directory is renamed based on the current refresh count. By renaming the directory, it is possible to re-load the native library since its path in the file system has changed. The old class loaders and native libraries will eventually be garbage collected. The current refresh count is stored in a file, called `refresh.counter`, in the bundle's directory. To illustrate, if a bundle was updated and has two revision directorie [...]
-
-
-
-# Configuring Default Behavior
-
-It is possible to modify the default behavior of Felix' bundle cache by setting certain configuration properties; see the [usage document]({{ refs.apache-felix-framework-usage-documentation-configuring-framework.path }}) for information on how to set configuration properties for Felix. Felix' bundle cache recognizes the following configuration properties:
-
-* `org.osgi.framework.storage` \- Sets the directory to use as the bundle cache; by default bundle cache directory is `felix-cache` in the current working directory. The value should be a valid directory name. The directory name can be either absolute or relative. Relative directory names are relative to the current working directory. The specified directory will be created if it does not exist.
-* `org.osgi.framework.storage.clean` \- Determines whether the bundle cache is flushed. The value can either be "`none`" or "`onFirstInit`", where "`none`" does not flush the bundle cache and "`onFirstInit`" flushes the bundle cache when the framework instance is first initialized. The default value is "`none`".
-* `felix.cache.rootdir` \- Sets the root directory to use to calculate the bundle cache directory for relative directory names. If `org.osgi.framework.storage` is set to a relative name, by default it is relative to the current working directory. If this property is set, then it will be calculated as being relative to the specified root directory.
-* `felix.cache.bufsize` \- Sets the buffer size to be used by the cache; the default value is 4096. The integer value of this string provides control over the size of the internal buffer of the disk cache for performance reasons.
-
-To be clear, if a relative bundle cache directory is specified then the absolute location of the bundle cache directory is computed like this: `$\{felix.cache.rootdir}+$\{org.osgi.framework.storage`}, where `felix.cache.rootdir` has the default value of the current working directory. If `$\{org.osgi.framework.storage`} is specified as absolute, then it is used as the location of the bundle cache. If the bundle cache directory does not exist, it is created.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-configuration-properties.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-configuration-properties.mdtext
deleted file mode 100644
index 21b7fe7..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-configuration-properties.mdtext
+++ /dev/null
@@ -1,82 +0,0 @@
-Title: Apache Felix Framework Configuration Properties
-
-* [Overview]({{ refs.-overview.path }})
-* [Framework configuration properties]({{ refs.-framework.path }})
-* [Launcher configuration properties]({{ refs.-launcher.path }})
-* [Mirgrating from earlier versions]({{ refs.-migrating.path }})
-* [Feedback]({{ refs.-feedback.path }})
-
-
-
-## Overview
-
-This document describes the various configuration properties related to the Apache Felix Framework. Technically, there are framework properties and launcher properties. If you are using the Felix Framework JAR file (i.e., `org.apache.felix.framework-x.y.x.jar`), then you can only use framework properties. On the other hand, if you are using the Felix Main launcher JAR (i.e., `felix.jar` or `org.apache.felix.main-x.y.z.jar`), then you can use both framework and launcher properties. This d [...]
-
-Note that the framework does not use system properties to find its configuration properties, it only consults the map passed into its constructor. In contrast to bundles, which use `BundleContext.getProperty()`, which exposes both configuration and system properties at execution time. In the case of overlap, the configuration properties override system properties. As a convenience, if you are using the Felix launcher, it will copy all configuration properties it finds in the system prope [...]
-
-
-
-## Framework configuration properties
-
-The following configuration properties are for the framework (properties starting with "`felix`" are specific to Felix, while those starting with "`org.osgi`" are standard OSGi properties):
-
-* `org.osgi.framework.executionenvironment` \- Sets the OSGi execution environment for the framework. The framework tries to set this to a reasonable default value. If you specify a value, it overrides the framework default. Refer to the OSGi specification for appropriate execution environment values.
-* `org.osgi.framework.storage` \- Sets the directory to use as the bundle cache; by default the bundle cache directory is `felix-cache` in the current working directory. The value should be a valid directory name. The directory name can be either absolute or relative. Relative directory names are relative to the current working directory. The specified directory will be created if it does not exist.
-* `felix.cache.rootdir` \- Sets the root directory used to calculate the bundle cache directory for relative directory names. If `org.osgi.framework.storage` is set to a relative name, by default it is relative to the current working directory. If this property is set, then it will be calculated as being relative to the specified root directory.
-* `org.osgi.framework.storage.clean` \- Determines whether the bundle cache is flushed. The value can either be "`none`" or "`onFirstInit`", where "`none`" does not flush the bundle cache and "`onFirstInit`" flushes the bundle cache when the framework instance is first initialized. The default value is "`none`".
-* `felix.cache.filelimit` \- The integer value of this string sets an upper limit on how many files the cache will open. The default value is zero, which means there is no limit. (Since 4.0)
-* `felix.cache.locking` \- Enables or disables bundle cache locking, which is used to prevent concurrent access to the bundle cache. This is enabled by default, but on older/smaller JVMs file channel locking is not available; set this property to `false` to disable it.
-* `felix.cache.bufsize` \- Sets the buffer size to be used by the cache; the default value is 4096. The integer value of this string provides control over the size of the internal buffer of the disk cache for performance reasons.
-* `org.osgi.framework.system.packages` \- Specifies a comma-delimited list of packages that should be exported via the System Bundle from the framework class loader. The framework will set this to a reasonable default. If the value is specified, it replaces any default value.
-* `org.osgi.framework.system.packages.extra` \- Specifies a comma-delimited list of packages that should be exported via the System Bundle from the framework class loader in addition to the packages in `org.osgi.framework.system.packages`. The default value is empty. If a value is specified, it is appended to the list of default or specified packages in `org.osgi.framework.system.packages`.
-* `org.osgi.framework.bootdelegation` \- Specifies a comma-delimited list of packages that should be made implicitly available to all bundles from the parent class loader. It is recommended not to use this property since it breaks modularity. The default value is empty.
-* `org.osgi.framework.bundle.parent` \- Specifies which class loader is used for boot delegation. Possible values are: `boot` for the boot class loader, `app` for the application class loader, `ext` for the extension class loader, and `framework` for the framework's class loader. The default is `boot`.
-* `felix.bootdelegation.implicit` \- Specifies whether the framework should try to guess when to implicitly boot delegate to ease integration with external code. The default value is `true`.
-* `felix.systembundle.activators` \- A `List` of `BundleActivator` instances that are started/stopped when the System Bundle is started/stopped. The specified instances will receive the System Bundle's `BundleContext` when invoked. (This property cannot be set in the configuration file since it requires instances; it can only be passed into Felix' constructor directly.)
-* `felix.log.logger` \- An instance of `org.apache.felix.framework.Logger` that the framework uses as its default logger. (This property cannot be set in the configuration file since it requires an instance; it can only be passed into Felix' constructor directly.)
-* `felix.log.level` \- An integer value indicating the degree of logging reported by the framework; the higher the value the more logging is reported. If zero ('0') is specified, then logging is turned off completely. The log levels match those specified in the OSGi Log Service (i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug). The default value is 1.
-* `org.osgi.framework.startlevel.beginning` \- The initial start level of the framework once it starts execution; the default value is 1.
-* `felix.startlevel.bundle` \- The default start level for newly installed bundles; the default value is 1.
-* `felix.service.urlhandlers` \- Flag to indicate whether to activate the URL Handlers service for the framework instance; the default value is `true`. Activating the URL Handlers service will result in the `URL.setURLStreamHandlerFactory()` and `URLConnection.setContentHandlerFactory()` being called.
-* `felix.native.processor.alias.<procName>` \- An alias for resolving native processor requirements new with R6. This can be used to add new or override existing processors. The <procName> represents the key for the processor architecture such as x86-64 (which may not contain spaces) then the property value is a comma delimited list of aliases such as x86\_64,amd64. EX felix.native.processor.alias.x86-64=x86\_64,amd64
-* `felix.native.osname.alias.<osName>` \- An alias for resolving native operating system requirements new with R6. This can be used to add new or override existing operating systems. The <osName> represents the key for the operating system such as windows7 (which may not contain spaces) then the property value is a comma delimited list of aliases such as Windows 7,win32. EX felix.native.osname.alias.windows7=Windows 7,win32
-
-
-
-## Launcher configuration properties
-
-The following configuration properties are for the launcher:
-
-* `felix.auto.deploy.dir` \- Specifies the auto-deploy directory from which bundles are automatically deployed at framework startup. The default is the `bundle/` directory of the current directory.
-* `felix.auto.deploy.action` \- Specifies a comma-delimited list of actions to be performed on bundle JAR files found in the auto-deploy directory. The possible actions are `install`, `update`, `start`, and `uninstall`. An undefined or blank value is equivalent to disabling auto-deploy processing; there is no default value, so this value must be defined to enable it.
-* `felix.auto.install.<n>` \- Space-delimited list of bundle URLs to automatically install when Felix is started, where `<n>` is the start level into which the bundle will be installed (e.g., `felix.auto.install.2`).
-* `felix.auto.start.<n>` \- Space-delimited list of bundle URLs to automatically install and start when Felix is started, where `<n>` is the start level into which the bundle will be installed (e.g., `felix.auto.start.2`).
-* `felix.shutdown.hook` \- Specifies whether the launcher should install a shutdown hook to cleanly shutdown the framework on process exit. The default value is `true`.
-
-
-
-## Migrating from Earlier Versions
-
-Apache Felix Framework `2.0.0` introduced significant configuration property changes. This section describes the differences from older versions of the framework.
-
-* *Removed*
-** `felix.embedded.execution` \- No longer needed, since the framework now never calls `System.exit()`; the creator of the framework is now always responsible for exiting the VM.
-** `felix.strict.osgi` \- No longer needed, since all non-specification features have been removed.
-** `felix.cache.dir` \- No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.
-** `felix.cache.profile` \- No longer needed, since the framework no longer uses bundle cache profiles for saving sets of bundles.
-** `felix.fragment.validation` \- No longer needed, since the framework supports fragments.
-* *Renamed*
-** `felix.cache.profiledir` \- The equivalent of this property is now named `org.osgi.framework.storage`.
-** `felix.startlevel.framework` \- The equivalent of this property is now named `org.osgi.framework.startlevel.beginning`.
-* *Introduced*
-** `org.osgi.framework.system.packages.extra` \- New property, as described above, added to align with standard framework API.
-** `org.osgi.framework.storage.clean` \- New property, as described above, added to align with standard framework API.
-** `felix.cache.rootdir` \- Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.
-
-For the most part, these changes are minor and previous behavior achieved from older configuration properties is either easily attained with the new properties or no longer necessary.
-
-
-
-## Feedback
-
-Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-faq.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-faq.mdtext
deleted file mode 100644
index 20be5cb..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-faq.mdtext
+++ /dev/null
@@ -1,60 +0,0 @@
-Title: Apache Felix Framework Frequently Asked Questions
-
-[TOC]
-
-## Is the Felix framework compliant with the OSGi specification?
-
-Refer to the [Apache Felix Framework OSGi R4.2 CT Results]({{ refs.apache-felix-framework-osgi-r4-2-ct-results.path }}) document.
-
-## If I use bundles from Felix, will my application be tied to the Felix framework?
-
-See the answer in the [OSGi FAQ]({{ refs.apache-felix-osgi-faq-felix-dependencies.path }}).
-
-## When I update my bundle, why are my bundle's old classes still being used?
-
-See the answer in the [OSGi FAQ]({{ refs.apache-felix-osgi-faq-bundle-not-updated.path }}).
-
-## Why do I get an "Unknown protocol: http" exception when I run Felix on a non-Sun JRE?
-
-Felix installs the URL Handlers service by default. If you do not want this service you can disable it, by setting the `felix.service.urlhandlers` property to `false` in the `config.properties` file. It is not recommended to disable this, but the main reason for doing so it because the URL Handlers implementation invokes methods to set the singleton factories for URL stream and content handler factories. Assuming that you want to use URL Handlers service, you must configure it if you are [...]
-
-The URL Handlers service extends the standard Java URL stream and content handler mechanism to work in an OSGi environment. The way that built-in URL protocol and content handlers are discovered is by probing packages for the appropriate classes to handle the protocol/content. For example, the default package for Sun protocol handlers is:
-
-
- sun.net.www.protocol
-
-
-If someone tries to create a URL for the "http" protocol, then the class to handle the protocol will be:
-
-
- sun.net.www.protocol.http.Handler
-
-
-A similar process is followed for content handlers, whose default package is:
-
-
- sun.net.www.content
-
-
-If you are running on a VM that is different than Sun's, then you must determine what are the default packages used for its protocol and content handlers. Once you know this information, then you can configure Felix to use those packages instead of the default one. You can configure Felix by setting the following system properties:
-
-
- java.protocol.handler.pkgs
-
-
-and
-
-
- java.content.handler.pkgs
-
-
-The value of these properties is a list of "|" delimited package names to be searched for protocol and content handlers, respectively. See the Java documentation for [stream](http://java.sun.com/javase/6/docs/api/java/net/URL.html#URL(java.lang.String,%20java.lang.String,%20int,%20java.lang.String)) and [content|http://java.sun.com/javase/6/docs/api/java/net/URLConnection.html#getContent()] handlers for more information.
-
-There are two ways to set these system properties. The first way is using the standard `-D<property>=<value>` syntax when executing `java` or if you are using Felix' standard `Main.java` launcher, you can put the system properties into the `conf/system.properties` file so that they get set automatically each time you execute Felix.
-
-## What is the daemon status of framework created threads?
-
-The framework creates a few threads for handling specific tasks, such as event delivery or handling start level change requests. All framework threads are explicitly started as daemon threads except the event dispatcher thread. The logic behind this is that the event dispatcher thread should exit when it is done delivering events. However, if an application is hosting an instance of the framework, it is possible to make the event dispatcher thread a daemon by starting your framework inst [...]
-
-For bundle developers, it is probably best to explicitly define any created threads as daemon or non-daemon to avoid any ambiguity.
-
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-launching-and-embedding.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-launching-and-embedding.mdtext
deleted file mode 100644
index ea7c567..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-launching-and-embedding.mdtext
+++ /dev/null
@@ -1,784 +0,0 @@
-Title: Apache Felix Framework Launching and Embedding
-
-*\[This document describes framework launching introduced in Felix Framework 2.0.0 and continuing with the latest releases; it is incompatible with older versions of the Felix framework.\]({{ refs.this-document-describes-framework-launching-introduced-in-felix-framework-2-0-0-and-continuing-with-the-latest-releases-it-is-incompatible-with-older-versions-of-the-felix-framework.path }})*
-
-* [Introduction]({{ refs.-introduction.path }})
-* [OSGi Launching and Embedding API Overview]({{ refs.-overview.path }})
-** [Creating and Configuring the Framework Instance]({{ refs.-creating-and-configuring.path }})
-** [Starting the Framework Instance]({{ refs.-starting-instance.path }})
-** [Stopping the Framework Instance]({{ refs.-stopping-instance.path }})
-* [Launching Felix]({{ refs.-launching.path }})
-** [Standard Felix Launcher]({{ refs.-standard-launcher.path }})
-** [Custom Felix Launcher]({{ refs.-custom-launcher.path }})
-* [Embedding Felix]({{ refs.-embedding.path }})
-** [Host/Felix Interaction]({{ refs.-host-interaction.path }})
-** [Providing Host Application Services]({{ refs.-host-services.path }})
-** [Using Services Provided by Bundles]({{ refs.-host-service-usage.path }})
-*** [Using Bundle Services via Reflection]({{ refs.-service-reflection.path }})
-*** [Other Approaches]({{ refs.-service-other.path }})
-* [Caveat]({{ refs.-caveat.path }})
-* [Feedback]({{ refs.-feedback.path }})
-
-
-
-# Introduction
-
-The Apache Felix Framework is intended to be easily launchable and embeddable. For example, the Felix framework implementation avoids the use of system properties for configuration, since these are globals and can cause interference if multiple framework instances are created in the same VM. The framework also tries to multiplex singleton facilities, like the URL stream handler factory. The goal is to make it possible to use the framework in a variety of scenarios; however, this is still [...]
-
-
-
-# OSGi Launching and Embedding API Overview
-
-The Felix framework is implemented by the `org.apache.felix.framework.Felix` class or just `Felix` for short. As part of the R4.2 OSGi specification, the launching and embedding API of the OSGi framework has been standardized. The approach is to have the framework implement the `org.osgi.framework.launch.Framework` interface, which extends the `org.osgi.framework.Bundle` interface. These interfaces provide the necessary means to launch and manage framework instances. The `Bundle` interfa [...]
-
-
- public interface Bundle
- {
- BundleContext getBundleContext();
- long getBundleId();
- URL getEntry(String name);
- Enumeration getEntryPaths(String path);
- Enumeration findEntries(String path, String filePattern, boolean recurse);
- Dictionary getHeaders();
- Dictionary getHeaders(String locale);
- long getLastModified();
- String getLocation();
- URL getResource(String name);
- Enumeration getResources(String name) throws IOException;
- ServiceReference[] getRegisteredServices();
- ServiceReference[] getServicesInUse();
- int getState();
- String getSymbolicName();
- Version getVersion();
- boolean hasPermission(Object obj);
- Class loadClass(String name) throws ClassNotFoundException;
- void start() throws BundleException;
- void stop() throws BundleException;
- void uninstall() throws BundleException;
- void update() throws BundleException;
- void update(InputStream is) throws BundleException;
- }
-
-
-The `Framework` interface is defined as:
-
-
- public interface Framework extends Bundle
- {
- void init();
- FrameworkEvent waitForStop(long timeout);
- }
-
-
-To actually construct a framework instance, the R4.2 specification defines the `FrameworkFactory` interface:
-
-
- public interface FrameworkFactory
- {
- Framework newFramework(Map config);
- }
-
-
-The framework factory can be used to create configured framework instances. It is obtained following the standard `META-INF/services` approach.
-
-
-
-## Creating and Configuring the Framework Instance
-
-You use the framework factory to construct and configure a framework instance (or by directly instantiating the Felix class). The configuration map may contain any of the framework configuration properties listed in the [Apache Felix Framework Configuration Properties]({{ refs.apache-felix-framework-configuration-properties.path }}) document, not the launcher configuration properties. The configuration map is copied and the keys are treated as case insensitive. You are not able to change [...]
-
-<div class="warning" markdown="1">
-**WARNING**
-Felix configuration properties have change considerably starting from `1.4.0`; if you are upgrading from an earlier version, the [configuration property document]({{ refs.apache-felix-framework-configuration-properties-migrating.path }}) describes the configuration property changes.
-</div>
-
-
-
-## Starting the Framework Instance
-
-The `start()` method is used to start the framework instance. If the `init()` method was not invoked prior to calling `start()`, then it is invoked by `start()`. The two methods result in two different framework state transitions:
-
-* `init()` results in the framework instance in the `Bundle.STARTING` state.
-* `start()` results in the framework instance in the `Bundle.ACTIVE` state.
-
-The `init()` method is necessary since the framework does not have a `BundleContext` when it is first created, so a transition to the `Bundle.STARTING` state is required to acquire its context (via `Bundle.getBundleContext()`) for performing various tasks, such as installing bundles. Note that the Felix framework also provides the `felix.systembundle.activators` property that serves a similar purpose, but is not standard. After the `init()` method completes, the follow actions have been [...]
-
-* Event handling is enabled.
-* The security manager is installed if it is enabled.
-* The framework is set to start level 0.
-* All bundles in the bundle caches are reified and their state is set to `Bundle.INSTALLED`.
-* The framework gets a valid `BundleContext`.
-* All framework-provided services are made available (e.g., PackageAdmin, StartLevel, etc.).
-* The framework enters the `Bundle.STARTING` state.
-
-A call to `start()` is necessary to start the framework instance, if the `init()` method is invoked manually. Invoking `init()` or `start()` on an already started framework as no effect.
-
-
-
-## Stopping the Framework Instance
-
-To stop the framework instance, invoke the `stop()` method, which will asynchronously stop the framework. To know when the framework has finished its shutdown sequence, use the `waitForStop()` method to wait until it is complete. A stopped framework will be in the `Bundle.RESOLVED` state. It is possible to restart the framework, using the normal combination of `init()`/`start()` methods as previously described.
-
-
-
-# Launching a Framework
-
-Launching a framework is fairly simple and involves only four steps:
-
-1. Define some configuration properties.
-1. Obtain framework factory.
-1. Use factory to create framework with the configuration properties.
-1. Invoke the `Framework.start()` method.
-
-In reality, the first step is optional, since all properties will have reasonable defaults, but if you are creating a launcher you will generally want to more than that, such as automatically installing and starting bundles when you start the framework instance. The default Felix launcher defines reusable functionality to automatically install and/or start bundles upon framework startup; see the [usage document]({{ refs.apache-felix-framework-usage-documentation-configuring-felix.path }} [...]
-
-The remainder of this section describes how the standard Felix launcher works as well as how to create a custom launcher.
-
-
-
-## Standard Felix Framework Launcher
-
-The standard Felix framework launcher is very simple and is not intended to solve every possible requirement; it is intended to work for most standard situations. Most special launching requirements should be resolved by creating a custom launcher. This section describes how the standard launcher works. The following code represents the complete `main()` method of the standard launcher, each numbered comment will be described in more detail below:
-
-
- public static void main(String[] args) throws Exception
- {
- // (1) Check for command line arguments and verify usage.
- String bundleDir = null;
- String cacheDir = null;
- boolean expectBundleDir = false;
- for (int i = 0; i < args.length; i++)
- {
- if (args[i].equals(BUNDLE_DIR_SWITCH))
- {
- expectBundleDir = true;
- }
- else if (expectBundleDir)
- {
- bundleDir = args[i];
- expectBundleDir = false;
- }
- else
- {
- cacheDir = args[i];
- }
- }
-
- if ((args.length > 3) || (expectBundleDir && bundleDir == null))
- {
- System.out.println("Usage: [-b <bundle-deploy-dir>] [<bundle-cache-dir>]");
- System.exit(0);
- }
-
- // (2) Load system properties.
- Main.loadSystemProperties();
-
- // (3) Read configuration properties.
- Properties configProps = Main.loadConfigProperties();
- if (configProps == null)
- {
- System.err.println("No " + CONFIG_PROPERTIES_FILE_VALUE + " found.");
- configProps = new Properties();
- }
-
- // (4) Copy framework properties from the system properties.
- Main.copySystemProperties(configProps);
-
- // (5) Use the specified auto-deploy directory over default.
- if (bundleDir != null)
- {
- configProps.setProperty(AutoProcessor.AUTO_DEPLOY_DIR_PROPERY, bundleDir);
- }
-
- // (6) Use the specified bundle cache directory over default.
- if (cacheDir != null)
- {
- configProps.setProperty(Constants.FRAMEWORK_STORAGE, cacheDir);
- }
-
- // (7) Add a shutdown hook to clean stop the framework.
- String enableHook = configProps.getProperty(SHUTDOWN_HOOK_PROP);
- if ((enableHook == null) || !enableHook.equalsIgnoreCase("false"))
- {
- Runtime.getRuntime().addShutdownHook(new Thread("Felix Shutdown Hook") {
- public void run()
- {
- try
- {
- if (m_fwk != null)
- {
- m_fwk.stop();
- m_fwk.waitForStop(0);
- }
- }
- catch (Exception ex)
- {
- System.err.println("Error stopping framework: " + ex);
- }
- }
- });
- }
-
- try
- {
- // (8) Create an instance and initialize the framework.
- FrameworkFactory factory = getFrameworkFactory();
- m_fwk = factory.newFramework(configProps);
- m_fwk.init();
- // (9) Use the system bundle context to process the auto-deploy
- // and auto-install/auto-start properties.
- AutoProcessor.process(configProps, m_fwk.getBundleContext());
- // (10) Start the framework.
- m_fwk.start();
- // (11) Wait for framework to stop to exit the VM.
- m_fwk.waitForStop(0);
- System.exit(0);
- }
- catch (Exception ex)
- {
- System.err.println("Could not create framework: " + ex);
- ex.printStackTrace();
- System.exit(0);
- }
- }
-
-
-The general steps of the standard launcher are quite straightforward:
-
-1. The launcher supports setting the auto-deploy directory (with the `-b` switch) and setting the bundle cache path with a single argument, so check for this and issue a usage message it there are more than one arguments.
-1. Load any system properties specified in the `system.properties` file; this file is typically located in the `conf/` directory of the Felix installation directory, but it can be specified directly using the `felix.system.properties` system property. This file is not needed to launch Felix and is provided merely for convenience when system properties must be specified. The file is a standard Java properties file, but it also supports property substitution using `$\{<property-name`} synt [...]
-1. Load any configuration properties specified in the `config.properties` file; this file is typically located in the `conf/` directory of the Felix installation directory, but it can be specified directly using the `felix.config.properties` system property. This file is used to configure the framework instance created by the launcher. The file is a standard Java properties file, but it also supports property substitution using "`$\{<property-name>`}" syntax. Property substitution can be [...]
-1. For convenience, any configuration properties that are set as system properties are copied into the set of configuration properties. This provide an easy way to add to or override configuration properties specified in the `config.properties` file, since the Felix instance will never look at system properties for configuration.
-1. If the `-b` switch was used to specify an auto-deploy directory, then use that to set the value of `felix.auto.deploy.dir`.
-1. If a single command-line argument is specified, then use that to set the value of `org.osgi.framework.storage`; relative paths are relative to the current directory unless the `felix.cache.rootdir` property is set.
-1. Add a shutdown hook to cleanly stop the framework, unless the hook is disabled.
-1. Create a framework instance using the `FrameworkFactory` passing in the configuration properties, then initialize the factory instance; see the [custom launcher example]({{ refs.-custom-launcher.path }}) below to see how the META-INF/services `FrameworkFactory` is obtained.
-1. Use `org.apache.felix.main.AutoProcessor`, which will automatically deploy any bundles in the auto-deploy directory as well as bundles specified in the `felix.auto.install` and `felix.auto.start` configuration properties during framework startup to automatically install and/or start bundles; see the usage document for more information [configuration properties]({{ refs.apache-felix-framework-usage-documentation-configuring-framework.path }}) and [bundle auto-deploy|Apache Felix Framew [...]
-1. Invoke `waitForStop()` to wait for the framework to stop to force the VM to exit; this is necessary because the framework never calls `System.exit()` and some libraries (e.g., Swing) create threads that will not allow the VM to exit.
-
-The framework is not active until the `start()` method is called. If no shell bundles are installed and started or if there is difficulty locating the shell bundles specified in the auto-start property, then it will appear as if the framework is hung, but it is actually running without any way to interact with it since the shell bundles provide the only means of interaction.
-
-
-
-## Custom Framework Launcher
-
-This section creates a bare-bones launcher to demonstrate the minimum requirements for creating an interactive launcher for the Felix framework. This example uses the standard Gogo shell bundles for interactivity, but any other bundles could be used instead. This example launcher project has the following directory structure:
-
-
- launcher/
- lib/
- org.apache.felix.main-3.0.0.jar
- bundle/
- org.apache.felix.gogo.command-0.6.0.jar
- org.apache.felix.gogo.runtime-0.6.0.jar
- org.apache.felix.gogo.shell-0.6.0.jar
- src/
- example/
- Main.java
-
-
-The `lib/` directory contains Felix' main JAR file, which also contains the OSGi core interfaces. The main JAR file is used so that we can reuse the default launcher's auto-install/auto-start configuration property handling; if these capabilities are not needed, then it would be possible to use the framework JAR file instead of the main JAR file. The `bundle/` directory contains the shell service and textual shell interface bundles that will be used for interacting with the framework ins [...]
-
-
- package example;
-
- import java.io.*;
- import org.osgi.framework.launch.*;
- import org.apache.felix.main.AutoProcessor;
-
- public class Main
- {
- private static Framework m_fwk = null;
-
- public static void main(String[] argv) throws Exception
- {
- // Print welcome banner.
- System.out.println("\nWelcome to My Launcher");
- System.out.println("======================\n");
-
- try
- {
- m_fwk = getFrameworkFactory().newFramework(null);
- m_fwk.init();
- AutoProcessor.process(null, m_fwk.getBundleContext());
- m_fwk.start();
- m_fwk.waitForStop(0);
- System.exit(0);
- }
- catch (Exception ex)
- {
- System.err.println("Could not create framework: " + ex);
- ex.printStackTrace();
- System.exit(-1);
- }
- }
-
- private static FrameworkFactory getFrameworkFactory() throws Exception
- {
- java.net.URL url = Main.class.getClassLoader().getResource(
- "META-INF/services/org.osgi.framework.launch.FrameworkFactory");
- if (url != null)
- {
- BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream()));
- try
- {
- for (String s = br.readLine(); s != null; s = br.readLine())
- {
- s = s.trim();
- // Try to load first non-empty, non-commented line.
- if ((s.length() > 0) && (s.charAt(0) != '#'))
- {
- return (FrameworkFactory) Class.forName(s).newInstance();
- }
- }
- }
- finally
- {
- if (br != null) br.close();
- }
- }
-
- throw new Exception("Could not find framework factory.");
- }
- }
-
-
-This launcher relies on the default behavior of `AutoProcessor` to automatically deploy the shell bundles. This simple, generic launcher provides a good starting point if the default Felix launcher is not sufficient. Since very few configuration properties are specified, the default values are used. For the bundle auto-deploy directory, "`bundle`" in the current directory is used, while for the framework bundle cache, "`felix-cache`" in the current directory is used.
-
-By breaking down the above source code into small chunks, it is quite easy to see what is going on.
-
-
- m_fwk = getFrameworkFactory().newFramework(null);
- m_fwk.init()
-
-
-These steps get a the framework factory service and use it to create a framework instance with a default configuration. Once the framework instance is created, it is initialized with `init()`.
-
-
- AutoProcessor.process(null, m_fwk.getBundleContext());
-
-
-The `AutorProcessor` will automatically deploy bundles in the auto-deploy directory and any referenced from the auto-install/start properties. Since we are using an empty configuration, the auto-deploy directory is the `bundle` directory in the current directory and there are no auto properties. Therefore, in this case, the shell bundles will be installed.
-
-
- m_fwk.start();
- m_fwk.waitForStop(0);
- System.exit(0);
-
-
-These final steps start the framework and cause the launching application thread to wait for the framework to stop and when it does the launching thread calls `System.exit()` to make sure the VM actually exits.
-
-
- private static FrameworkFactory getFrameworkFactory() throws Exception
- {
- ...
- }
-
-
-This method retrieves the framework factory service by doing a META-INF/services resource lookup, which it can use to obtain the concrete class name for the factory. If you are using Java 6, then you can use the `ServiceLoader` API in the JRE to further simplify the factory service lookup.
-
-The following command compiles the launcher when run from the root directory of the launcher project:
-
-
- javac -d . -classpath lib/org.apache.felix.main-3.0.0.jar src/example/Main.java
-
-
-After executing this command, an `example/` directory is created in the current directory, which contains the generated class file. The following command executes the simple launcher when run from the root directory of the launcher project:
-
-
- java -cp .:lib/org.apache.felix.main-3.0.0.jar example.Main
-
-
-After executing this command, a "`felix-cache/`" directory is created that contains the cached bundles, which were installed from the `bundle/` directory.
-
-
-
-# Embedding the Felix Framework
-
-Embedding the Felix framework into a host application is a simple way to provide a sophisticated extensibility mechanism (i.e., a plugin system) to the host application. Embedding the Felix framework is very similar to launching it as described above, the main difference is that the host application typically wants to interact with the framework instance and/or installed bundles/services from the outside. This is fairly easy to achieve, but there are some subtle issues to understand. Thi [...]
-
-
-
-## Host/Felix Interaction
-
-In the section on [launching]({{ refs.-launching.path }}) the framework above, the `Felix` class accepts a configuration property called `felix.systembundle.activators`, which is a list of bundle activator instances. These bundle activator instances provide a convenient way for host applications to interact with the Felix framework.
-
-<div class="warning" markdown="1">
-**WARNING**
-The `felix.systembundle.activators` configuration property is specific to the Felix framework implementation. If you want your code to work with other framework implementations, you should call `init()` on the framework instance and use `getBundleContext()` directly. Otherwise, the approach would be very similar.
-</div>
-
-Each activator instance passed into the constructor effectively becomes part of the system bundle. This means that the `start()`/`stop()` methods of each activator instance in the list gets invoked when the system bundle's activator `start()`/`stop()` methods gets invoked, respectively. Each activator instance will be given the system bundle's `BundleContext` object so that they can interact with the framework. Consider following snippet of a bundle activator:
-
-
- public class HostActivator implements BundleActivator
- {
- private BundleContext m_context = null;
-
- public void start(BundleContext context)
- {
- m_context = context;
- }
-
- public void stop(BundleContext context)
- {
- m_context = null;
- }
-
- public Bundle[] getBundles()
- {
- if (m_context != null)
- {
- return m_context.getBundles();
- }
- return null;
- }
- }
-
-
-Given the above bundle activator, it is now possible to embed the Felix framework into a host application and interact with it as the following snippet illustrates:
-
-
- public class HostApplication
- {
- private HostActivator m_activator = null;
- private Felix m_felix = null;
-
- public HostApplication()
- {
- // Create a configuration property map.
- Map config = new HashMap();
- // Create host activator;
- m_activator = new HostActivator();
- List list = new ArrayList();
- list.add(m_activator);
- configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
-
- try
- {
- // Now create an instance of the framework with
- // our configuration properties.
- m_felix = new Felix(config);
- // Now start Felix instance.
- m_felix.start();
- }
- catch (Exception ex)
- {
- System.err.println("Could not create framework: " + ex);
- ex.printStackTrace();
- }
- }
-
- public Bundle[] getInstalledBundles()
- {
- // Use the system bundle activator to gain external
- // access to the set of installed bundles.
- return m_activator.getBundles();
- }
-
- public void shutdownApplication()
- {
- // Shut down the felix framework when stopping the
- // host application.
- m_felix.stop();
- m_felix.waitForStop(0);
- }
- }
-
-
-Notice how the `HostApplication.getInstalledBundles()` method uses its activator instance to get access to the system bundle's context in order to interact with the embedded Felix framework instance. This approach provides the foundation for all interaction between the host application and the embedded framework instance.
-
-
-
-## Providing Host Application Services
-
-Providing services from the host application to bundles inside the embedded Felix framework instance follows the basic approach laid out in [above]({{ refs.-host-interaction.path }}). The main complication for providing a host application service to bundles is the fact that both the host application and the bundles must be using the same class definitions for the service interface classes. Since the host application cannot import classes from a bundle, this means that the service interfa [...]
-
-Consider the follow simple property lookup service:
-
-
- package host.service.lookup;
-
- public interface Lookup
- {
- public Object lookup(String name);
- }
-
-
-This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "`java -jar`" command. Now consider the following host application bundle activator, which will be used to register/unregister the property lookup service when the embedded framework instance starts/stops:
-
-
- package host.core;
-
- import java.util.Map;
- import org.osgi.framework.BundleActivator;
- import org.osgi.framework.BundleContext;
- import org.osgi.framework.ServiceRegistration;
- import host.service.lookup;
-
- public class HostActivator implements BundleActivator
- {
- private Map m_lookupMap = null;
- private BundleContext m_context = null;
- private ServiceRegistration m_registration = null;
-
- public HostActivator(Map lookupMap)
- {
- // Save a reference to the service's backing store.
- m_lookupMap = lookupMap;
- }
-
- public void start(BundleContext context)
- {
- // Save a reference to the bundle context.
- m_context = context;
- // Create a property lookup service implementation.
- Lookup lookup = new Lookup() {
- public Object lookup(String name)
- {
- return m_lookupMap.get(name);
- }
- };
- // Register the property lookup service and save
- // the service registration.
- m_registration = m_context.registerService(
- Lookup.class.getName(), lookup, null);
- }
-
- public void stop(BundleContext context)
- {
- // Unregister the property lookup service.
- m_registration.unregister();
- m_context = null;
- }
- }
-
-
-Given the above host application bundle activator, the following code snippet shows how the host application could create an embedded version of the Felix framework and provide the property lookup service to installed bundles:
-
-
- package host.core;
-
- import java.util.List;
- import java.util.ArrayList;
- import java.util.Map;
- import java.util.HashMap;
- import host.service.lookup.Lookup;
- import org.apache.felix.framework.Felix;
- import org.apache.felix.framework.util.FelixConstants;
- import org.osgi.framework.Constants;
-
- public class HostApplication
- {
- private HostActivator m_activator = null;
- private Felix m_felix = null;
- private Map m_lookupMap = new HashMap();
-
- public HostApplication()
- {
- // Initialize the map for the property lookup service.
- m_lookupMap.put("name1", "value1");
-
- m_lookupMap.put("name2", "value2");
- m_lookupMap.put("name3", "value3");
- m_lookupMap.put("name4", "value4");
-
- // Create a configuration property map.
- Map configMap = new HashMap();
- // Export the host provided service interface package.
- configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
- "host.service.lookup; version=1.0.0");
- // Create host activator;
- m_activator = new HostActivator(m_lookupMap);
- List list = new ArrayList();
- list.add(m_activator);
- configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
-
- try
- {
- // Now create an instance of the framework with
- // our configuration properties.
- m_felix = new Felix(configMap);
- // Now start Felix instance.
- m_felix.start();
- }
- catch (Exception ex)
- {
- System.err.println("Could not create framework: " + ex);
- ex.printStackTrace();
- }
- }
-
- public void shutdownApplication()
- {
- // Shut down the felix framework when stopping the
- // host application.
- m_felix.stop();
- m_felix.waitForStop(0);
- }
- }
-
-
-Rather than having the host application bundle activator register the service, it is also possible for the the host application to simply get the bundle context from the bundle activator and register the service directly, but the presented approach is perhaps a little cleaner since it allows the host application to register/unregister the service when the system bundle starts/stops.
-
-
-
-## Using Services Provided by Bundles
-
-Using services provided by bundles follows the same general approach of using a host application bundle activator. The main complication for the host application using a service from a bundle is the fact that both the host application and the bundle must be using the same class definitions for the service interface classes. Since the host application cannot import classes from a bundle, this means that the service interface classes *must* be accessible on the class path, typically as par [...]
-
-Consider the following simple command service interface for which bundles provide implementations, such as might be used to create an extensible interactive shell:
-
-
- package host.service.command;
-
- public class Command
- {
- public String getName();
- public String getDescription();
- public boolean execute(String commandline);
- }
-
-
-This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "`java -jar`" command. Now consider the previously introduced host application bundle activator below, which simply provides access to the system bundle context:
-
-
- package host.core;
-
- import org.osgi.framework.BundleActivator;
- import org.osgi.framework.BundleContext;
-
- public class HostActivator implements BundleActivator
- {
- private BundleContext m_context = null;
-
- public void start(BundleContext context)
- {
- m_context = context;
- }
-
- public void stop(BundleContext context)
- {
- m_context = null;
- }
-
- public BundleContext getContext()
- {
- return m_context;
- }
- }
-
-
-With this bundle activator, the host application can use command services provided by bundles installed inside its embedded Felix framework instance. The following code snippet illustrates one possible approach:
-
-
- package host.core;
-
- import java.util.List;
- import java.util.ArrayList;
- import java.util.Map;
- import host.service.command.Command;
- import org.apache.felix.framework.Felix;
- import org.apache.felix.framework.util.FelixConstants;
- import org.apache.felix.framework.cache.BundleCache;
- import org.osgi.framework.Constants;
- import org.osgi.util.tracker.ServiceTracker;
-
- public class HostApplication
- {
- private HostActivator m_activator = null;
- private Felix m_felix = null;
- private ServiceTracker m_tracker = null;
-
- public HostApplication()
- {
- // Create a configuration property map.
- Map configMap = new HashMap();
- // Export the host provided service interface package.
- configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
- "host.service.command; version=1.0.0");
- // Create host activator;
- m_activator = new HostActivator();
- List list = new ArrayList();
- list.add(m_activator);
- configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
-
- try
- {
- // Now create an instance of the framework with
- // our configuration properties.
- m_felix = new Felix(configMap);
- // Now start Felix instance.
- m_felix.start();
- }
- catch (Exception ex)
- {
- System.err.println("Could not create framework: " + ex);
- ex.printStackTrace();
- }
-
- m_tracker = new ServiceTracker(
- m_activator.getContext(), Command.class.getName(), null);
- m_tracker.open();
- }
-
- public boolean execute(String name, String commandline)
- {
- // See if any of the currently tracked command services
- // match the specified command name, if so then execute it.
- Object[] services = m_tracker.getServices();
- for (int i = 0; (services != null) && (i < services.length); i++)
- {
- try
- {
- if (((Command) services[i]).getName().equals(name))
- {
- return ((Command) services[i]).execute(commandline);
- }
- }
- catch (Exception ex)
- {
- // Since the services returned by the tracker could become
- // invalid at any moment, we will catch all exceptions, log
- // a message, and then ignore faulty services.
- System.err.println(ex);
- }
- }
- return false;
- }
-
- public void shutdownApplication()
- {
- // Shut down the felix framework when stopping the
- // host application.
- m_felix.stop();
- m_felix.waitForStop(0);
- }
- }
-
-
-The above example is overly simplistic with respect to concurrency issues and error conditions, but it demonstrates the overall approach for using bundle-provided services from the host application.
-
-
-
-### Using Bundle Services via Reflection
-
-It possible for the host application to use services provided by bundles without having access to the service interface classes and thus not needing to put the service interface classes on the class path. To do this, the host application uses the same general approach to acquire the system bundle context object, which it can use to look up service objects. Using either an LDAP filter or the service interface class name, the host application can retrieve the service object and then use st [...]
-
-
-
-### Other Approaches
-
-The [Transloader](http://code.google.com/p/transloader/) project is another attempt at dealing with issues of classes loaded from different class loaders and may be of interest.
-
-
-
-# Caveat
-
-The code in this document has not been thoroughly tested nor even compiled and may be out of date with respect to the current Felix source code. If you find errors please report them so the that they can be corrected.
-
-
-
-## Feedback
-
-Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-usage-documentation.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-usage-documentation.mdtext
deleted file mode 100644
index c9f615e..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-framework/apache-felix-framework-usage-documentation.mdtext
+++ /dev/null
@@ -1,179 +0,0 @@
-Title: Apache Felix Framework Usage Documentation
-
-* [Downloading the Framework](#downloading-the-framework)
-* [Starting the Framework](#starting-the-framework)
-* [Framework Shell](#framework-shell)
- * [Installing Bundles](#installing-bundles)
- * [Web Proxy Issues when Installing Bundles](#web-proxy-issues-when-installing-bundles)
-* [Bundle Auto-Deploy](#bundle-auto-deploy)
-* [Configuring the Framework](#configuring-the-framework)
- * [System Property Substitution](#system-property-substitution)
-* [Configuring Bundles](#configuring-bundles)
-* [Feedback](#feedback)
-
-## Downloading the Framework
-
-Go to the [downloads]({{ refs.downloads.path }}) page and download the latest Felix framework distribution.
-
-
-
-## Starting the Framework
-
-Start the framework from the installation directory by typing:
-
-
- java -jar bin/felix.jar
-
-
-The framework launcher starts the framework and installs and starts all bundles contained in the `bundle` directory of the current directory. By default, the bundle directory contains shell-related bundles providing a textual user interface to interact with the framework. Bundles installed into the framework are copied into a bundle cache directory for subsequent executions. By default, the framework creates a cache directory, called `felix-cache`, in your current working directory. If y [...]
-
-
- java -jar bin/felix.jar <cache-path>
-
-
-Where `<cache-path>` is the path you want to use as the bundle cache. If you specify a relative cache path, then it will be treated as relative to the current working directory.
-
-<div class="info" markdown="1">
-<b>Useful Information</b><br/>
-Previous versions of the framework prompted for a profile name when executed. The profile name
-was used to create a directory inside <code>.felix/</code> in the user home directory. This
-approach allowed users to have different sets of bundles for different purposes, e.g., testing,
-production, etc. If this behavior is still desired, it is very easy to mimic. Modify
-<code>conf/config.properties</code> to include "<code>felix.cache.rootdir=${user.home}/.felix</code>".
-Now, if you start Felix with something like "<code>java -jar bin/felix.jar foo</code>", it will use
-"<code>${user.home}/.felix/foo/</code>" as the bundle cache directory, where
-"<code>${user.home}</code>" is automatically substituted with the appropriate system property by
-the launcher.
-</div>
-
-
-
-## Framework Shell
-
-The main way to interact with the framework is via the supplied Apache Felix Gogo shell. After starting the framework, type `help` into the shell to see the list of the available commands and `help <command-name>` to get help for a specific command.
-
-<div class="info" markdown="1">
-<b>Useful Information</b><br/>
-In Gogo, command names are made up of two parts: <code><scope>:<name></code>. This is similar
-to a fully qualified class name in Java and is used to avoid naming collisions. If the
-<code><name></code> portion of the command is unique, then you only need to type it. If not,
-then you must either type the full <code><scope>:<name></code> or arrange the scope search path accordingly.
-</div>
-
-To install bundles, use the `felix:install` command, which is described in more detail in the next [sub-section]({{ refs.-installing-bundles.path }}). To list installed bundles, use the `felix:lb` command. To stop the framework type `stop 0` to stop the System Bundle; any installed bundles will automatically be reloaded (and potentially restarted) the next time you launch with the associated cache.
-
-
-
-### Installing Bundles
-
-A bundle is the OSGi term for a component for the OSGi framework. A bundle is simply a JAR file containing a manifest and some combination of Java classes, embedded JAR files, native code, and resources. A bundle may provide some specific functionality for the user or it may implement a service that other bundles can use; bundles can only use functionality from other bundles through shared services and packages.
-
-The Felix framework distribution comes with three bundles, which are located in the `bundle/` directory of the framework distribution installation directory. These bundles include the Gogo Runtime (core command processing functionality), Gogo Shell (text-based shell user interface), Gogo Command (basic set of commands), and Bundle Repository (a bundle repository service). In addition to these bundles, the bundle repository provides access to other bundles for easy installation. The bundl [...]
-
-Before installing any bundles, it is important to understand how bundles are manually deployed into the framework. Bundles are deployed in two stages; first they are installed, then they are started. To install a bundle use the `felix:install` shell command followed by a bundle URL. For example, to install a `bundle.jar` bundle you type:
-
-
- felix:install file:/path/to/bundle/bundle.jar
-
-
-Once a bundle is installed, it can then be started by using the `felix:start` command and the bundle identifier of the desired bundle. The `felix:lb` command is used to list installed bundles and to obtain the bundle's identifier. The following Felix shell session illustrates how to start the `bundle.jar` bundle:
-
-
- g! install file:/path/to/bundle/bundle.jar
- g! lb
- START LEVEL 1
- ID|State |Level|Name
- 0|Active | 0|System Bundle (3.0.0)
- 1|Active | 1|Apache Felix Bundle Repository (1.6.2)
- 2|Active | 1|Apache Felix Gogo Command (0.6.0)
- 3|Active | 1|Apache Felix Gogo Runtime (0.6.0)
- 4|Active | 1|Apache Felix Gogo Shell (0.6.0)
- 5|Installed | 1|Example Bundle (1.0.0)
- g! start 5
- Hello from Bundle 5.
- g!
-
-
-The `felix:stop` command is used to stop a bundle and the `felix:uninstall` command is used to remove a bundle from the bundle cache. As an alternative to using the `felix:install` and `felix:start` commands explicitly, it is also possible to install and start a bundle in one step by using the `felix:start` command with a bundle URL.
-
-Bundles can be updated using the `felix:update` command. The update command allows you to specify an URL from which to retrieve the updated bundle, but if one is not specified it will try to update the bundle from the bundle's `Bundle-UpdateLocation` manifest attribute, if present, or the bundle's original location URL.
-
-<div class="info" markdown="1">
-<b>Useful Information</b><br/>
-When you use <code>felix:update</code> or <code>felix:uninstall</code>, the changes appear to take
-effect immediately, but in reality the changes are only partially enacted. If a bundle is updated
-or uninstalled and it was exporting packages, these packages are not removed until the framework
-is refreshed using the <code>PackageAdmin</code> service. The Felix shell offers a convenient
-<code>refresh</code> command for this purpose. This is the correct behavior as defined by the OSGi
-specification.
-</div>
-
-For an introduction to writing bundles and services, refer to the Felix bundle tutorial.
-
-
-
-### Web Proxy Issues when Installing Bundles
-
-If you use a proxy for Web access, then you may run into difficulty using the Gogo shell to install bundles from remote URLs. To remedy this situation, certain system properties must be set to make the framework work with your proxy. These properties are:
-
-* `http.proxyHost` \- the name of the proxy host.
-* `http.proxyPort` \- the port of the proxy host.
-* `http.proxyAuth` \- the user name and password to use when connecting to the proxy; this string should be the user name and password separated by a colon (e.g., `rickhall:mypassword`).
-
-These system properties can be set directly on the command line when starting the JVM using the standard "`\-D<prop>=<value>`" syntax
-or you can put them in the `lib/system.properties` file of your Felix installation; see the next section on [configuring Felix](#configuring-the-framework)
-for more information.
-
-
-
-## Bundle Auto-Deploy
-
-To minimize the amount of configuration necessary to install bundles when you launch the framework, the Felix launcher uses the concept of an "auto-deploy" directory. The Felix launcher deploys all bundles in the auto-deploy directory into the framework instance during startup. By default, the auto-deploy directory is "`bundle`" in the current directory, but it can be specified on the command line like this:
-
-
- java -jar bin/felix.jar -b /path/to/dir
-
-
-Specifying an auto-deploy directory replaces the default directory, it does not augment it. The framework distribution is configured to install and start bundles in the auto-deploy directory. Both the location of the auto-deploy directory and the deployment actions performed can be controlled by the following configuration properties, respectively:
-
-* `felix.auto.deploy.dir` \- Specifies the auto-deploy directory from which bundles are automatically deploy at framework startup. The default is the `bundle/` directory of the current directory.
-* `felix.auto.deploy.action` \- Specifies the auto-deploy actions to be performed on the bundle JAR files found in the auto-deploy directory. The possible actions are `install`, `update`, `start`, and `uninstall`. If no actions are specified, then the auto-deploy directory is not processed (i.e., it is disabled). There is no default value for this property, but the default `config.properties` file installed with the Felix framework distribution sets the value to: `install, start`
-
-The next section describes how to set and use configuration properties.
-
-
-
-## Configuring the Framework
-
-Both the Felix framework and the launcher use configuration properties to alter their default behavior. The framework can only be configured by passing properties into its constructor, but the launcher provides a mechanism to configure the framework via a property file. The framework launcher reads configuration properties from `conf/config.properties`. This file uses standard Java property file syntax.
-
-The launcher also supports setting system properties via the `conf/system.properties` file. This file is purely for convenience when you need to repeatedly set system properties when running the framework. While the framework itself does not look at system properties, the launcher does copy any framework configuration properties found in the system properties into the framework configuration map, also for your convenience.
-
-It is possible to specify different locations for these property files using the `felix.config.properties` and `felix.system.properties` system properties when executing the framework. For example:
-
-
- java -Dfelix.config.properties=file:/home/rickhall/config.properties -jar bin/felix.jar
-
-
-Configuration and system properties are accessible at run time via `BundleContext.getProperty()`, but configuration properties override system properties. For more information about available configuration properties, refer to the [Apache Felix Framework Configuration Properties]({{ refs.apache-felix-framework-configuration-properties.path }}) document. The Felix framework distribution contains a default `conf/config.properties`.
-
-
-
-### System Property Substitution
-
-It is possible to use system properties to specify the values of properties in the `conf/config.properties` file. This is achieved through system property substitution, which is instigated by using `$\{<property>\`} syntax, where `<property>` is the name of a system property to substitute. When the properties file is read, any such property values are substituted as appropriate. It is possible to have nested system property substitution, in which case the inner-most property is substitut [...]
-
-
-
-## Configuring Bundles
-
-Some bundles use properties to configure certain aspects of their behavior. It is a good idea, when implementing bundles, to parameterize them with properties where appropriate. To learn about the configuration options for specific bundles, refer to the documentation that accompanies them.
-
-Bundle properties may also be defined in the `conf/config.properties` property file. Any property placed in this file will be accessible via `BundleContext.getProperty()` at run time. The property file uses the standard Java property file syntax (i.e., attribute-value pairs). For information on changing the default location of this file, refer to the section on [configuring Felix](#configuring-the-framework).
-
-
-
-## Feedback
-
-Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org](mailto:users-subscribe@felix.apache.org);
-after subscribing, email questions or feedback to [users@felix.apache.org](mailto:users@felix.apache.org).
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-gogo.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-gogo.mdtext
deleted file mode 100644
index b789009..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-gogo.mdtext
+++ /dev/null
@@ -1,195 +0,0 @@
-Title: Apache Felix Gogo
-
-Apache Felix Gogo is a subproject of Apache Felix implementing a command line shell for OSGi. It is used in many OSGi runtimes and servers (Felix distro, Eclipse IDE, Apache Karaf, ...).
-
-## Overview
-
-The Gogo subproject consists of three bundles:
-
-- *runtime* \- implements the core command processing functionality.
-- *command* \- implements a set of basic commands.
-- *jline* \- Advanced textual user interface with features like completion and colors
-- *shell* \- provides a simple textual user interface to interact with the command processor.
-
-## Working with the sources
-
-You can find the [sources on apache svn](https://svn.apache.org/repos/asf/felix/trunk/gogo/) there is also [a mirror at github](https://github.com/apache/felix/tree/trunk/gogo).
-
-Clone
- git clone https://github.com/apache/felix
-
-Build
- cd gogo
- mvn clean install
-
-## Using Gogo with the Felix Framework
-
-Gogo is included as the default shell in the felix framework distribution. To use it, you just start the framework like normal:
-
- $ java -jar bin/felix.jar
- _______________
- Welcome to Apache Felix Gogo
-
- g!
-
-Gogo shell integration in the framework distribution is also discussed in the [framework usage document]({{ refs.apache-felix-framework-usage-documentation.path }})
-
-## Built in shell features
-
-- TAB
-
- Completion for commands and parameters
-
-- Cursor left, Cursor right
-
- Edit inside current line
-
-- Cursor up, Cursor down
-
- Scroll through history
-
-- Ctrl-C
-
- Interrupt execution of current command
-
-- Ctrl-D
-
- Exit the shell
-
-- Ctrl-R
-
- Search in history
-
-- *\[command1\]* | *\[command2\]*
-
- Pipe output of command1 as input of command2
-
-## Basic commands
-
-- cat *\[URI\]*
-
- Read URI and print to stdout
-
-- cd *\[path\]*
-
- Change working directory
-
-- diag *\[bundleid\]*
-
- Shows why a bundle is not working
-
-- help
-
- Show the available commands
-
-- help *\[command\]*
-
- Shows detailed help about a command
-
-- head *\[bundleid\]*
-
- Print bundle headers
-
-- history
-
- Shows the history of executed commands
-
-- inspect capability service *\[bundleid\]*
-
- Lists all services provided by a bundle
-
-- inspect requirement service *\[bundleid\]*
-
- Lists all services required by a bundle
-
-- install *\[URI\]*
-
- Install a bundle from file or URI
-
-- lb
-
- List bundles
-
-- *\[command1\]* | less
-
- Show output of command1 in a paged view
-
-- less *\[file\]*
-
- Show file in a paged view
-
-- ls *\[directory\]*
-
- Show directory contents
-
-- start *\[bundleid\]*
-
- Start the given bundle
-
-- stop *\[bundleid\]*
-
- Stop the given bundle
-
-- tac
-
- Capture stdin as string and optionally write to file
-
-- tail *\[file\]*
-
- Shows the last lines of a file. Using -f allows to follow the file changes.
-
-- uninstall *\[bundleid\]*
-
- Uninstall given bundle
-
-## Changing shell colors
-
-The colors of the command shell cane be adjusted by setting a property in an init script or directly on the shell.
-
-HIGHLIGHTER_COLORS = "rs=35:st=32:nu=32:co=32:va=36:vn=36:fu=94:bf=91:re=90"
-
-The property above forms a map from highlight type to ANSI color code.
-
-These are the highlight types
-
-- rs : Reserved words
-- st : Strings
-- nu : Numbers
-- co : Constants
-- va : Variable
-- vn : Variable name
-- fu : Function
-- bf : Bad function
-- un : Unknown
-- re : Repair
-
-The colors of the ls output can be adjusted using
-
-LS_COLORS = "dr=1;91:ex=1;92:sl=1;96:ot=34;43"
-
-The color types are these:
-
-- dr : Directory
-- ex : Executable
-- sl : Symbolic Link
-- ot : Other
-
-Last but not least grep can also be adjusted
-
-GREP_COLORS = "mt=1;31:fn=35:ln=32:se=36"
-
-Types:
-
-- mt : Hits in the text (sets both ms and mc)
-- ms : Matching text in selected line
-- mc : Matching text in context line
-- fn : File names
-- ln : Line numbers
-- se : Selected lines
-- sl : Whole selected line
-- cx : Context lines
-- rv : If set and match is inverted, the meaning of sl and cx is inverted
-
-## Origin in RFC 147
-
-Gogo is based on the OSGi RFC 147, which describes a standard shell for OSGi-based environments. See [RFC 147 Overview]({{ refs.rfc-147-overview.path }}) for more information. Unfortunately this RFC was never made a standard.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-gogo/rfc-147-overview.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-gogo/rfc-147-overview.mdtext
deleted file mode 100644
index 6f99cfb..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-gogo/rfc-147-overview.mdtext
+++ /dev/null
@@ -1,158 +0,0 @@
-Title: RFC 147 Overview
-
-The RFC-147 draft is not yet publicly available. It used to be called RFC-132, which can be found in an [early specification draft](http://www.osgi.org/download/osgi-4.2-early-draft.pdf)
-
-This is an overview of its main features:
-
-[TOC]
-
-## Standard way to implement and run commands for any OSGi 4.2 framework
-
-Commands are registered via service attributes, you don't have to register a specific service. This allows commands to be registered by existing services, just by adding the new attributes:
-
- :::java
- Dictionary<String, Object> dict = new Hashtable<String, Object>();
- dict.put(CommandProcessor.COMMAND_SCOPE, "shell");
- dict.put(CommandProcessor.COMMAND_FUNCTION, new String[] {"sleep", "grep"});
- context.registerService(name, service, dict);
-
-Scope is used to provide a namespace for commands. The commands above can be invoked as `shell:sleep` and `shell:grep`. If the scope is omitted (e.g. `sleep` and `grep`) then the first matching command is invoked.
-
-### Commands can have any signature
-
-Arguments are coerced to call the best matching method using reflection. A `CommandSession` argument is inserted if required:
-
- :::java
- public void sleep(long millis) throws InterruptedException{
- Thread.sleep(millis);
- }
-
- public void sleep(String[] args) throws Exception;
-
- public boolean grep(CommandSession session, String[] args) throws Exception;
-
-The `CommandSession` interface provides methods for executing commands and getting and setting session variables:
-
- :::java
- public interface org.apache.felix.service.command.CommandSession {
- Object execute(CharSequence commandline) throws Exception;
- Object get(String name);
- void put(String name, Object value);
- ...
- }
-
-### Easy to use interactively - no unnecessary syntax
-
-- basic commands
-
- :::shell
- g! echo hello world
- hello world
-
-- session variables
-
- :::shell
- g! msg = "hello world"
- g! echo $msg
- hello world
-
-- execution quotes `()` - similar to bash backquotes
-
- :::shell
- g! (bundle 1) location
- file:/Users/derek/Downloads/felix-framework-3.0.0/bundle/org.apache.felix.bundlerepository-1.6.2.jar
-
-### Lists, maps, pipes and closures
-
-- lists - `[]`
-
- :::shell
- g! list = [1 2 a b]
- 1
- 2
- a
- b
-
-- maps - `[]`
-
- :::shell
- g! map = [Jan=1 Feb=2 Mar=3]
- Jan 1
- Feb 2
- Mar 3
-
-- pipes - `|`
-
- :::shell
- g! bundles | grep gogo
- 2|Active | 1|org.apache.felix.gogo.command (0.6.0)
- 3|Active | 1|org.apache.felix.gogo.runtime (0.6.0)
- 4|Active | 1|org.apache.felix.gogo.shell (0.6.0)
-
-- closures - `{}`
-
- :::shell
- g! echo2 = { echo xxx $args yyy }
- g! echo2 hello world
- xxx hello world yyy
-
-### Leverages existing Java capabilities, via reflection
-
-- exception handling - console shows summary, but full context available
-
- :::shell
- g! start xxx
- E: Cannot coerce start[xxx] to any of [(Bundle)]
- g! $exception printstacktrace
- java.lang.IllegalArgumentException: Cannot coerce start[xxx] to any of [(Bundle)]
- at org.apache.felix.gogo.runtime.shell.Reflective.method(Reflective.java:162)
- at org.apache.felix.gogo.runtime.shell.Command.execute(Command.java:40)
- at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:211)
- at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:146)
- at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:91)
- ...
-
-- add all public methods on `java.lang.System` as commands:
-
- :::shell
- g! addcommand system (loadClass java.lang.System)
- g! system:getproperties
- sun.io.unicode.encodingUnicodeLittle
- java.version 1.5.0_19
- java.class.path bin/felix.jar
- java.awt.graphicsenvapple.awt.CGraphicsEnvironment
- user.language en
- sun.os.patch.level unknown
- os.version 10.6.2
- [snip]
-
-### Easy to implement and test commands without needing OSGi
-
-Command implementations don't need to reference any OSGi interfaces. They can use `System.in`, `System.out` and `System.err`, just as you would in a trivial Java application. The `ThreadIO` service transparently manages the singleton `System.out` etc, so that each thread sees the appropriate stream:
-
- :::java
- public void cat(String[] args) throws Exception {
- for (String arg : args) {
- IOUtil.copy(arg, System.out);
- }
- }
-
-### Normal commands can provide control primitives
-
- :::java
- public void each(CommandSession session, Collection<Object> list, Function closure) throws Exception {
- for (Object x : list) {
- closure.execute(session, null);
- }
- }
-
-then
-
- :::shell
- g! each [Jan Feb Mar] { echo $it | grep . }
- Jan
- Feb
- Mar
-
-**Note:** The default *echo* command _returns_ a String and does not write to System.out. Also, by default, the console prints the results of each command, so *echo* appears to behave as you would expect.
-However, the console does not see the *each* closure above, so the result of echo would not be seen. This is why it is piped into *grep*, as the _result_ of the command as well as its output is written to a pipeline.
\ No newline at end of file
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-healthchecks.mdtext b/modules/ROOT/pages/documentation/subprojects/apache-felix-healthchecks.mdtext
deleted file mode 100644
index f860123..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-healthchecks.mdtext
... 24520 lines suppressed ...