How to Add External Jar Libraries to WSO2 Carbon based Products.

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Sameera Jayasoma
  • 12 Mar, 2010

WSO2 Carbon is a componentized Service Oriented Platform(SOA) platform which is build on top OSGi. OSGi defines a way to create true modular systems. The unit of modularization in OSGi is called a bundle. Legacy Java applications is collection of Jar files and OSGi application is a collection of modules/bundles. Bundle is just a jar file with some additional manifest headers.

Since WSO2 Carbon is based on OSGi, you can only extend the platform by dropping OSGi bundles. But most of the users are still new to OSGi, hence we have provided a mechanism to convert legacy jar files to OSGi bundles.

The OSGi repository of WSO2 Carbon is located inside the $CARBON_HOME/repository/components folder. $CARBON_HOME is the folder where you extracted an Carbon or Carbon based product. You can use following directories to drop external user libraries. But you need to restart the server after adding libraries.


This is the place where you can drop OSGi bundles.


The jar files you drop into this folder will be converted to OSGi bundles during the next server startup.


The jar files you drop into this folder will be converted to OSGi framework Extension bundles during the next server startup. Following section will give you a brief description about OSGi bundles.

In most of the cases, external user libraries should be dropped into the components/lib folder. But in certain situations you might need to drop the library to components/extensions folder. Please refer the following section for more information.

OSGi uses Java package as the unit of information hiding. Hence OSGi allows bundles to share packages among other bundles or to hide package from other bundles. OSGi achieves this level of information hiding by assigning a separate class loader for a bundle. And this bundle class loader can load classes from system class loader, other bundles class loader and from the bundle's jar files.

The system bundle is bundle which represent the OSGi framework. Implementation classes of the OSGi framework reside inside the system bundle. It exports packages loaded from the system classpath. i.e. from the application class loader.

Fragments are bundle which can be attached to host bundles by the framework. Once attached fragments are considered as part of the host bundle and the fragment shares the host bundles class loader.

Framework extension bundles is a special type of fragment bundles. They can be attached to the system bundle. They can provide functionality which should be reside on the boot class path. This is necessary because certain Java package implementation assume that they are on the boot class patch or required to be available to all clients. An example of a boot class path extension is an implementation of java.sql such as JSR 169. One other use case of extension bundles is to provide optional parts of the framework implementation.


Sameera Jayasoma

Senior Software Engineer