Provide OSGi Metadata

[GoogleCodeExporter]

As many libraries already do, it would be great if ez-vcard would provide OSGi 
metadata out-of-the-box, too, so that it can be easily used in an OSGi 
environment.

Changes to the POM:
 1. Replace:
<packaging>jar</packaging>
with
<packaging>bundle</packaging>

 2. Add:
<build>
        <plugins>
            ...
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.4.0</version>
                <extensions>true</extensions>
            </plugin>
            ...
        </plugins>
    </build>

 3. Eyeball the generated Manifest file and tweak it if needed by configuring the maven-bundle-plugin

What is the expected output?
A Manifest with OSGi metadata

What is the actual output?
A Manifest without OSGi metadata

What version of ez-vcard are you using?
0.9.0

What version of Java are you using?
1.7.0_45; Java HotSpot(TM) 64-Bit Server VM 24.45-b08

Please provide any additional information below.

Original issue reported on code.google.com by puce1977 on 29 Nov 2013 at 10:14

[GoogleCodeExporter]

I attached a patch.

Original comment by puce1977 on 30 Nov 2013 at 10:43

Attachments:

• ez-vcard-osgi.patch

[GoogleCodeExporter]

The generated Mainfest file (on my machine) looks like this now:

Manifest-Version: 1.0
Bnd-LastModified: 1385808303005
Build-Jdk: 1.7.0_45
Built-By: puce
Bundle-Description: A library that reads and writes vCards, supporting a
 ll versions of the vCard standard (2.1, 3.0, and 4.0) as well as xCard 
 (XML-encoded vCards), hCard (HTML-encoded vCards), and jCard (JSON-enco
 ded vCards).
Bundle-License: http://opensource.org/licenses/bsd-license.php
Bundle-ManifestVersion: 2
Bundle-Name: ez-vcard
Bundle-SymbolicName: com.googlecode.ez-vcard
Bundle-Vendor: Michael Angstadt
Bundle-Version: 0.9.1.SNAPSHOT
Created-By: Apache Maven Bundle Plugin
Export-Package: ezvcard;uses:="ezvcard.io.scribe,ezvcard.parameter,ezvca
 rd.property,ezvcard.util,javax.xml.transform,org.w3c.dom,org.xml.sax";v
 ersion="0.9.1.SNAPSHOT",ezvcard.io;uses:="ezvcard,ezvcard.property";ver
 sion="0.9.1.SNAPSHOT",ezvcard.io.text;uses:="ezvcard,ezvcard.io.scribe,
 ezvcard.parameter,ezvcard.property";version="0.9.1.SNAPSHOT",ezvcard.io
 .json;uses:="com.fasterxml.jackson.core,ezvcard,ezvcard.io.scribe,ezvca
 rd.parameter,ezvcard.property";version="0.9.1.SNAPSHOT",ezvcard.io.html
 ;uses:="ezvcard,ezvcard.io.scribe,ezvcard.property,org.jsoup.nodes";ver
 sion="0.9.1.SNAPSHOT",ezvcard.io.scribe;uses:="ezvcard,ezvcard.io,ezvca
 rd.io.html,ezvcard.io.json,ezvcard.io.xml,ezvcard.parameter,ezvcard.pro
 perty,ezvcard.util,javax.xml.namespace,org.jsoup.nodes,org.w3c.dom";ver
 sion="0.9.1.SNAPSHOT",ezvcard.io.xml;uses:="ezvcard,ezvcard.io.scribe,e
 zvcard.property,javax.xml.namespace,javax.xml.transform,org.w3c.dom,org
 .xml.sax";version="0.9.1.SNAPSHOT",ezvcard.property;uses:="ezvcard,ezvc
 ard.parameter,ezvcard.util,org.w3c.dom,org.xml.sax";version="0.9.1.SNAP
 SHOT",ezvcard.util;uses:="javax.xml.transform,org.jsoup.nodes,org.jsoup
 .select,org.w3c.dom,org.xml.sax";version="0.9.1.SNAPSHOT",ezvcard.util.
 org.apache.commons.codec;version="0.9.1.SNAPSHOT",ezvcard.util.org.apac
 he.commons.codec.binary;uses:="ezvcard.util.org.apache.commons.codec";v
 ersion="0.9.1.SNAPSHOT",ezvcard.util.org.apache.commons.codec.net;uses:
 ="ezvcard.util.org.apache.commons.codec";version="0.9.1.SNAPSHOT",ezvca
 rd.parameter;uses:="ezvcard,ezvcard.util";version="0.9.1.SNAPSHOT"
