Architecture Examples

This is the source code for the architectural examples cited on LucidJ Documentation.

Important

Please be sure to check the documentation inside every subproject (the numerated directories). Every subproject have it’s own documentation and instructions to build and run the tests.

Prerequisites for Building

• Java Development Kit 8 or later

• Ant (minimun Ant 1.8.0)

Before Starting

The examples were built to illustrate both functionality and implementation. They are IDE-agnostic, showing all the steps to build an OSGi application from zero without need of a particular combination of IDE and plugin or any wizzard tool.

We achieve this using Ant. Today, you can also use Maven to build any OSGi project, however Maven is magical in it’s own way, because there are many predefined (and sane) defaults. You may choose Maven for your own projects. On the other side, Ant allows you to follow the logic of building an OSGi jar file, with all required steps very visible. We strongly suggest you to take a time to look into build.xml and configure.xml to get a good idea of whats going on, and how things are being done. It may look intimidating at first, but hopefully will also be instructive.

Specially, you will get known to Bnd (http://bndtools.org/), which is the reference tool to build all OSGi-related stuff you can imagine. There’s also the iPojo processor, which manipulates the code after compilation and demonstrates the post-processing of OSGi jar bundles.

Building

You need a stage to work. Our default stage is built with Apache Felix. The stage area is where the bundles will be deployed, and every subproject will deploy it’s artifacts there. You may also build an alternative stage using Apache Karaf if you wish:

• Build the Felix stage: Follow these instructions to build the default Felix stage;

  or

• Build the Karaf stage: Use these instructions to build an alternative Karaf stage.

To specific instructions to run the examples and the tests are available for each subproject on the README.adoc file.

To build all subprojects at once, just type ant on project root.

By default, Ant will download and cache all needed tools, then invoke the build-all target. The output of all builds will be located in dist/ directory beneath every subproject. If the stage is available, all built bundles will be automatically copied into stage/deploy.

Running

To run the OSGi container available on the stage/ directory use:

• Run stage/bin/felix for Apache Felix (our default container);

  or

• Run stage/bin/karaf for a Apache Karaf stage.

Administration and Monitoring

There are 2 administration tools available:

• Apache Felix Web Console: The built-in admin console available for Apache Felix. Click here to open Felix Console at http://localhost:6502/system/console/. Both username and password are admin.

• Hawt.io Console: Additional web console. Open source, extendable with lots of plugins. Use Ant to launch the Hawt.io server running ant run-hawtio on project root. After started, click here to open Hawt.io Console at http://localhost:8181/hawtio/. On the connection dialog that follows, be sure to set host to localhost and port to 6502 (our default Felix host and port). Keep the default path the same jolokia. We use Jolokia to provide JMX over HTTP/JSON.

Useful Ant targets

For details on building the code, see ant -p.

These are the available targets:

• ant build-stage: build the stage with Apache Felix ready to run the examples;

• ant build-karaf: build the stage using Apache Karaf instead;

• ant build-library-version: build the Library Versioning subproject;

• ant build-private-libraries: build the Private Libraries subproject;

• ant build-rest-playground: build the Rest Playground subproject;

• ant build-all: builds all available subprojects;

• ant run-hawtio: download and start Hawt.io Web Console;

• ant clean: removes the build and dist directories;

• ant zero: same as clean, but also removes the cache directory with all downloaded tools;

• ant configure: rebuild the library and tools cache.

Key Directories and Files

Important directories to be aware of:

• cache - stores the downloaded jars, custom tasks and other tools;

• stage - the local Apache Karaf installation built to test the subprojects.

The configure.xml file contains all the macros and targets used by the subprojects and it’s worth looking. It can be used standalone on another projects.

Installing Java on Raspberry Pi

Raspberry Pi have a fully certified OpenJDK distribution available: Zulu® Embedded, built by Azul Systems. You can install it on Raspbian Stretch using:

# apt-get install dirmngr
# apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 0x219BD9C9
# echo 'deb http://repos.azulsystems.com/debian stable main' > /etc/apt/sources.list.d/zulu.list
# apt-get update
# apt-get install zulu-embedded-8
# java -version
openjdk version "1.8.0_152"
OpenJDK Runtime Environment (Zulu Embedded 8.25.0.76-linux-aarch32hf) (build 1.8.0_152-b76)
OpenJDK Client VM (Zulu Embedded 8.25.0.76-linux-aarch32hf) (build 25.152-b76, mixed mode, Evaluation)

Important Resources

If you need further information, please refer to the following resources:

• OSGi in Practice: Free, Creative Commons-licensed book on OSGi by Neil Bartlett.

• Tutorial Archive from OSGi Alliance: Lots of great articles and resources.

• BND Tools: The standard OSGi tool to build artifacts.

• OSGi Specifications: All OSGi specifications available from OSGi Alliance.

• OSGi Release 5 Javadoc: Browse online the javadocs for OSGi R5 APIs.

Copyright

This work is licensed under a Apache License, Version 2.0.