brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From neykov <...@git.apache.org>
Subject [GitHub] brooklyn-docs pull request #113: Improvements to java blueprint docs for OSG...
Date Thu, 29 Sep 2016 11:58:30 GMT
Github user neykov commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/113#discussion_r81120231
  
    --- 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
    +Bundle ID: 316
    +
    +karaf@amp> bundle:list -t 0 -s | grep github
    +316 | Resolved |  80 | 2.1.5.1                       | org.apache.servicemix.bundles.egit.github.core
    +
    +karaf@amp> bundle:headers org.apache.servicemix.bundles.egit.github.core
    +...
    +
    +karaf@amp> bundle:uninstall org.apache.servicemix.bundles.egit.github.core
    +{% endhighlight %}
    +
    +
    +##### Karaf Deploy Folder
    +
    +Karaf support [hot deployment](https://karaf.apache.org/manual/latest/#_deployers). There
are a 
    +set of deployers, such as feature and KAR deployers, that handle deployment of artifacts
added
    +to the `deploy` folder.
    +
    +Note that the Karaf console can give finer control (including for uninstall).
    +
    +
    +### Karaf KAR files
    +
    +[Karaf KAR](https://karaf.apache.org/manual/latest/kar) is an archive format (Karaf ARchive).
    +A KAR is a jar file (so a zip file), which contains a set of feature descriptors and
bundle jar files.
    +
    +This can be a useful way to bundle a more complex Java blueprint (along with its dependencies),
to
    +make it easier for others to install.
    +
    +A KAR file can be built using the 
    +[maven plugin org.apache.karaf.tooling:features-maven-plugin](https://karaf.apache.org/manual/latest/#_maven).
    +
    +
    +### Karaf Features
    +
    +A [karaf feature.xml](https://karaf.apache.org/manual/latest/#_create_a_features_xml_karaf_feature_archetype)
    +defines a set of bundles that make up a feature. Once a feature is defined, one can add
it to a Karaf instance:
    +either directly (e.g. using the [Karaf console](https://karaf.apache.org/manual/latest/#_shell_console_basics)),
or
    +by referencing it in another feature.xml file. 
    +
    +
    +### Embedded Dependencies
    +
    +An OSGi bundle can 
    +[embed jar dependencies](http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html#embedding-dependencies)
    +within it. This allows dependencies to be kept private within a bundle, and easily shipped
with that bundle.
    +
    +To keep these private, it is vital that the OSGi bundle does not import or export the
packages
    +contained within those embedded jars, and does not rely on any of those packages in the
public 
    +signatures of any packages that are exported or imported.
    --- End diff --
    
    Is it worth adding a section on non-osgi jars? Os is it too advanced (though more frequently
needed than I'd like)? The three possible approaches are:
      * use a servicemix re-packaged jar if available
      * use `wrap:` prefix if using features
      * if none of the above are possible then can "wrap" the bundle offline and use the re-packaged
bundle - following the servicemix approach but locally. This can be used in the `brooklyn.libraries`
section.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message