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

More often than not these third party libs comes 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 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 bundles 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 relevant host bundles during server startup time. 

Example:

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

1. Create directory named foo under $CARBON_HOME/repository/conf/bundle-config.
   The directory name is how the server derives the host bundle that it should attach the fragment bundle.
2. Place the resources/config files under the newly created foo directory.
3. Start the server with -DosgiConsole flag
4. Upon executing 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 $CARBON_HOME/repository/components/dropins