...

Bundle is an OSGi Alliance term for a module in an OSGi Service Platform. A Bundle is packaged as a regular jar file with additional entries in its manifest. Every jar file in the repository is a valid OSGi bundle and can be deployed as-is into an OSGi Service Platform and the SpringSource dm Server. Bundles in the repository all define the following information:

• Bundle-Name: the human-readable name of the bundle, for example, "Spring Core".
• Bundle-SymbolicName: a string that (along with the version information) uniquely identifies the bundle. Symbolic names follow reverse domain-name conventions - for example, "org.springframework.core".
• Bundle-Version: the version of the bundle, e.g. 2.5.4
• Export-Package: the packages exported by the bundle. In OSGi only packages that are exported by the bundle are visible to other bundles. Packages that are not exported remain private to the bundle. When searching the repository for bundles providing certain classes or resources, only the exported packages are displayed and searched. Every package is exported with version information, for example, the Spring Core bundle, version 2.5.4 exports version 2.5.4 of the org.springframework.core package.
• Import-Package: the package-level dependencies of the bundle. These may be optional or mandatory dependencies. Each import specifies the version range it is compatible with (e.g. "version 2.5.0 or higher").

Where to find

...

existing bundles

Most of the libraries we use currently are available on the SpringSource Enterprise Bundle Repository and can be retrieved by Ivy.

Wrapping jar files into OSGi bundles

For the libraries that are not available as OSGi bundles, we need to create the bundle on our own. The tool that can help is Bnd. In the attachment of the page there is bnd-1.50.0.jar that can be used to generate the OSGi bundles from the existing jars via command line.: 

java -jar bnd.jar wrap -properties bnd_properties.bnd [source/path/toof/theyour/jar/filelibrary.jar]

Executing following command will create the jarName.bar file with the MANIFEST.MF file included. There is always the need to manually alter the manifest file after the generation. Please take care of the following:

1. Make sure that the Bundle-Version: header has the same version number as the library that we try to modify to bundle. This means that MANIFEST.MF for the guava-11.0.1 has to have the Bundle-Version: 11.0.1 header. Note that it is necessary to have a valid OSGi version, meaning that for example Hibernate libraries with 3.5.3-Final are not correct versions for OSGi and have to be changed to 3.5.3.FINAL.

2. Change the Bundle-SymbolicName: into the format: info.novatec.[artifact name]. This means that the old ivy dependency of 

   Code Block
   <dependency org="org.apache.httpcomponents" name="httpclient" rev="4.1.1" />

   should have the  Bundle-SymbolicName: info.novatec.httpclient in the manually generated bundle. 

3. Add the Bundle-Vendor: Novatec GmbH to the list of headers

After editing the manifest file, please update the name of the .bar file to the info.novatec.jarName.jar and upload the jar to our Nexus server with the following GAV parameters: 

...

The content of the bnd properties file is as follows:

version=3.2.16
artifact=spring-aop
Bundle-Version: ${version}
Bundle-Name: info.novatec.${artifact}
Bundle-SymbolicName: info.novatec.${artifact}
Export-Package: *;version="${version}"

The bnd_properties.bnd file above was used to wrap the spring-aop-3.2.16.RELEASE.jar file into an OSGi bundle. You have to modify the value of version (line 1) and artifact (line 2) to match your particular case. Leave the other lines untouched to ensure that your library is wrapped according to our guidelines.

Running the command as outlined above creates a *.bar file with the same name as the wrapped *.jar file. Change the file extension from *.bar to *.jar. You can overwrite the  default output name of the jar and directory by setting the -output property:

java -jar bnd.jar wrap -properties bnd_properties.bnd -output [target/path/of/your/bundle.jar] [source/path/of/your/library.jar]

Uploading to external Nexus

After creating such a jar, it needs to be uploaded to the external Nexus we use, so that the library can be resolved by Ivy. Please use the 3rd Party Dependencies repository on the Nexus for such upload uploads and correctly specify the GAV parameters when uploading a wrapped jar. Log-in credentials for the external Nexus can be found on the /wiki/spaces/IN/pages/5701787 page. 

Select GAV parameters as GAV Definition. 

Specifying dependencies

In the manifest for the Commons, CommonsCS and inspectIT projects we list all required plug-ins as a dependency via Required Plug-ins option.

inspectIT.product

The product file has to contain a list of all needed dependencies from all three mentioned plug-ins. Please keep the list of dependencies there up-to-date.

Ivy organisation

In the settings of the Ivy we have added the SpringSource repositories, so all budles that are available there can be used out of the box with Ivy. For the bundles that we generated we use Nexus as described.

All the OSGi based bundles should always be resolved to the osgi configuration. This should not be changed, because platform target we use in development is relying on the /lib/osgi folders of every plug-in project for the needed bundles.

