Move documentation from Confluence to Git (#113)

* add project and modules documentation
* adjust documentation URLs
* format

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/)

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<ManifestEntry>(
+    bundleContext,
+    // bundle manifest scanner
+    new BundleManifestScanner(...),
+    // customizer for scanned entries
+    new BundleObserver<ManifestEntry>() {
+        public void addingEntries(Bundle bundle, List<ManifestEntry> entries) {
+            // your specific code, doing something with the manifest entries
+        }
+        public void removingEntries(Bundle bundle, List<ManifestEntry> 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<URL>(
+    bundleContext,
+    new BundleURLScanner(
+        "WEB-INF/",
+        "web.xml",
+        false // do not recurse
+    ),
+    new BundleObserver<URL>() {
+        public void addingEntries(Bundle bundle, List<URL> entries) {
+            // process web xml, as for example parsing and registering servlets
+        }
+
+        public void removingEntries(Bundle bundle, List<URL> entries) {
+            // revert processing of web xml
+        }
+    }
+).start();
+----

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.

pom.xml

@@ -16,8 +16,6 @@
   <name>OPS4J Pax Swissbox</name>
   <description>OPS4J Pax Swissbox - Utilities for OSGi</description>
 
-  <url>${pax.swissbox.wiki.url}</url>
-
   <scm>
     <connection>scm:git:https://github.com/ops4j/org.ops4j.pax.swissbox.git</connection>
     <developerConnection>scm:git:https://github.com/ops4j/org.ops4j.pax.swissbox.git</developerConnection>
@@ -31,7 +29,6 @@
   </issueManagement>
 
   <properties>
-    <pax.swissbox.wiki.url>https://ops4j1.jira.com/wiki/spaces/PAXSB</pax.swissbox.wiki.url>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <dependency.base.version>1.5.1</dependency.base.version>
     <dependency.slf4j.version>1.7.36</dependency.slf4j.version>
@@ -55,7 +52,7 @@
           <extensions>true</extensions>
           <configuration>
             <instructions>
-              <Bundle-DocURL>${pax.swissbox.wiki.url}</Bundle-DocURL>
+              <Bundle-DocURL>https://github.com/ops4j/org.ops4j.pax.swissbox</Bundle-DocURL>
               <Bundle-SymbolicName>${bundle.symbolicName}</Bundle-SymbolicName>
               <Import-Package>org.osgi.framework;version="[1.3,2)", *</Import-Package>
             </instructions>

samples/manifest-extender/pom.xml

@@ -15,9 +15,7 @@
   <packaging>bundle</packaging>
 
   <name>OPS4J Pax Swissbox :: Samples :: Manifest Extender</name>
-  <description>
-    OPS4J Pax Swissbox - Manifest entry extender sample.
-  </description>
+  <description>OPS4J Pax Swissbox - Manifest entry extender sample.</description>
 
   <properties>
     <bundle.symbolicName>org.ops4j.pax.swissbox.samples.em.extender</bundle.symbolicName>

samples/pom.xml

@@ -16,9 +16,7 @@
   <packaging>pom</packaging>
 
   <name>OPS4J Pax Swissbox :: Samples</name>
-  <description>
-    OPS4J Pax Swissbox Samples
-  </description>
+  <description>OPS4J Pax Swissbox Samples</description>
 
   <modules>
     <module>manifest-extender</module>