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:
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:
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:
- The Java Plugin:
This basically means that it declares your project to be a Java project.
In Gradle, this means that your sources go into
src/main/java
, and tests go intosrc/test/java
. - The Maven Plugin:
This adds the
install
task that installs your project jars into the local maven repository. - Our custom OSGI Plugin: This makes your project generate OSGi bundles,
adds task to copy the
MANIFEST.MF
file and OSGi service declaration XMLs into the appropriate foldes to help eclipse recognize them. It also sets compile time dependencies forosgi.core
andosgi.compendium
, as well as runtime dependencies on Apache Felix SCR (to make sure declarative services are run).
Add repositories for dependency resolution
The UBstore plugin will add the following maven repositories in that precedence that will be used for dependency resolution:
- the local maven repository
- the UBStore repository
- Maven Central
This means that:
- You can just declare dependencies for anything that exists in the maven central repository (e.g. JUnit)
- You can just put dependency declarations for all UBStore components (core, extensions and implementations)
- If you develop an own bundle, you can use that too if you
install it to the local maven repository (
install
gradle task)
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
- Set the Java source and target to Version 7
- Set the file encoding to UTF-8
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:
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
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.
Copy generated OSGi related files
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:
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
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:
Run[projectname].launch
will start you application normallyDebug[projectname].launch
will run your application and set the JVM to wait for a debugger to connect. This allows remote debugging.ConnectDebugger[projectname].launch
will connect the eclipse debugger to such a waiting JVM, so can use Eclipses debugger.
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:
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: