Add OSGi manifest headers

[mattbishop]

Those of us on OSGi environments (like eclipse, netbeans, glassfish) cannot use rxjava-core or the other adapters without OSGi headers being added to the manifest.

This is pretty easy to do using the Maven Bundle plugin from apache Felix.

[benjchristensen]

This looks pretty straight-forward to do with Gradle: http://www.gradle.org/docs/current/userguide/osgi_plugin.html

Since I have not used OSGi before, is there anything special about what the headers need to contain or is it basically the same information used to post to Maven Central?

For example, this pom file: http://search.maven.org/#artifactdetails%7Ccom.netflix.rxjava%7Crxjava-core%7C0.5.3%7Cjar

[mattbishop]

This plugin looks similar enough to the felix plugin (which also uses BND) that it should work. The import/exports of RxJava are minimal and discoverable by the java code. There aren't any Class.forName() calls right?

[benjchristensen]

There is one place Class.forName is used – to automatically load the plugins when they are in the classpath:

https://github.com/Netflix/RxJava/blob/master/rxjava-core/src/main/java/rx/util/functions/Functions.java#L49

Language adaptors can also be manually loaded using Functions.registerLanguageAdaptor(Class<?>[] functionClasses, FunctionLanguageAdaptor adaptor)

https://github.com/Netflix/RxJava/blob/master/rxjava-core/src/main/java/rx/util/functions/Functions.java#L63

[mattbishop]

Interesting. This means the language plugins are going to have to be "bundle fragments" instead of plain bundles. That means that the plugin jars will be bound to the main rxjava-core jar at runtime as a logically-merged bundle. I haven't used gradle so my best-guess addendum for the language plugins would be:

instruction 'Fragment-Host', 'com.netflix.rxjava.rxjava-core'

This means the jar being built (like the groovy plugin) is a fragment, whose host is rxjava-core. At runtime OSGi will fit the two together.

[mattbishop]

If you set up the gradle changes I am happy to test.

[benjchristensen]

I'd appreciate that as I have no way to know if it's successful or not, so I'll create a branch with the gradle changes and then if you can play with and modify the values as necessary that would be great. I'm working on something else right now that I need to get done and then can work on this.

[mattbishop]

NP, gives me a chance to experience gradle. :)

On Fri, Feb 22, 2013 at 6:07 PM, Ben Christensen
notifications@github.comwrote:

I'd appreciate that as I have no way to know if it's successful or not, so
I'll create a branch with the gradle changes and then if you can play with
and modify the values as necessary that would be great. I'm working on
something else right now that I need to get done and then can work on this.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/154#issuecomment-13978672.

[benjchristensen]

I've got a jar building with the OSGi headers but that's where I stop having any idea what to put in as the headers, so I'd appreciate you getting it working as needed and submitting the pull request.

Here is how I did it:

1. Edit build.gradle of the module to change. For example, ./rxjava-core/build.gradle

I added this line at the top:

apply plugin: 'osgi'

and this at the bottom:

jar {
    manifest { 
        name = 'rxjava-core'
        instruction 'Bundle-Vendor', 'Netflix'
        instruction 'Bundle-DocURL', 'https://github.com/Netflix/RxJava'
    }
}

I then run a build:

$ ./gradlew clean build

I then see the MANIFEST file by doing this:

$ cd ./rxjava-core/build/libs/
$ jar xvf rxjava-core-0.5.4-SNAPSHOT.jar 
$ cat META-INF/MANIFEST.MF 

I see the new manifest headers that normally aren't there without the build.grade changes above.

[mattbishop]

Hi Ben, I will give it a go next week.

On Wed, Feb 27, 2013 at 2:49 PM, Ben Christensen
notifications@github.comwrote:

I've got a jar building with the OSGi headers but that's where I stop
having any idea what to put in as the headers, so I'd appreciate you
getting it working as needed and submitting the pull request.

Here is how I did it:

1. Edit build.gradle of the module to change. For example,
   ./rxjava-core/build.gradle

I added this line at the top:

apply plugin: 'osgi'

and this at the bottom:

jar {
manifest {
name = 'rxjava-core'
instruction 'Bundle-Vendor', 'Netflix'
instruction 'Bundle-DocURL', 'https://github.com/Netflix/RxJava'
}}

I then run a build:

$ ./gradlew clean build

I then see the MANIFEST file by doing this:

$ cd ./rxjava-core/build/libs/
$ jar xvf rxjava-core-0.5.4-SNAPSHOT.jar
$ cat META-INF/MANIFEST.MF

I see the new manifest headers that normally aren't there without the
build.grade changes above.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/154#issuecomment-14205447
.

[mattbishop]

I added in your jar {} section and it does generate OSGi headers in the manifest.

However, the unit tests are in the source code so it inserts dependencies for junit and mockito. I can strip them out with custom BND instructions to the OSGi plugin, but are these tests going to stay in the main src dir or will they move to a separate tests dir?

[mattbishop]

Please add this one line to the jar {} section:

    instruction 'Import-Package', '!org.junit,!junit.framework,!org.mockito.*,*'

This should mask out the unit testing packages.

NOTE: Make sure you set your version to a release name (non-SNAPSHOT) before building the project. The manifest exports specific versions of rx; right now that version is "version="0.5.5.SNAPSHOT" which will fail if the actual maven artifact version is 0.5.5.

Thanks, if you do move the tests out of the main source dir then the Import-Package instruction can be removed.

[benjchristensen]

The unit tests will not be moved out. They are there on purpose.

The JUnit dependency is marked as 'provided' (https://github.com/Netflix/Hystrix/blob/master/hystrix-core/build.gradle#L9) but not included as part of the runtime dependencies when published to Maven Central: http://search.maven.org/#artifactdetails%7Ccom.netflix.hystrix%7Chystrix-core%7C1.2.12%7Cjar

Does the addition of just the following OSGi headers satisfy your requirements?

jar {
    manifest { 
        name = 'rxjava-core'
        instruction 'Bundle-Vendor', 'Netflix'
        instruction 'Bundle-DocURL', 'https://github.com/Netflix/RxJava'
        instruction 'Import-Package', '!org.junit,!junit.framework,!org.mockito.*,*'
    }
}

What about the 'bundle fragments' that you mentioned would be needed for the language-adaptors? Or do I simply just add these same headers to each of those other jars as well (with their appropriate names of course)?

[mattbishop]

The 'provided' scope still means a runtime dependency rather than a test time dependency. I don't understand why they are not separated but that doesn't matter as long as it can be managed out of the dependencies.

As for the language adapters, let me have a look at them. They will need their own instructions for gradle including the fragment instruction.

[mattbishop]

...and to answer the question for core, yes that manifest instruction set is good.

[benjchristensen]

I'll wait on your answer for the language-adaptors and then commit the changes.

Yes, it's "runtime" for running the tests, but not for production usage which is why they are marked as provided and not needed as transitive dependencies. Reasons if you care are here: http://benjchristensen.com/2011/10/23/junit-tests-as-inner-classes/