Config Files for Third Party JARs

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 new protocol handling capability. The standard way to extend the Carbon server runtime is to add those new libs as bundles in the <PRODUCT_HOME/repository/components/dropins/ directory. 

More often than not, these third party libs 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 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 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 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. 

Example:

A developer integrates a foo.jar bundle with the Carbon server by adding it to <PRODUCT_HOME>/repository/components/dropins. The bundles comes with foo.properties 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 the config-files/resources and load them as a fragment of the host bundle (foo.jar) during server startup. 

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

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