[3/4] brooklyn-docs git commit: Add documentation about how to control the catalog with Brooklyn in Karaf

[sv...@apache.org]

Add documentation about how to control the catalog with Brooklyn in Karaf

Closes #46
Merging changes from https://github.com/apache/brooklyn-docs/pull/46


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/dcbbc566
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/dcbbc566
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/dcbbc566

Branch: refs/heads/master
Commit: dcbbc566899cd5a606f5cfdd863fcf6ab522b5c3
Parents: 9e1f1c1
Author: Svetoslav Neykov <sv...@cloudsoftcorp.com>
Authored: Thu Apr 21 14:18:27 2016 +0100
Committer: Svetoslav Neykov <sv...@cloudsoftcorp.com>
Committed: Thu Apr 21 14:18:27 2016 +0100

----------------------------------------------------------------------
 guide/misc/osgi.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/dcbbc566/guide/misc/osgi.md
----------------------------------------------------------------------
diff --git a/guide/misc/osgi.md b/guide/misc/osgi.md
index 5482481..2af842e 100644
--- a/guide/misc/osgi.md
+++ b/guide/misc/osgi.md
@@ -71,9 +71,61 @@ Web console related configuration is done through the corresponding Karaf mechan
    * For other Jetty related configuration consult the Karaf and pax-web docs.
 
 
+## Catalog in Karaf
+
+
+With the traditional launcher, Brooklyn loads the initial contents of the catalog from a `default.catalog.bom` file
+as described in the section on [installation](/guide/ops/production-installation.html). Brooklyn finds Java 
+implementations to provide for certain things in blueprints (entities, enrichers etc.) by scanning the classpath. 
+
+In the OSGI world this approach is not used, as each bundle only has visibility of its own and its imported Java packages. 
+Instead, in Karaf, each bundle can declare its own `catalog.bom` file, in the root of the bundle,
+with the catalog declarations for any entities etc. that the bundle contains.
+
+For example, the `catalog.bom` file for Brooklyn's Webapp bundle looks like (abbreviated):
+
+    brooklyn.catalog:
+        version: ...
+        items:
+        - id: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
+          item:
+            type: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
+            name: Node.JS Application
+        ...
+        - id: resilient-bash-web-cluster-template
+          itemType: template
+          name: "Template: Resilient Load-Balanced Bash Web Cluster with Sensors"
+          description: |
+            Sample YAML to provision a cluster of the bash/python web server nodes,
+            with sensors configured, and a load balancer pointing at them,
+            and resilience policies for node replacement and scaling
+          item:
+            name: Resilient Load-Balanced Bash Web Cluster (Brooklyn Example)
+
+In the above YAML the first item declares that the bundle provides an entity whose type is
+`org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService`, and whose name is 'Node.JS Application'.  The second
+item declares that the bundle provides a template application, with id  `resilient-bash-web-cluster-template`, and
+includes a description for what this is.
+
+## Configuring the applications in the Catalog
+
+When running some particular deployment of Brooklyn it may not be desirable for the sample applications to appear in
+the catalog (for clarity, "application" here in the sense of an item with `itemType: template`).
+For example, if you have developed
+some bundle with your own application and added it to Karaf then you might want only your own application to appear in
+the catalog.
+
+Brooklyn contains a mechanism to allow you to configure what bundles will add their applications to the catalog.
+The Karaf configuration file `/etc/org.apache.brooklyn.core.catalog.bomscanner.cfg` contains two properties,
+one `whitelist` and the other `blacklist`, that bundles must satisfy for their applications to be added to the catalog.
+Each property value is a comma-separated list of regular expressions.  The symbolic id of the bundle must match one of
+the regular expressions on the whitelist, and not match any expression on the blacklist, if its applications
+are to be added to the bundle.  The default values of these properties are to admit all bundles, and forbid none.
+
 ## Caveats
 
 In the OSGi world specifying class names by string in Brooklyn's configuration will work only
 for classes living in Brooklyn's core modules. Raise an issue or ping us on IRC if you find
 a case where this doesn't work for you. For custom SecurityProvider implementations refer to the
 documentation of BrooklynLoginModule.
+