Bndtools and Maven: A Brave New World - N Bartlett & T Ward

Copyright © 2017 Paremus Ltd.
May not be reproduced by any means without express permission. All rights reserved.
October 2017
Neil Bartlett
neil.bartlett@paremus.com
Bndtools and Maven: 
A Brave New World
Tim Ward
tim.ward@paremus.com

October 2017
Overview

October 2017
Bnd & Bndtools History
• bnd is a low-level tool developed originally by Peter Kriens
and used by OSGi Alliance.
• Pre-dates Maven and Gradle!
• Most bnd builds used ANT.
• bnd provided dependency management missing from ANT.
• ~2006 Bndtools project started.

October 2017
Bnd, Bndtools & Maven
• Maven overtook ANT in the wider industry.
• Bndtools did not work well with Maven.
• Both trying to manage build dependencies & own the build
lifecycle.

October 2017
Bnd, Bndtools & Maven
• New Maven plugins in bnd since 3.2.
• Integration with M2E build lifecycle.
• Now even better in 3.5!
• Bundles and indexes rebuilt on save.

October 2017
Development Workflow
Component
Development
Bundle Unit
Testing
Bundle
Repository
Integration
Testing
Code-Test
Application
Assembly
Application
Artifact
consum
e
Deployment

October 2017
Project Structure
_distro
_index
Component
Bundles
_assembly
Test
Bundles

October 2017
Effective OSGi Archetypes
• Maven archetypes for easy project creation.
• Generates an application that runs out-of-the-box.
• Also archetypes for new bundle modules and integration test
modules.
• https://github.com/effectiveosgi/maven-archetypes
e

October 2017
Preview
• We are building a simple “Points of Interest” web application.
• See what it will look like by running ‘java -jar preview.jar’ and
navigating to http://localhost:8080/index.html

October 2017
Get It
github.com/paremus/osgi-community-event2017/releases
bit.ly/osgice2017tut

October 2017
Exercise Help
• These slides have the key new content but not everything.
• New files introduced in each lab are under tutorial/NN_
• E.g.: 01_command_bundle/HelloCommand.java
• Have to put in the right place!
• If you get really stuck, use the checkpoint zips.
• E.g. 03_tester_bundle.checkpoint.zip contains everything up to
and including the tester bundle exercise.
• Refer to current checkpoint number in top-right of slide.

October 2017
Install Archetypes

October 2017
Install Effective OSGi Archetypes
• Not yet available on Maven Central, so…
• Open folder archetypes
• Run install.sh or install.bat
• Uses ‘mvn install:install-file’ to copy into local Maven repo.

October 2017
Project Initiation

October 2017
Initial Project
mvn archetype:generate
-DarchetypeGroupId=com.effectiveosgi
-DarchetypeVersion=0.0.1-SNAPSHOT
-DarchetypeArtifactId=eosgi-project-archetype
Group ID: org.example.bnd-maven
Artifact ID: example-parent
Version, Package: <use defaults>
Checkpoint: 00

October 2017
Initial Project
• Includes a skeleton OSGi application that can be run
immediately.
• Open _assembly/application.bndrun and click Run.
• Or:
• mvn package
• java -jar _assembly/target/application.jar
• You should be in the Gogo shell. Ctrl-D to exit.
Checkpoint: 00

October 2017
Command Bundle

October 2017
Generate Module
-DarchetypeArtifactId=eosgi-module-archetype
Artifact ID: org.example.command
Checkpoint: 01

October 2017
Command Bundle Code
• Rename Example.java to HelloCommand.java
package org.example.command;
import java.text.MessageFormat;
import org.osgi.service.component.annotations.*;
@Component(
service = Object.class,
property = {
"osgi.command.scope=greeting",
"osgi.command.function=sayHello"
})
public class HelloCommand {
public String sayHello() {
return sayHello("anonymous user");
}
public String sayHello(String name) {
return MessageFormat.format("Hello, {0}", name);
}
}
Checkpoint: 01

October 2017
Command Bundle Code
• Rename ExampleTest.java to HelloCommandTest.java
package org.example.command;
import static org.junit.Assert.*;
import org.junit.Test;
public class HelloCommandTest {
@Test
public void test() {
HelloCommand cmd = new HelloCommand();
assertEquals("Hello, Donald", cmd.sayHello("Donald"));
}
}
Checkpoint: 01

