You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by al...@apache.org on 2016/10/04 23:10:17 UTC
[1/2] brooklyn-docs git commit: Improvements to java blueprint docs
for OSGi
Repository: brooklyn-docs
Updated Branches:
refs/heads/master 152b418ce -> c008aae55
Improvements to java blueprint docs for OSGi
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/5c5b0e25
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/5c5b0e25
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/5c5b0e25
Branch: refs/heads/master
Commit: 5c5b0e253efafe49981c8ec43a52885fe6e850a7
Parents: 7e13af2
Author: Aled Sage <al...@gmail.com>
Authored: Wed Sep 28 21:34:10 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Oct 4 10:12:22 2016 +0100
----------------------------------------------------------------------
guide/java/archetype.md | 27 +++--
guide/java/bundle-dependencies.md | 135 ++++++++++++++++++++++
guide/java/defining-and-deploying.md | 17 ++-
guide/java/gist_generator/gist_generator.bom | 11 +-
guide/java/index.md | 1 +
5 files changed, 168 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5c5b0e25/guide/java/archetype.md
----------------------------------------------------------------------
diff --git a/guide/java/archetype.md b/guide/java/archetype.md
index 8a9ac11..8f51410 100644
--- a/guide/java/archetype.md
+++ b/guide/java/archetype.md
@@ -26,11 +26,13 @@ Alternatively, all options can be supplied at the command line. For example,
if creating a project named "autobrick" for "com.acme":
{% highlight bash %}
+$ BROOKLYN_VERSION={{ site.brooklyn-version }}
$ mvn archetype:generate \
-DarchetypeGroupId=org.apache.brooklyn \
-DarchetypeArtifactId=brooklyn-archetype-quickstart \
- -DarchetypeVersion={{ site.brooklyn-version }} \
- -DgroupId=com.acme -DartifactId=autobrick \
+ -DarchetypeVersion=${BROOKLYN_VERSION} \
+ -DgroupId=com.acme \
+ -DartifactId=autobrick \
-Dversion=0.1.0-SNAPSHOT \
-DpackageName=com.acme.autobrick \
-DinteractiveMode=false
@@ -73,22 +75,31 @@ For example:
{% highlight yaml %}
brooklyn.catalog:
brooklyn.libraries:
- - file:///path/to/jar/autobrick-0.1.0-SNAPSHOT.jar
+ - file:///path/to/jar/autobrick-0.1.0-SNAPSHOT.jar
+ version: "0.1.0-SNAPSHOT"
itemType: entity
items:
- - id: com.acme.MySample
+ - id: com.acme.autobrick.MySample
item:
- type: com.acme.MySample
+ type: com.acme.autobrick.MySample
{% endhighlight %}
The command below will use the CLI to add this to the catalog of a running Brooklyn instance:
{% highlight bash %}
- br add-catalog src/main/resources/catalog.bom
+ br add-catalog catalog.bom
{% endhighlight %}
-After running that command the entity will have been added to your catalog and can be used
-in the same way as regular Brooklyn entities.
+After running that command, the OSGi bundle will have been added to the OSGi container, and the
+entity will have been added to your catalog. It can then be used in the same way as regular AMP
+entities.
+
+For example, you can use the blueprint:
+
+{% highlight yaml %}
+services:
+- type: com.acme.autobrick.MySample
+{% endhighlight %}
### Testing Entities
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5c5b0e25/guide/java/bundle-dependencies.md
----------------------------------------------------------------------
diff --git a/guide/java/bundle-dependencies.md b/guide/java/bundle-dependencies.md
new file mode 100644
index 0000000..5a894eb
--- /dev/null
+++ b/guide/java/bundle-dependencies.md
@@ -0,0 +1,135 @@
+---
+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 -s 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
+318 | Active | 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.
+
+
+### Converting Non-OSGi Dependencies to Bundles
+
+If a dependencies is not available as an OSGi bundle (and you don't want to just [embed the jar](#embedded-dependencies)),
+there are a few options for getting an equivalent OSGi bundle:
+
+* Use a ServiceMix re-packaged jar, if available. ServiceMix have re-packed many common dependencies as
+ OSGi bundles, and published them on [Maven Central](https://search.maven.org).
+
+* Use the `wrap:` prefix. The [PAX URL Wrap protocol](https://ops4j1.jira.com/wiki/display/paxurl/Wrap+Protocol)
+ is an OSGi URL handler that can process your legacy jar at runtime and transform it into an OSGi bundle.
+ This can be used when declaring a dependency in your feature.xml, and when using the Karaf console's
+ `bundle:install`. Note that it is not yet supported in Brooklyn's `brooklyn.libraries` catalog items.
+
+* Re-package the bundle yourself, offline, to produce a valid OSGi bundle.
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5c5b0e25/guide/java/defining-and-deploying.md
----------------------------------------------------------------------
diff --git a/guide/java/defining-and-deploying.md b/guide/java/defining-and-deploying.md
index d754c82..4e6fc62 100644
--- a/guide/java/defining-and-deploying.md
+++ b/guide/java/defining-and-deploying.md
@@ -149,16 +149,15 @@ artifact (which will be in the `target` sub-directory after running `mvn clean i
{% readj gist_generator/gist_generator.bom %}
{% endhighlight %}
-*Unfortunately the file org.eclipse.egit.github.core-2.1.5.jar (available on maven central) was
-generated incorrectly as an OSGi bundle (there is a missing quotation mark from the manfest file,
-making it invalid). The above YAML references a corrected version of this OSGi bundle, made
-available for test purposes.*
+See [Handling Bundle Dependencies]({{ site.path.guide}}/java/bundle-dependencies.html)
+for a description of the `brooklyn.libraries` used above, and for other alternative approaches.
-The command below will use the REST api to add this to the catalog of a running Brooklyn instance.
+The command below will use the `br` CLI to add this to the catalog of a running Brooklyn instance.
Substitute the credentials, URL and port for those of your server.
-{% highlight bash %}
-$ curl -u admin:pa55w0rd https://127.0.0.1:8443/v1/catalog --data-binary @gist_generator.bom
+{% highlight bash %}
+$ br login https://127.0.0.1:8443 admin pa55w0rd
+$ br add-catalog gist_generator.bom
{% endhighlight %}
@@ -168,11 +167,11 @@ The YAML blueprint below shows an example usage of this blueprint:
name: my sample
services:
- - type: example.GistGenerator:1.0
+ - type: example.GistGenerator
brooklyn.config:
oauth.key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-Note the type name matches the id and version defined in the `.bom` file.
+Note the type name matches the id defined in the `.bom` file.
You can now call the effector by any of the standard means - [web console]({{ site.path.guide }}/ops/gui/),
[REST api]({{ site.path.guide }}/ops/rest.html), or [Client CLI]({{ site.path.guide }}/ops/cli/).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5c5b0e25/guide/java/gist_generator/gist_generator.bom
----------------------------------------------------------------------
diff --git a/guide/java/gist_generator/gist_generator.bom b/guide/java/gist_generator/gist_generator.bom
index 89effaf..9548035 100644
--- a/guide/java/gist_generator/gist_generator.bom
+++ b/guide/java/gist_generator/gist_generator.bom
@@ -1,15 +1,14 @@
brooklyn.catalog:
+ libraries:
+ - http://search.maven.org/remotecontent?filepath=com/google/code/gson/gson/2.2.2/gson-2.2.2.jar
+ - 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
+ - http://developers.cloudsoftcorp.com/brooklyn/guide/java/gist_generator/autobrick-0.1.0-SNAPSHOT.jar
id: example.GistGenerator
- version: "1.0"
+ version: "0.1.0-SNAPSHOT"
itemType: template
description: For programmatically generating GitHub Gists
displayName: Gist Generator
iconUrl: classpath:///sample-icon.png
- libraries:
- - http://search.maven.org/remotecontent?filepath=com/google/code/gson/gson/2.2.2/gson-2.2.2.jar
- - http:/.developers.cloudsoftcorp.com/brooklyn/guide/java/gist_generator/org.eclipse.egit.github.core-2.1.5.jar
- - http://developers.cloudsoftcorp.com/brooklyn/guide/java/gist_generator/autobrick-0.1.0-SNAPSHOT.jar
-
item:
services:
- type: com.acme.GistGenerator
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5c5b0e25/guide/java/index.md
----------------------------------------------------------------------
diff --git a/guide/java/index.md b/guide/java/index.md
index 0dce159..c15d007 100644
--- a/guide/java/index.md
+++ b/guide/java/index.md
@@ -6,6 +6,7 @@ started-pdf-exclude: true
children:
- archetype.md
- defining-and-deploying.md
+- bundle-dependencies.md
- topology-dependencies.md
- common-usage.md
- feeds.md
[2/2] brooklyn-docs git commit: This closes #113
Posted by al...@apache.org.
This closes #113
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/c008aae5
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/c008aae5
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/c008aae5
Branch: refs/heads/master
Commit: c008aae55ecba0389474f2c77d51cc6ee9e19e78
Parents: 152b418 5c5b0e2
Author: Aled Sage <al...@gmail.com>
Authored: Wed Oct 5 00:10:01 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Wed Oct 5 00:10:01 2016 +0100
----------------------------------------------------------------------
guide/java/archetype.md | 27 +++--
guide/java/bundle-dependencies.md | 135 ++++++++++++++++++++++
guide/java/defining-and-deploying.md | 17 ++-
guide/java/gist_generator/gist_generator.bom | 11 +-
guide/java/index.md | 1 +
5 files changed, 168 insertions(+), 23 deletions(-)
----------------------------------------------------------------------