info.novatec.inspectit.commons and info.novatec.inspectit.commmonscs

The ivy files in this two projects need to have duplicated lists of needed libraries, since this projects are used as normal java project in CMR and as plug-in in inspectIT RCP:

1. One configuration is osgi and should have all needed bundles
2. Second configuration is prod and should have normal libraries that will be needed for CMR run

This means that the ivy will define same dependencies twice, one in normal format, one in OSGi format. For example, this is the current look of the ivy.xml in the CommonsCS project:

...

Use the values you specified in your bnd properties file to replace ${artifact} and ${version} in the table above.

Specifying dependencies

In the manifest for the Commons, CommonsCS and inspectIT projects we list all required plug-ins as a dependency via Required Plug-ins option.

inspectIT.product

The product file has to contain a list of all needed dependencies from all three mentioned plug-ins. Please keep the list of dependencies there up-to-date.

Ivy organisation

In the settings of the Ivy we have added the SpringSource repositories, so all budles that are available there can be used out of the box with Ivy. For the bundles that we generated we use Nexus as described.

All the OSGi based bundles should always be resolved to the osgi configuration. This should not be changed, because platform target we use in development is relying on the /lib/osgi folders of every plug-in project for the needed bundles.

info.novatec.inspectit.commons and info.novatec.inspectit.commmonscs

The ivy files in this two projects need to have duplicated lists of needed libraries, since this projects are used as normal java project in CMR and as plug-in in inspectIT RCP:

1. One configuration is osgi and should have all needed bundles
2. Second configuration is prod and should have normal libraries that will be needed for CMR run

This means that the ivy will define same dependencies twice, one in normal format, one in OSGi format. For example, this is the current look of the ivy.xml in the CommonsCS project:

<?xml version="1.0" encoding="ISO-8859-1"?>
<ivy-module version="2.0" xmlns:e="http://ant.apache.org/ivy/extra">
	<info organisation="info.novatec.inspectit" module="CommonsCS"/>
	<configurations>
		<conf name="osgi" visibility="private" transitive="false"/>
    	<conf name="prod" visibility="private" transitive="false"/>
    </configurations>
    <!-- note that the manifest file stored in the resource sections needs to be updated to reflect
         any changes to the production libraries (changing of revisions is safe!) -->
    <!-- PLEASE UPDATE THE 3rd PARTY NOTIFICATION LIST IN CMR AND Agent build.xml FOR ANY CHANGE -->
	<!-- IMPORTANT
		 * OSGI based jars are used in inspectIT UI and it is necessary to have the same list of OSGi and normal jars
		 * Any added OSGi jar has to be added in the MANIFEST.MF of this project as a dependency
		 * Any added OSGI jar has to be added to the inspectIT.product as a dependency
	 -->
	<dependencies>
		<!-- OSGi plugins -- THE 3rd PARTY NOTIFICATION LIST IN CMR AND Agent build.xml FOR ANY CHANGE -->
	<!-- IMPORTANT
		 * OSGI based jars are used in inspectIT UI and it is necessary to have the same list of OSGi and normal jars
		 * Any added OSGi jar has to be added in the MANIFEST.MF of this project as a dependency
		 * Any added OSGI jar has to be added to the inspectIT.product as a dependency
	 -->
	<dependencies>
		<!-- OSGi plugins -->
		<dependency org="org.apache.commons" name="com.springsource.org.apache.commons.logging" rev="1.1.1" conf="osgi->compile" />
		<dependency org="org.apache.commons" name="com.springsource.org.apache.commons.lang" rev="2.5.0" conf="osgi->compile" />
		<dependency org="org.springframework" name="org.springframework.core" rev="3.1.0.RELEASE" conf="osgi->compile" />
		<dependency org="org.apache.commonsspringframework" name="com.springsource.org.apachespringframework.commons.loggingbeans" rev="3.1.10.1RELEASE" conf="osgi->compile" />
		<dependency org="org.apache.commonsspringframework" name="com.springsource.org.apache.commonsspringframework.langcontext" rev="23.51.0.RELEASE" conf="osgi->compile" />
		<dependency org="org.springframework" name="org.springframework.coreweb" rev="3.1.0.RELEASE" conf="osgi->compile" />
		<dependency org="org.springframework" name="org.springframework.beansasm" rev="3.1.0.RELEASE" conf="osgi->compile" />
		<dependency org="org.springframework" name="org.springframework.contextexpression" rev="3.1.0.RELEASE" conf="osgi->compile" />
		<dependency org="org.springframework" name="org.springframework.webaop" rev="3.1.0.RELEASE" conf="osgi->compile" />
		<dependency org="org.springframeworkaopalliance" name="com.springsource.org.springframework.asmaopalliance" rev="3.1.0.RELEASE0" conf="osgi->compile" />
		<dependency org="orgjavax.springframeworkservlet" name="orgjavax.springframework.expressionservlet" rev="3.10.0.RELEASEv201103241009" conf="osgi->compile" />
		<dependency org="orgnet.sourceforge.springframeworkcglib" name="org.springframework.aop="com.springsource.net.sf.cglib" rev="32.12.0.RELEASE" conf="osgi->compile" />
		<!-- Original jars for CMR production -->
		<dependency org="org.aopalliancecommons-logging" name="com.springsource.org.aopalliancecommons-logging" rev="1.01.01" conf="osgiprod->compile>default" />
		<dependency org="javax.servletcommons-lang" name="javax.servletcommons-lang" rev="3.0.0.v2011032410092.5" transitive="false" conf="osgiprod->compile>default" />
		<dependency org="netorg.sourceforge.cglibspringframework" name="spring-core" rev="com3.springsource1.net0.sf.cglibRELEASE" revtransitive="2.2.0false" conf="osgiprod->compile>default" />
		<!-- Original jars for CMR production -->
		<dependency org="commons-loggingorg.springframework" name="commons-logging" rev="1.1.1spring-beans" rev="3.1.0.RELEASE" transitive="false" conf="prod->default" />
		<dependency org="commons-langorg.springframework" name="commonsspring-langcontext" rev="2.53.1.0.RELEASE" transitive="false" conf="prod->default"/>
		<dependency org="org.springframework" name="spring-coreweb" rev="3.1.0.RELEASE" transitive="false" conf="prod->default"/>
		<dependency org="org.springframework" name="spring-beansasm" rev="3.1.0.RELEASE" transitive="false" conf="prod->default"/>
		<dependency org="org.springframework" name="spring-contextexpression" rev="3.1.0.RELEASE" transitive="false" conf="prod->default"/>
		<dependency org="org.springframework" name="spring-webaop" rev="3.1.0.RELEASE" transitive="false" conf="prod->default"/>
		<dependency org="org.springframeworkaopalliance" name="spring-asmaopalliance" rev="3.1.0.RELEASE" transitive="false" conf="prod->default"/>
		<dependency org="org.springframeworkcglib" name="springcglib-expressionnodep" rev="3.12.02.RELEASE2" transitive="false" conf="prod->default"/>
		<dependency org="org.springframework" name="spring-aop" rev="3.1.0.RELEASE" transitive="false" conf="prod->default"/>
		<dependency org="aopalliance" name="aopalliance" rev="1.0" transitive="false" conf="prod->default"/>
		<dependency org="cglib" name="cglib-nodep" rev="2.2.2" transitive="false" conf="prod->default"/>
	</dependencies>
