runOsgi {
    configSettings = 'equinox'
    programArgs = '-console'
}

For the rest of this tutorial, it does not matter which container you use, as everything will work exactly the same with either, but the examples will use Felix. You can even try Knopflerfish, another OSGi container, if you want. See the Knopflerfish sample in the osgi-run tests if you are interested.

Create a Java OSGi bundle and run it

As you can see, running a OSGi container is pretty easy, but what you are probably interested in doing is writing some code and getting it to run in OSGi.

Before we do that, let's consider what options OSGi gives us to bootstrap our application (if you already know OSGi well, feel free to skip this small detour).

In this tutorial, we will use Declarative Services annotations to bootstrap our application.

To make use of Declarative Services, we need to add a few things to the Gradle build file (added lines are bold and have a comment-number at the end):

git branch: hello-world

plugins {
    id "java"
    id "com.athaydes.osgi-run" version "1.5.0"
    id "org.dm.bundle" version "0.8.4" // 1
}

group 'osgi-run-tutorial'
version '1.0'

repositories {
    jcenter()
}

dependencies {
    compile "org.osgi:org.osgi.service.component.annotations:1.3.0" // 2
    osgiRuntime 'org.apache.felix:org.apache.felix.scr:2.0.2' // 3
}

runOsgi {
    bundles += project // 4
}

bundle {
    instruction '-dsannotations', '*' // 5
}

Explanation of the added lines (numbers in comments):

1. apply the org.dm.bundle Gradle plugin to turn the java project into a bundle.
2. add a dependency to the OSGi Declarative Services annotations jar (so we can annotate the Java code later).
3. instruct osgi-run to deploy the Felix SCR (Service Component Runtime) bundle to the OSGi container.
4. tell osgi-run to use all the default bundles (which include the gogo command-line interface for OSGi) plus this project as a bundle.
5. instruct bnd (via the org.dm.bundle plugin) to use DS annotations.

Create a Java class at src/main/java/osgirun/tutorial/Hello.java:

package osgirun.tutorial;

import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;

@Component( immediate = true )
public class Hello {

    @Activate
    public void start() {
        System.out.println( "Hello osgi-run" );
    }

}

The @Component annotation identifies the Hello class as a OSGi service. The immediate argument tells the SCR that this service must be started immediately when the container starts up. The default is false, which means that the Hello class should only start when some other service required it.

When the service is started, the OSGi container calls the @Activate method.

If everything goes well, we should see the following output when we start the container again:

Congratulations! You've just written an OSGi service.

I hope to write a more in-depth DS tutorial in the future, but for now, let's continue by showing how you can use an existing OSGi bundle.

Use a third-party OSGi bundle

osgi-run makes using a third-party bundle as easy as adding a dependency in the build file.

Add the following line to the dependencies block in the Gradle build file:

git branch: use-third-party-bundle

compile "com.google.guava:guava:19.0"

Let's also change the Hello class to use something from Guava and make sure that it works:

package osgirun.tutorial;

import com.google.common.collect.ImmutableList;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;

@Component( immediate = true )
public class Hello {

    @Activate
    public void start() {
        System.out.println( "Hello osgi-run " + ImmutableList.of( 'J', 'A', 'V', 'A' ) );
    }

}

Re-compiling and running the container again, you should see that everything works as expected:

Use a Java library which is not a OSGi bundle

One of the most common sources of frustration when you start using OSGi is to find out that not all Java libraries you might like are OSGi-ready. This means that if you try to use them in OSGi, you'll be faced with errors that you most likely have no previous experience with, and might not have enough understanding to solve (hence the frustration).