Import-Package: com.fasterxml.jackson.core;version="[2.1,3)",freemarker.
 template,javax.xml.namespace,javax.xml.parsers,javax.xml.transform,java
 x.xml.transform.dom,javax.xml.transform.stream,javax.xml.xpath,org.jsou
 p;version="[1.7,2)",org.jsoup.nodes;version="[1.7,2)",org.jsoup.select;
 version="[1.7,2)",org.w3c.dom,org.xml.sax
Tool: Bnd-2.1.0.20130426-122213

Original comment by puce1977 on 30 Nov 2013 at 10:47

[GoogleCodeExporter]

If you have some classes which you just need internally but don't actually 
belong to the API and if you don't want to guarantee backwards compatibility 
for those classes, then you should exclude them from from "Export-Package".

The easiest way is to put those classes in a *.impl.* or *.internal.* package 
as the Maven Bundle Plugin excludes these packages by default.

Original comment by puce1977 on 30 Nov 2013 at 10:56

[GoogleCodeExporter]

Note: jackson-core and jsoup already contain the OSGi metadata but freemarker 
doesn't.

Original comment by puce1977 on 30 Nov 2013 at 11:12

[GoogleCodeExporter]

fremarker v2.3.20 contains the OSGi metadata. Please upgrade the dependency.

Original comment by puce1977 on 30 Nov 2013 at 12:01

[GoogleCodeExporter]

Updated patch which uses fremarker v2.3.20

Original comment by puce1977 on 30 Nov 2013 at 12:06

Attachments:

• ez-vcard-osgi.patch

[GoogleCodeExporter]

Sounds good, thanks for this. :)  Is there anything else that needs to be done? 
 I saw something about an "activator" when reading the Wikipedia page on OSGi.  
And do you know why the build fails with the original <resource> configuration?

Original comment by mike.angstadt on 4 Dec 2013 at 3:45

• Changed state: Accepted

[GoogleCodeExporter]

OSGi provides 3 layers: the module layer, the lifecycle layer and the service 
layer.

The module layer controls what code can be accessed by which bundle and the 
OSGi metadata in the Manifest file is the way to control this.

The activator gives a hook to the bundle's lifecycle management. You only need 
this if you activly want to do something when the bundle gets started rather 
than waiting to get called from code of another bundle.

The service layer allows to search and provide service implementations (e.g. a 
VCardImporter which implements some common a Importer interface).

It's possible that the library could benefit from the lifecyle and service 
layer as well, but for the start, the provided patch is enough to access the 
ez-vcard classes from another bundle.

Original comment by puce1977 on 4 Dec 2013 at 9:54

[GoogleCodeExporter]

Regarding the changed resource configuration: I'm not sure why it works with a 
jar-packaging but not with a bundle-packaging, but actually I'm more suprised 
that it did work before.

When you filter binary files with Maven usually the resulting file gets 
corrupted. Maybe there was some slight corruption or just a simple precaution 
which failed the filtering of the png files when using the Maven Bundle Plugin, 
altough the resulting png files surprisingly still could be opened before.

Original comment by puce1977 on 4 Dec 2013 at 10:01

[GoogleCodeExporter]

Hmm strange.  Well thanks again for the patch.  If you think ez-vcard could 
benefit from plugging into the other layers, let me know. :)

Original comment by mike.angstadt on 4 Dec 2013 at 10:55

• Changed state: Fixed