</ivy-module>

For the build of the CMR we will use libraries defined in prod configuration and for the build of inspectIT RCP we will use the bundles defined in osgi configuration.

PDE Target Platform

All the OSGi bundles we retrieve via Ivy will be placed in the ${project_loc}/lib/osgi folder. However, when an Eclipse plug-in is run from the Development environment, we need to have those plug-ins available in the Eclipse/plugins/ folder. Since it is complicated for developer to constantly update the plugin folder of Eclipse installation manually, we have created the Target Definition for inspectIT RCP where all needed plug-ins are defined. 

The definition file is inspectit/inspectIT.target and defines four places as the source of required plug-ins for execution:

1. Commons/lib/osgi folder
2. CommonsCS/lib/osgi folder
3. inspectit/lib/osgi folder
4. Eclipse Indigo update site with plug-ins defined for Eclipse platform and Eclipse Platform SDK

...

</dependencies>
</ivy-module>

For the build of the CMR we will use libraries defined in prod configuration and for the build of inspectIT RCP we will use the bundles defined in osgi configuration.

PDE Target Platform

All the OSGi bundles we retrieve via Ivy will be placed in the inspectit.root/build/updatesite folder. However, when an Eclipse plug-in is run from the Development environment, we need to have those plug-ins available in the Eclipse/plugins/ folder. Since it is complicated for developer to constantly update the plugin folder of Eclipse installation manually, we have created the Target Definition for inspectIT RCP where all needed plug-ins are defined. 

The definition file is inspectit.root/resources/target/inspectIT.target and defines four places as the source of required plug-ins for execution:

1. inspectit.root/build/updatesite
2. Eclipse Indigo plug-ins defined for Eclipse platform and Eclipse Platform SDK located under inspectit.root/build/eclipse

Support for Java 1.8

Since Eclipse Indigo does not support Java 1.8, we have manually added JavaSE-1.8 profile to the needed jar (described https://stackoverflow.com/questions/24669940/java-8-missing-required-capability-require-capability-osgi-ee-filter-osg) and updated the patched Eclipse base to the Nexus under version 3.8.2_20170531. This is why target definition must point to the updated base and the update site for the Eclipse Indigo can not be used.