From df1226ce675931714fa08edd6a0d5019f6541fa1 Mon Sep 17 00:00:00 2001 From: Oliver Lietz Date: Sat, 2 Nov 2024 12:21:39 +0100 Subject: [PATCH] Move documentation from Confluence to Git (#113) * add project and modules documentation * adjust documentation URLs * format --- README.md | 2 +- .../modules/ROOT/pages/extender.adoc | 77 ++++++++++++++++++- documentation/modules/ROOT/pages/index.adoc | 7 +- pom.xml | 5 +- samples/manifest-extender/pom.xml | 4 +- samples/pom.xml | 4 +- 6 files changed, 86 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 18e391a..0141c4a 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,4 @@ Pax Swissbox is a collection of utilities for OSGi applications and is used by various other OPS4J projects. -* [Documentation](https://ops4j1.jira.com/wiki/spaces/PAXSB) +* [Documentation](https://ops4j.github.io/pax-swissbox/) diff --git a/documentation/modules/ROOT/pages/extender.adoc b/documentation/modules/ROOT/pages/extender.adoc index b884022..684e11a 100644 --- a/documentation/modules/ROOT/pages/extender.adoc +++ b/documentation/modules/ROOT/pages/extender.adoc @@ -1,4 +1,79 @@ = Pax Swissbox Extender :navtitle: Extender -Utilities related to extender pattern. +Utilities related to https://enroute.osgi.org/FAQ/400-patterns.html#extender-pattern[extender pattern]. + +== `BundleManifestScanner` + +You should use the `BundleManifestScanner` if you wish to implement an extender that is triggered by existence of specific entries in bundle manifest (`META-INF/MANIFEST.MF`). + +Usually in your extender `BundleActivator` you will create and start an instance of `BundleWatcher` by passing in a `BundleManifestScanner` and your extender specific `BundleObserver`. + +[source, java] +---- +new BundleWatcher( + bundleContext, + // bundle manifest scanner + new BundleManifestScanner(...), + // customizer for scanned entries + new BundleObserver() { + public void addingEntries(Bundle bundle, List entries) { + // your specific code, doing something with the manifest entries + } + public void removingEntries(Bundle bundle, List entries) { + // revert actions (if required) + } + } +); +---- + +=== `BundleManifestScanner` + +This scanner takes the starting bundle manifest entries and makes use of provided `ManifestFilter` to find out if the current bundle manifest contains expected entries. +If there are any entries matched by the manifest filter it will create for each one a `ManifestEntry` which is a simple pair between manifest header name and value. +Below is an example of creating a `BundleManifestScanner` that uses a regular expression based manifest filter: + +[source, java] +---- +new BundleManifestScanner( + new RegexKeyManifestFilter( + "Bundle-.*" + ) +); +---- + +=== `ManifestFilter` + +Manifest filters scope is to filter the manifest entries to the set required by your extender. +You can implement your own filter and/or make use of the built-in ones: + +* `RegexKeyManifestFilter` — matches manifest headers name against a regular expression +* ... more to come + +== `BundleURLScanner` + +You should use the `BundleURLScanner` if you wish to implement an extender that is triggered by existence of specific files or directories in bundles. + +=== Example WAR Extender + +The following is an example of how you can implement an extender bundle for war files: + +---- +new BundleWatcher( + bundleContext, + new BundleURLScanner( + "WEB-INF/", + "web.xml", + false // do not recurse + ), + new BundleObserver() { + public void addingEntries(Bundle bundle, List entries) { + // process web xml, as for example parsing and registering servlets + } + + public void removingEntries(Bundle bundle, List entries) { + // revert processing of web xml + } + } +).start(); +---- diff --git a/documentation/modules/ROOT/pages/index.adoc b/documentation/modules/ROOT/pages/index.adoc index 8b72505..97fd3d6 100644 --- a/documentation/modules/ROOT/pages/index.adoc +++ b/documentation/modules/ROOT/pages/index.adoc @@ -1,4 +1,9 @@ = Pax Swissbox :navtitle: Pax Swissbox -Utilities for OSGi +== Utilities for OSGi + +Pax Swissbox is a set of utilities targeting OSGi and the project emerged as means for re-usage within Pax projects. +But, as Pax Swissbox artifacts are generic, they can be reused outside Pax projects. +In order to minimize dependencies and improve modularity Pax Swissbox is split in very fine-grained bundles that you can use individually. +Pax Swissbox artifacts are meant to be embedded (wrapped) in your bundle (easy to achieve using Maven Bundle Plugin), but you can use them as standalone bundles. diff --git a/pom.xml b/pom.xml index 4f708f5..d365755 100644 --- a/pom.xml +++ b/pom.xml @@ -16,8 +16,6 @@ OPS4J Pax Swissbox OPS4J Pax Swissbox - Utilities for OSGi - ${pax.swissbox.wiki.url} - scm:git:https://github.com/ops4j/org.ops4j.pax.swissbox.git scm:git:https://github.com/ops4j/org.ops4j.pax.swissbox.git @@ -31,7 +29,6 @@ - https://ops4j1.jira.com/wiki/spaces/PAXSB UTF-8 1.5.1 1.7.36 @@ -55,7 +52,7 @@ true - ${pax.swissbox.wiki.url} + https://github.com/ops4j/org.ops4j.pax.swissbox ${bundle.symbolicName} org.osgi.framework;version="[1.3,2)", * diff --git a/samples/manifest-extender/pom.xml b/samples/manifest-extender/pom.xml index 6c7f520..1da4814 100644 --- a/samples/manifest-extender/pom.xml +++ b/samples/manifest-extender/pom.xml @@ -15,9 +15,7 @@ bundle OPS4J Pax Swissbox :: Samples :: Manifest Extender - - OPS4J Pax Swissbox - Manifest entry extender sample. - + OPS4J Pax Swissbox - Manifest entry extender sample. org.ops4j.pax.swissbox.samples.em.extender diff --git a/samples/pom.xml b/samples/pom.xml index 06ea209..c822722 100644 --- a/samples/pom.xml +++ b/samples/pom.xml @@ -16,9 +16,7 @@ pom OPS4J Pax Swissbox :: Samples - - OPS4J Pax Swissbox Samples - + OPS4J Pax Swissbox Samples manifest-extender