Gradle Plugins

We provide several Gradle Plugins that help developing UBStore projects.

Gradle supports applying plugins by downloading them from maven repositories. To tell gradle where to download the plugins from, put the following snippet at the top of your build.gradle file:

buildscript {
  // dependencies can be pulled from the following repositories
  repositories {
    maven { url 'http://p9.cs.unibas.ch/artifactory/ubstore-stable' }
    maven { url 'http://p9.cs.unibas.ch/artifactory/gradle-plugins' }
    mavenCentral()
  }

  // define the actual dependencies (jars) for the build script
  // that contain the plugins that will be applied, in their latest
  // version. You can delete one of the two if you do not need it
  dependencies {
    classpath 'ch.unibas.cs.dbis:ch.unibas.cs.dbis.ubstore.gradleplugin:+'
    classpath 'ch.unibas.cs.dbis:ch.unibas.cs.dbis.osgi:+'
  }
}

UBStore

The UBStore Gradle Plugin is meant to help setting your project to UBStore conventions. As all Gradle Plugins do, it simply sets some project settings, adds tasks, etc. It is intended to be applied to the actual bundle (sub-) projects, not the root project itself.

Applying the plugin

The UBStore plugin can then be applied to (sub-)projects for example like follows:

subprojects {
  apply plugin: 'ch.unibas.cs.dbis.ubstore'
}

Effects of the plugin

The UBStore plugin does the following things to a project it is applied to:

Apply more plugins

The UBStore plugin will apply more gradle plugins, more specifically:

Add repositories for dependency resolution

The UBstore plugin will add the following maven repositories in that precedence that will be used for dependency resolution:

  1. the local maven repository
  2. the UBStore repository
  3. Maven Central

This means that:

Add Dependencies to UBStore

The UBStore plugin will add a compile time dependency to ubstore.core.api and a runtime dependency to ubstore.core.impl. And since ubstore.core.api has a transitive dependency to SLF4J, it will also appear in your projects dependencies.

Configure the Java build

The UBStore plugin will configure the Java build to

Configuring the Plugin

You can configure some things the UBStore plugin does in your build script. To do so, add a section to your build script that looks similar to the following:

ubstore {
  repository = 'stable' // pull dependencies from the ubstore-stable mvn repository
  version = '0.6.+'     // get the latest available ubstore release from the 0.6 version
}

The repository variable can be assigned stable or unstable. This choses whether the stable or unstable UBStore repository is added to the list of repositories. The difference between the two repositories is that stable only contains build that pass all the Unit tests

The version variable can be assigned an arbitrary dependency version String. It determines which version of UBStore is pulled in as a dependency. In the example, the newest version of the 0.6.x release is used.

The default is set to pull the latest version ("+") from the stable repository.

OSGi Plugin

The OSGi Plugin should be applied to the actual bundle subprojects, not the root project. You can apply it by adding

apply plugin: 'ch.unibas.cs.dbis.osgi'

to your build.gradle file (besides the snippet from the beginning of this page).

Effects

Apply the Bundle Plugin

It applies the gradle-bundle-plugin, which makes your project generate OSGi bundles using bnd. Bnd is a very popular tool for creating OSGi bundles, the base for BndTools and is developed by the technological officer of the OSGi alliance.

The OSGi plugin will provide tasks that copy generated OSGi related files into directories that make eclipse recognize a project as a plug-in project. This enables running eclipse OSGi run configurations. However, if you do this, beware that it might behave different to what can be deployed using the osgi-deploy plugin for it deploys your project using Apache Felix (which more strictly adheres to the OSGi specification).

The tasks are called osgiCreateManifest, osgiCreateServiceDeclarations and osgiFiles (which is a combination of the former).

Instruct the bundle plugin to generate service declarations

It will configure the gradle-bundle-plugin to generate declarative service XML files from OSGi DS annotations (OSGi Compendium Specification, Section 112.14).

Add OSGi dependencies

The OSGi plugin will add compile time dependencies to org.osgi.core and org.osgi.compendium (which is the reference API of OSGi). Additionally, it will set runtime dependencies to Apache Felix SCR, an implementation of declarative services. This ensures that your declarative services are known and executed at runtime.

Configuring the OSGi Plugin

You can configure the OSGi plugin like follows:

osgi {
  osgi_version = '4.3.1'
  scr_version = '1.8.2'
}

You can use this to specify the version of both the OSGi framework and the Apache Felix SCR declarative service implementations. The defaults are as show in the example.

OSGi-Deploy Plugin

The OSGideploy plugin is used for generating a deployable package from your project. It is meant to be applied to the root project that contains the bundle projects.

Apply it by adding

apply plugin: 'ch.unibas.cs.dbis.osgideploy'

to your build.gradle file.

The OSGi-Deploy plugin will add several tasks to your project that aim to help deploying and running your project.

osgiDeploy

The osgiDeploy task will create a directory that can be run and deployed in /build/deploy. This package will download Apache Felix and put both the bundles of your project and all its dependencies in it. This means that you should be able to run your project as long as all dependencies are defined in your gradle file.

Additionally, it will put all files in /src/main/resources/osgideploy into the directory. This is useful for UBStore configurations files.

The package will contain a start.sh file that will run the application.

osgiRun

osgiRun will execute osgiDeploy and then run it. Since a percentage of the build will stick to the beginning of the OSGi console, you might want to run this task with the -q option (which supresses most of the gradle output).

Sadly, it is not suited for executing through the Eclipse Gradle plugin, since eclipse will not let you input anything into the console (no System.in defined). As a result, you OSGi application will start and immediately shut down again.

osgiLaunchConfigs

osgiLaunchConfigs will generate a bunch of eclipse launch configurations in the /launchConfigs directory that will help you execute and debug your application from within eclipse.

Three launch configurations are generated:

You can run the configurations by rightclicking it and chosing the top most option in the Run as / Debug as submenu.

Configuring OSGi-deploy

You can configure the OSGi-deploy plugin by adding the following section to your build.gradle file:

osgideploy {
  felix_version = '4.4.1'
  eclipse_workspace = '/path/to/project/root'
}

The felix_version variable is used to set the version of Apache Felix that will be downloaded during osgiDeploy. The default is 4.4.1.

The eclipse_workspace variable is used to set the scope of the Eclipse Debugger: It will only find break points and source files that are within that directory. Per default, it is set to be your projects root directory. However, if you have multiple root projects (for example when working on your own copy of UBStore), you need to adapt this path to be your Eclipse Workspace path in order to be able to set break points everywhere.

OSGi-wrap Plugin

The OSGi-wrap plugin can be used to convert existing libraries that do not support OSGi into OSGi bundles. It will collect all class files of the specified bundles and its dependencies into one jar.

The idea is to specify a separate project (which contains nothing but a build file), and as a result have an OSGi-enabled bundle of some library.

An example Gradle file would look as follows:

// ...
// omitted build script header from beginning of page

version = '1.3.0'
description = "OSGified version of org,.ektorp"
group = "ch.unibas"

apply plugin: 'ch.unibas.cs.dbis.osgiwrap'
dependencies {
  wrap('org.ektorp:org.ektorp:1.3.0')
}

bundle {
  instruction 'Bundle-Name', 'Ektorp'
  instruction '-exportcontents', 'org.ektorp.*,org.apache.*,org.codehaus.jackson.*'
}