October 2017
Command Bundle Testing
• Open launch.bndrun
• Check that the Resolve button works.
• Click Run OSGi.
• Try the command ‘sayHello <name>’
• Unit Testing: right-click src/test/java and Run As > JUnit Test.
Checkpoint: 01

October 2017
Command Bundle Indexing
• Include org.example.command in the main index.
• This makes your new bundle available for application
assembly.
• _index/pom.xml:
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>org.example.command</artifactId>
<version>${project.version}</version>
</dependency>
Checkpoint: 01

October 2017
P.o.I. (Points-of- 
Interest) Bundle

October 2017
Generate Module
Artifact ID: org.example.poi
Checkpoint: 02

October 2017
POI Bundle API
• Create package org.example.poi with package-info.java:
• Add PointsOfInterest.java:
@org.osgi.annotation.versioning.Version("1.0.0")
package org.example.poi;
package org.example.poi;
import java.util.List;
public interface PointsOfInterest {
static final class POI {
public float latitude;
public float longitude;
public String label;
@Override
public String toString() { return String.format("POI '%s':lat=%f;long=%f", label, latitude, longitude); }
}
List<POI> find(String search) throws Exception;
}
Checkpoint: 02

October 2017
POI Bundle Implementation
• Create package org.example.poi.impl and POIComponent.java
@Component
public class POIComponent implements PointsOfInterest {
private final List<POI> pois = new ArrayList<>();
@Activate
void activate() throws Exception {
InputStream resource = getClass().getResourceAsStream("/data.csv");
if (resource == null) throw new IllegalStateException("Missing data resource");
try (BufferedReader reader = new BufferedReader(new InputStreamReader(resource))) {
reader.lines()
.map(s -> s.split(",", 3))
.map(ss -> {
if (ss.length != 3) throw new IllegalArgumentException("Not enough fields: " + Arrays.toString(ss));
POI poi = new POI();
poi.latitude = Float.parseFloat(ss[0]);
poi.longitude = Float.parseFloat(ss[1]);
poi.label = ss[2];
return poi;
}).forEach(pois::add);
}
}
@Override
public List<POI> find(String search) throws Exception {
Pattern pattern = Pattern.compile(search.toLowerCase().replaceAll("*", ".*"));
return pois.stream()
.filter(poi -> pattern.matcher(poi.label.toLowerCase()).find())
.collect(Collectors.toList());
}
}
Checkpoint: 02

October 2017
POI Bundle Data
• Copy data.csv to src/main/resources
48.8927,9.1950,OSGi Community Event
48.78816,9.23413,Mercedes-Benz Museum
48.89168,9.18617,Ludwigsburg S-Bahn
48.90448,9.19571,Favoriteschloss
Checkpoint: 02

October 2017
POI Bundle Unit Test
• Under src/test/java, package org.example.poi.impl, create
POIComponentTest.java:
• Right-click src/test/java, Run As > JUnit Test
public class POIComponentTest {
@Test
public void test() throws Exception {
// This doesn't really test the component, it only shows the component is testable in plain JUnit
POIComponent component = new POIComponent();
component.activate();
List<POI> pois = component.find("*");
assertNotNull(pois);
}
}
Checkpoint: 02

October 2017
POI Bundle Indexing
• Include org.example.poi in the main index:
<dependency>
<artifactId>org.example.poi</artifactId>
</dependency>
Checkpoint: 02

October 2017
Tester Bundle

October 2017
Generate Module
-DarchetypeArtifactId=eosgi-test-module-archetype
Artifact ID: org.example.poi.test
Checkpoint: 03

October 2017
POI Test Depends on POI
• Add dependency to pom.xml:
<dependency>
</dependency>
Checkpoint: 03

October 2017
POI Test Class
• Create POIBundleTest in org.example.poi.test:
public class POIBundleTest {
private final BundleContext context = FrameworkUtil.getBundle(POIBundleTest.class).getBundleContext();
private ServiceTracker<PointsOfInterest, PointsOfInterest> poiTracker;
@Before
public void before() {
poiTracker = new ServiceTracker<>(context, PointsOfInterest.class, null);
poiTracker.open(true);
}
@After
public void after() {
poiTracker.close();
}
@Test
public void testExample() throws Exception {
PointsOfInterest pois = poiTracker.waitForService(1000);
assertNotNull("POI service not found", pois);
assertNotNull("POI search returned null", pois.find("*"));
}
}
Checkpoint: 03