With osgi-run, the chances of that happening are much smaller because osgi-run will automatically wrap non-OSGi jars into OSGi bundles. By default, everything in the jar will be exported and available for use by other bundles, except code inside packages called internal. But you can customise how the wrapping should occur (for example, you can specify which packages should be exported, as you'll see in the next sections).

Let's suppose we want to use weather information in our application. The Yahoo Weather API is a great source of weather information... but to avoid having to consume a HTTP API directly, which can be cumbersome, let's use a Java library which does that for us: yahoo-weather-java-api.

Notice that this library is not a OSGi bundle.

To depend on this library, we add a normal Gradle dependency in the build file (you can replace the Guava dependency):

git branch: use-non-bundle

compile 'com.github.fedy2:yahoo-weather-java-api:2.0.0'

Change the Hello class to use the library:

package osgirun.tutorial;

import com.github.fedy2.weather.YahooWeatherService;
import com.github.fedy2.weather.data.Channel;
import com.github.fedy2.weather.data.unit.DegreeUnit;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;

@Component( immediate = true )
public class Hello {

    @Activate
    public void start() {
        try {
            YahooWeatherService service = new YahooWeatherService();
            Channel channel = service.getForecastForLocation( "Stockholm, Sweden", DegreeUnit.CELSIUS )
                    .first( 1 ).get( 0 );

            int temperature = channel.getItem().getCondition().getTemp();
            String conditions = channel.getItem().getCondition().getText();

            System.out.println( "Weather in Stockholm now: " +
                    temperature + "C, " + conditions );
        } catch ( Exception e ) {
            e.printStackTrace();
        }
    }

}

Re-compile and run the container again:

It should work perfectly.

If you run the gradle command with the --info option:

You will see that osgi-run quietly wrapped a couple of jars into bundles:

The first one is, as expected, the yahoo-weather-java-api jar. The second one, animal-sniffer-annotations, is a transitive dependency from the Felix SCR bundle.

You'll see how to remove the unnecessary animal-sniffer dependency and customise the wrapping of the yahoo-weather-java-api jar in the next section.

Analyse transitive dependencies and customise jars wrapping

You can see all your dependencies (and you should regularly check it to make sure no unintended libraries are included without your knowledge) by running the Gradle dependencies task (only relevant output shown):

osgiRuntime 'org.apache.felix:org.apache.felix.scr:2.0.2', {
    transitive = false
}

The Export-Package clause is usually what you need to worry about. Should this bundle be exporting com.github.fedy2.weather.binding. To be honest, I am not sure, but as we're not currently using that, let's suppose that this is an internal package we should not allow our application to use.

To make the generated bundle stop exporting this package, add the following block inside the runOsgi block in the Gradle build file (notice that, for documentation, we also add the Bundle-Description entry):

wrapInstructions {
    // use regex to match file name of dependency
    manifest( "yahoo-weather-java-api.*" ) {
        // export everything except the binding package and sub-packages
        instruction 'Export-Package', '!com.github.fedy2.weather.binding*', '*'
        instruction 'Bundle-Description', 'The Yahoo Weather Java API is used to provide weather data.'
    }
}

Compile and update a bundle without stopping the OSGi container

This time, instead of doing gradle clean, just keep the OSGi environment running and, from a different shell, run only the createOsgi task... 

Nothing will happen in the OSGi container just yet... you need to tell the OSGi container to update the bundle we've modified.. from the previous steps, we know the ID of the yahoo-api bundle is 8, so type update 8 in the gogo command line (the ID number may be different for you!):

To confirm that the bundle was updated, run headers 8 again:

package osgirun.tutorial;

import com.github.fedy2.weather.YahooWeatherService;
import com.github.fedy2.weather.data.Channel;
import com.github.fedy2.weather.data.unit.DegreeUnit;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;

import java.util.Scanner;

@Component( immediate = true )
public class Hello {

    @Activate
    public void start() {
        System.out.println( "Enter a location:" );
        String location = new Scanner( System.in ).nextLine();

        try {
            YahooWeatherService service = new YahooWeatherService();
            Channel channel = service.getForecastForLocation( location, DegreeUnit.CELSIUS )
                    .first( 1 ).get( 0 );

            int temperature = channel.getItem().getCondition().getTemp();
            String conditions = channel.getItem().getCondition().getText();

            System.out.println( "Weather in " + location + " now: " +
                    temperature + "C, " + conditions );
        } catch ( Exception e ) {
            e.printStackTrace();
        }
    }

}

Using Kotlin and OSGi

The next step in this tutorial is to show that you are not limited to Java when you want to use OSGi.

Let's see how to turn the Hello World Java code into Kotlin code, and then run it in OSGi.

The first thing to do is to replace the Java plugin with Kotlin's in the build file and add Kotlin as a dependency (notice that Kotlin has a special OSGi artifact, the standard jar does not work in OSGi).

git branch: use-kotlin

buildscript {
    ext.kotlin_version = '1.0.2'

    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

plugins {
    id "com.athaydes.osgi-run" version "1.5.0"
    id "org.dm.bundle" version "0.8.4"
}

apply plugin: 'kotlin'

group 'osgi-run-tutorial'
version '1.0'

repositories {
    jcenter()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-osgi-bundle:$kotlin_version"
    compile "org.osgi:org.osgi.service.component.annotations:1.3.0"
    osgiRuntime 'org.apache.felix:org.apache.felix.scr:2.0.2'
}

runOsgi {
    bundles += project
}

bundle {
    instruction '-dsannotations', '*'
}

Here's the initial Hello class written in Kotlin (if you're using IntelliJ, let it do it for you automatically), with a small change to prove the Kotlin code is actually running:

package osgirun.tutorial

import org.osgi.service.component.annotations.Activate
import org.osgi.service.component.annotations.Component

@Component(immediate = true)
class Hello {

    @Activate
    fun start() {
        println("Hello osgi-run ${listOf('k', 'o', 't', 'l', 'i', 'n')}")
    }

}

Now we can run our nicer Kotlin code in OSGi:

Using Frege for scripting in OSGi

In the last part of this tutorial, we'll see how to use a library which would usually be tricky to get working inside OSGi due to the fact that it uses its own classloader at runtime to load modules.

But this is not just any library: it's Frege, a Haskell for the JVM!

So, let's add a dependency on the Frege interpreter as a system lib, then use it with a ScriptEngine:

• ScriptEngines are looked up using Java's ServiceLoader mechanism, which does not normally work in OSGi.
• Frege, internally, will load classes (or Frege modules) at runtime. Because each bundle in OSGi has its own classloader, the Frege interpreter will not be able to find the modules it needs, even the Prelude.

    systemLib "org.frege-lang:frege-interpreter-core:1.2"

runOsgi {
    bundles = [ project ]
}

Now, let's implement a simple REPL using the Hello class (still written in Kotlin):

package osgirun.tutorial

import org.osgi.service.component.annotations.Activate
import org.osgi.service.component.annotations.Component
import java.util.*
import javax.script.ScriptEngineManager

@Component(immediate = true)
class Hello {

    @Activate
    fun start() {
        val prompt = "Frege > "
        val engine = ScriptEngineManager().getEngineByName("frege") ?:
                throw RuntimeException("Frege ScriptEngine was not found")

        // never block the Component's @Activate method
        Thread().run {
            val scanner = Scanner(System.`in`)

            val hasInput = {
                print(prompt)
                scanner.hasNextLine()
            }

            while (hasInput()) {
                val line = scanner.nextLine()
                if (line == "exit") {
                    break
                } else {
                    println(engine.eval(line) ?: "")
                }
            }
        }
    }

}

Finally, you can start using a simple Frege REPL written in Kotlin, using a OSGi service!

And that's all.

You now know how to write OSGi applications that can benefit from the best of both worlds: OSGi modularity, dynamics and services, and at the same time use any Java resources you might need.

Discussion on Reddit.