brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aleds...@apache.org
Subject [1/2] brooklyn-docs git commit: Improvements to java blueprint docs for OSGi
Date Tue, 04 Oct 2016 23:10:17 GMT
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 <aled.sage@gmail.com>
Authored: Wed Sep 28 21:34:10 2016 +0100
Committer: Aled Sage <aled.sage@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


Mime
View raw message