October 2017
POI Integration Test
• Resolve org.example.poi.test.bndrun
• Right-click, Run As > Bnd OSGi Test Launcher (JUnit)
• Try automated build: ‘mvn verify’
Checkpoint: 03

October 2017
POI Test Bundle Indexing?
• DO NOT include org.example.poi in the main index:
• Why…?
<dependency>
<artifactId>org.example.poi.test</artifactId>
</dependency>
Checkpoint: 03

October 2017
Web Bundle

October 2017
Web Bundle
• Our most complex bundle yet.
• Three stages:
• 1. Build the web app front-end with non-functional back-end.
• 2. Connect to the POI back end.
• 3. Add Jackson to serialize data from the back-end.

October 2017
Generate Module
Artifact ID: org.example.web
Checkpoint: 04

October 2017
Web Bundle Dependencies
• Need to depend on the Servlet API:
<dependency>
<groupId>org.apache.felix</groupId>
<artifactId>org.apache.felix.http.servlet-api</artifactId>
<version>1.1.2</version>
</dependency>
Checkpoint: 04

October 2017
Servlet Component
• Rename Example.java to POIServlet.java:
@Component(
property = {
HttpWhiteboardConstants.HTTP_WHITEBOARD_RESOURCE_PATTERN + "=/*",
HttpWhiteboardConstants.HTTP_WHITEBOARD_RESOURCE_PREFIX + "=/static",
HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_PATTERN + "=/servlet"
})
public class POIServlet extends HttpServlet implements Servlet {
private static final long serialVersionUID = 1L;
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
String query = req.getQueryString();
if (query == null || query.trim().isEmpty()) query = "";
try (OutputStream out = resp.getOutputStream()) {
// TODO: delete code below, replace with code to search for POIs and serialize as JSON to the browser
new PrintStream(out).println("[]"); // empty JSON array
} catch (Exception e) {
resp.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, e.getMessage());
}
}
}
Checkpoint: 04

October 2017
Static Web Resources
• Copy whole ‘static’ folder to src/main/resources.
• Standard web structure: HTML, CSS and JS.
Checkpoint: 04

October 2017
Declare Web Engine Requirement
• Create bnd.bnd and switch to Source tab. Add:
• Declares that our bundle requires a Web Engine at runtime.
• Enables the Resolver to fully assemble the application.
• Yes the syntax is nasty. Java source annotations coming in
OSGi R7!
Require-Capability:
osgi.implementation;
filter:="(&(osgi.implementation=osgi.http)(version>=1)(!(version>=2)))"
Checkpoint: 04

October 2017
Run Simple Web App
• Resolve and run launch.bndrun
• Navigate to http://localhost:8080/index.html
• Note the POI search doesn’t work yet!
Checkpoint: 04

October 2017
Connect Web Bundle to POI Service
• Make org.example.web depend on org.example.poi:
• Add reference from POIServlet to PointsOfInterest service:
<dependency>
</dependency>
// ...
@Reference
PointsOfInterest poiSvc;
// ...
Checkpoint: 05

October 2017
Serialize with Jackson
• Make org.example.web depend on Jackson Databind:
• Use ObjectMapper to serialize result of poiSvc.find():
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
// ...
private ObjectMapper mapper = new ObjectMapper();
// ...
try (OutputStream out = resp.getOutputStream()) {
List<POI> pois = poiSvc.find(query);
mapper.writeValue(out, pois);
} catch (Exception e) {
resp.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, e.getMessage());
}
// ...
Checkpoint: 06

October 2017
Run Simple Web App
• Resolve and run launch.bndrun
• Navigate to http://localhost:8080/index.html
• The POI search should now work (try inputting ‘*’).
Checkpoint: 06

October 2017
Assembly

October 2017
Application Assembly
• _index generates an OSGi repository XML index.
• Format speciﬁed in OSGi Compendium R5+, Section 132.5
• Can be used by many OSGi-oriented tools and platforms.
• _assembly generates standalone applications
• Based on a bndrun ﬁle.
• Run exactly the application in production that was tested in dev.

October 2017
Indexing
• The bnd-indexer-maven-plugin indexes all transitive
dependencies of the module to which it is attached.
• … in either compile and runtime scope.
• It must depend on all non-test project modules.
• Many Maven users build their application directly this way.
• For us, the index is just the set of potentially useful bundles.
• The OSGi Resolver uses this to assemble only exactly what we
need and nothing more.

