This documentation is for WSO2 Carbon 4.4.0. View documentation for the latest release.
Page Comparison - Config Files for Third Party JARs (v.1 vs v.2) - Carbon 4.4.0 - WSO2 Documentation
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

At times the need arises for developers or users to extend the functionalities of the Carbon servers. For an example, one might want to use a new Java library that implements a cool new protocol handling capabilitiescapability. The standard way to extend the Carbon server runtime , is to add those new libs as bundles in the $CARBONthe <PRODUCT_HOME/repository/components/dropins directory/ directory. 

More often than not, these third party libs comes come with their own config files. In a typical non-OSGi application those config files will be picked from the application classpath . (implementations can differ; however, it can share one common classpath across all the libs). 

Carbon being an OSGi application , does not share a common classpath among its libraries. Each bundle in the environment has a unique bundle classLoader which resolves into a unique classpath. In such scenarios there are three possible solutions which are:

  1. Bundle the config files along with the library class files
    This . This will ensure that config files always resides in the bundle classpath. The biggest disadvantage is that, you cannot edit the config files during server restarts.
  2. If the third party library accepts the config file path via a system property, we can set that system property prior to invocation of the library.
    This  This is a very clean approach.
  3. Bundle the config file as a fragment of the main library and attach them during the startup of the server.

Fragment will attach to its host bundle during runtime and will share the same bundleloader of host bundle. As a result, the host bundle will have the access to fragment bundles bundle resources (since it shares the classpath).

Follow the steps below to allow Carbon servers to convert your resources into fragment bundles and attach them to the relevant host bundles during server startup time. 


A developer integrates a foo.jar bundle  bundle with the Carbon server by adding it to $CARBONto <PRODUCT_HOMEHOME>/repository/components/dropins. The bundles comes with file that has to be changed according to the running environment. The developer decides to follow the third approach mentioned above, which is to separate out the the config-files/resources and  and load them as a fragment of the host bundle (foo.jar) during the server startup. 

  1. Create a directory named foo under $CARBON_HOMEnamed foo under <PRODUCT_HOME>/repository/conf/etc/bundle-config.
    The directory name is how the server derives the host bundle that it should attach to which the fragment bundle should be attached.
  2. Place the the resources/config files  files under the newly created created foo directory directory.
  3. Start the server with with -DosgiConsole flag.
  4. Upon executing the ss command  command you should see the new fragment bundle named named foo.config-1.0.0.jar that  that has the the foo.jar as  as its host.

The server created bundle (that was created from created from the developer given given resources/properties files files) can be found in $CARBONin <PRODUCT_HOMEHOME>/repository/components/dropins.