Java to bndtools builder plugin

Table of Contents

1. What is it and what does it do
2. Prerequisites
3. How to install?
   1. Using the Eclipse update site
   2. Alternative way
4. How to use?
   1. Plugin way (recommended)
   2. Alternative way 1: Using Eclipse project properties
   3. Alternative way 2: Manual way (not recommended)
5. Example usage
6. How does it work?
7. To-do

What is it and what does it do?

It is an Eclipse plugin that provides integration of Java projects into a bndtools workspace, by making these Java projects available in a local bndtools repository.

Prerequisites

1. Eclipse workspace with bndtools workspace with the mandatory bnd cnf project folder and a bnd repository named "Local"
2. A Java project (having the org.eclipse.jdt.core.javanature nature) being contained within the same Eclipse workspace
3. The META-INF/MANIFEST.MF of the Java project must be present, readable and must have the following attributes (Bundle-Version defaults to 0.0.0 if not specified), mind the mandatory newline at the end of the file:

Manifest-Version: 1.0
Bundle-Name: Dummy project
Bundle-SymbolicName: com.foo.bar
Bundle-ManifestVersion: 2
Bundle-Version: 1.0.0

If your bnd workspace is missing the Local repository, you can add the entry to the main cnf/build.bnd file:

-plugin.7.Local: \
    aQute.bnd.deployer.repository.LocalIndexedRepo; \
    name = Local; \
    pretty = true; \
    local = ${build}/local

How to install?

Using the Eclipse update site (recommended)

The Eclipse update site is generated by the enclosed de.janhendriks.java2bnd.updatesite project (which uses the enclosed de.janhendriks.java2bnd.feature project which in turn uses this de.janhendriks.java2bnd project) and can be found at following URL:

https://github.com/DaHoC/Java2Bndtools/raw/master/de.janhendriks.java2bnd.updatesite/

Don't mind the potential HTTP 404 response as the index.html is missing, but Eclipse should rely on the existing site.xml file

Alternative way:

Clone this repo, and use the updatesite project as source folder as local Eclipse update site.

How to use?

Make sure that the prerequisites are met.

To associate the plugin with a Java project, you need to add a nature (which adds the corresponding builder) to the project you want to provide to the local bndtools workspace.

Each time a full build on the Java project is triggered, e.g. by doing a Project → Clean… → Build (automatically), the updated project should appear as bundle in the "Local" bndtools workspace repository.

The name of the bundle corresponds to the Bundle-SymbolicName MANIFEST.MF entry, the version to Bundle-Version.

This bundle can then be referenced by a bnd project.

To associate the plugin with a Java project, there are several approaches:

Plugin way (recommended)

Select the Java projects which should be considered and included as bnd dependencies in the "Package Explorer" or "Project Explorer" view, right-click to open the context menu → Add Java2bnd nature

Alternative way 1: Using Eclipse project properties

Select the Java project, go into its properties (e.g. by right-clicking the project → Properties), select Project Natures → Add... → Add Java2bnd nature as depicted below:

After hitting Apply and Close, the project nature is added, the corresponding builder is added and registered and the project is build and should immediately appear in the bnd workspace "Local" repository.

Alternative way 2: Manual way (not recommended)

For the Java project add the de.janhendriks.java2bnd.nature and buildCommand de.janhendriks.java2bnd.builder as last build entry as shown in the following .project entries / builder:

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	...
	<buildSpec>
		<buildCommand>
			<name>org.eclipse.jdt.core.javabuilder</name>
			<arguments>
			</arguments>
		</buildCommand>
		<buildCommand>
			<name>de.janhendriks.java2bnd.builder</name>
			<arguments>
			</arguments>
		</buildCommand>
	</buildSpec>
	<natures>
		<nature>org.eclipse.jdt.core.javanature</nature>
		<nature>de.janhendriks.java2bnd.nature</nature>
	</natures>
</projectDescription>

Example usage

Consider a Java project in your bndtools workspace that has a Bundle-SymbolicName of com.foo.java and a Bundle-Version of 2.1.0 defined in its META-INF/MANIFEST.MF.

Besides this project, the com.bar.bnd bndtools project is present in the same Eclipse workspace, which is to be configured to require the com.foo.java bundle as dependency.

First a full build of the Java project com.foo.java is to be done (e.g. by Project → Clean… → Build (automatically)). Afterwards, the corresponding bundle should now be present in the "Local" bndtools workspace repository (see Bndtools perspective → Repositories → Local).

com.foo.java can now be referenced from the com.bar.bnd/bnd.bnd file, e.g.

-buildpath = com.foo.java;version=2.1.0

The com.bar.bnd bndtools project now references the com.foo.java bundle as dependency and the exposed API (including JavaDoc) and further bndtools/OSGi instructions can be used (like Require-Capability, Import-Package, -runbundles and so on).

After each successful full build of the com.foo.java project, the corresponding bundle in the "Local" bndtools repository is updated.

How does it work?

If the Java project is given the additional nature (and builder) as mentioned before, the builder registers itself as the last builder to execute in the chain, to make sure it's called after all other builders doing e.g. source generation or resource handling, especially after the Java builder.

During each full build of this Java project, the Java2bndtools builder packs generated Java artifacts of the project into a temporary jar file using the Eclipse-internal jar package exporter with custom settings.

This temporary JAR file is passed via stream to the bnd workspace "Local" repository where it should appear. It is automatically overwritten for each new full build and the bnd workspace repository is refreshed automatically.

To-do

1. Support incremental builds to some extent (if possible and feasible at all)
2. Provide minimal sample workspace (from the example)
3. If MANIFEST.MF is missing, use a best-effort-approach, e.g. by setting

Manifest-Version: 1.0
Bundle-Name: <Eclipse project name>
Bundle-SymbolicName: <Eclipse project name>
Bundle-ManifestVersion: 2
Bundle-Version: 0.0.0