October 2017
Assembly
• The _assembly module depends on _index and defines one
or more launch definitions.
• An application is defined in terms of top-level requirements.
• Resolves against index to find all the “boring” dependencies.

October 2017
Assembly
• The bnd-export-maven-plugin generates a standalone
application JAR file (just add Java).
• Resolve in the IDE or command line to review & tweak
contents.
• Automated build also checks resolution & fails build if
different.
• Very useful to prevent dependency creep!

October 2017
Catching Dependency Creep TODO
• Start using external library from our bundle…
• Example: add SLF4j to org.example.command
• pom.xml:
• Example.java:
• “mvn package”… fails due to undeclared dependency (which is good)!
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
import org.slf4j.*;
@Component
public class HelloCommand {
Logger logger = LoggerFactory.getLogger(Example.class);
// ...
}

October 2017
Shepherding Dependencies
• Compile Scope: try to depend only on APIs, e.g. Servlet API,
SLF4j…
• Runtime Scope: depend on supporting implementations, e.g.
Logback, Felix Jetty…
• _distro for widely used 3rd party runtime bundles, e.g.:
• SCR, Conﬁg Admin, Gogo, Event Admin…
• Make proper use of Provided Scope for dependencies that should
never be installed as bundles, e.g. OSGi Core/Compendium
• Some 3rd party bundles have not done this correctly. You will
need to use Maven exclusions :-(

October 2017
Multiple Versions
• OSGi can support multiple versions at runtime. Great!
• Classic example: my app needs Guava N and Guava N+1.
• Maven will not allow any module to depend on two versions of
the same artifact.
• Therefore: cannot generate a single index with both Guavas.
• Solution is multiple indexes.
• A bndrun file can reference arbitrarily many indexes.

October 2017
Continuous 
Integration

October 2017
Indexing & Resource URLs
• Taking a look at the index you might notice a problem:
• This is good for local dev… don’t need a Nexus/Artifactory.
• But this index is not consumable outside my computer.
• Need to control the policy w.r.t. resource locations.
<capability namespace="osgi.content">
<attribute name="size" value="7063" type="Long"/>
<attribute name="url" value=“file:/Users/nbartlett/…/org.example.poi/target/org.example.poi-1.0-SNAPSHOT.jar”/>
<attribute name="mime" value="application/vnd.osgi.bundle"/>
<attribute name="osgi.content" value="901CD7D625C58F6C138244620776317AC0666139F79246D22AFF4CD1C4FA3456"/>
</capability>

October 2017
Local Index Policy
• This config is in the parent POM:
• FORBIDDEN means the resource must have a real URL, or
build fails… perfect for CI build.
• Configure CI job to set the CI_Build profile.

<profiles>
<profile>
<id>CI_Build</id>
<properties>
<local.index.policy>FORBIDDEN</local.index.policy>
</properties>
</profile>
</profiles>

October 2017
Review

October 2017
Maven Plugins Used
• bnd-maven-plugin: Basically builds bundles!
• bnd-indexer-maven-plugin: Generates OSGi repo index.
• bnd-testing-maven-plugin: Executes tests in OSGi Framework.
• bnd-export-maven-plugin: Generates standalone applications.

October 2017
Maven Plugins NOT Used
• bnd-resolver-maven-plugin: Resolves bndruns.
• Intended for manual command-line usage:
• ‘mvn bnd-resolver:resolve’
• Usually easier to resolve in Bndtools
• bnd-baseline-maven-plugin: Validates semantic versions
• Requires comparison against a release version in a repo.
• Left as an exercise

October 2017
Thank You!
Sources: github.com/paremus/osgi-community-event2017
Email: neil.bartlett@paremus.com
Twitter: @nbartlett

Bndtools and Maven: A Brave New World - N Bartlett & T Ward

Bndtools and Maven: A Brave New World - N Bartlett & T Ward

Recommended

More Related Content

What's hot

What's hot(20)

Similar to Bndtools and Maven: A Brave New World - N Bartlett & T Ward

Similar to Bndtools and Maven: A Brave New World - N Bartlett & T Ward(20)

More from mfrancis

More from mfrancis(20)

Recently uploaded

Recently uploaded(20)

Bndtools and Maven: A Brave New World - N Bartlett & T Ward