Github user neykov commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/113#discussion_r81115064
--- Diff: guide/java/bundle-dependencies.md ---
@@ -0,0 +1,118 @@
+---
+title: Handling Bundle Dependencies
+layout: website-normal
+---
+
+Some Java blueprints will require third party libraries. These need to be
made available to the
+Apache Brooklyn runtime. There are a number of ways this can be achieved.
+
+### Classic Mode: Dropins Folder
+
+In Brooklyn classic mode (i.e. when not using Karaf), jars can be added to
`./lib/dropins/`.
+After restarting Brooklyn, these will be available on the classpath.
+
+In Brooklyn classic mode, there is an embedded OSGi container. This is
used for installing
+libraries referenced in catalog items.
+
+### OSGi Bundles
+
+#### Introduction to OSGi Bundles
+
+An [OSGi bundle](https://en.wikipedia.org/wiki/OSGi#Bundles) is a jar file
with additional
+metadata in its manifest file. The `MANIFEST.MF` file contains the
symbolic name and version
+of the bundle, along with details of its dependencies and of the packages
it exports
+(which are thus visible to other bundles).
+
+The
[maven-bundle-plugin](http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html)
+is a convenient way of building OSGi bundles.
+
+#### OSGi Bundles Declared in Catalog Items
+
+Within a [catalog item]({{ site.path.guide}}/ops/catalog/), a list of URLs
can be supplied under
+`brooklyn.libraries`. Each URL should point to an OSGi bundle. This list
should include the OSGi
+bundle that has the Java code for your blueprint, and also the OSGi
bundles that it depends
+on (including all transitive dependencies).
+
+It is vital that these jars are built correctly as OSGi bundles, and that
all transitive
+dependencies are included. The bundles will be added to Karaf in the order
given, so a bundle's
+dependencies should be listed before the bundle(s) that depend on them.
+
+In the [GistGenerator example]({{
site.path.guide}}/java/defining-and-deploying.html), the
+[catalog.bom file]({{
site.path.guide}}/java/gist_generator/gist_generator.bom) included
+the URL of the dependency `org.eclipse.egit.github.core`. It also (before
that line) included
+its transitive dependency, which is a specific version of `gson`.
+
+For Java blueprint developers, this is often the most convenient way to
share a blueprint.
+
+Similarly for those wishing to use a new blueprint, this is often the
simplest mechanism: the
+dependencies are fully described in the catalog item, which makes it
convenient for deploying
+to Apache Brooklyn instances where there is not direct access to Karaf or
the file system.
+
+
+#### Adding Bundles and Features Directly to Karaf
+
+Bundles and features can be added manually, directly to Karaf.
+
+However, note this only affects the single Karaf instance. If running in
HA mode or if provisioning
+a new instance of Apache Brooklyn, the bundles will also need to be added
to these Karaf instances.
+
+
+##### Karaf Console
+
+Login to the [Karaf
console](https://karaf.apache.org/manual/latest/#_shell_console_basics)
+using `./bin/client`, and add the bundles and features as desired.
+
+Examples of some useful commands are shown below:
+
+{% highlight bash %}
+karaf@amp> bundle:install
http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.egit.github.core/2.1.5_1/org.apache.servicemix.bundles.egit.github.core-2.1.5_1.jar
--- End diff --
Add `-s` to start the bundle. While not required for most bundles it's nice
to have it in case the bundle does some fancy OSGi integration. Also starting
it will do additional validation on the dependencies.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
