When you are customizing the configuration file of a standard Lucy add-on, it is recommended not to change that configuration file directly. If you modified the original file directly, you would have to re-apply those changes each time you upgrade to a new version.

To customize the Lucy configuration and leave the original configuration files intact:

  1. Create a new configuration file

  2. Make that new file refer to the original configuration file with the includeConfig property.

  3. Copy the property you want to modify from the original file to the new file, and give it a different value in the new file. The value in the new file will override the value in the old file.

  4. Adjust the add-on configuration to use that new configuration file.

We’ll illustrate this using an example where we switch off the Lucy decoding support for data in the SVG format. To do so, you simply need to modify a setting in the Lucy decoders add-on. To protect your re-configuration work in the long run, we add a few steps to preserve the SVG format exclusion through future product upgrades.

  1. Look up the entry for the add-on you want to modify in the addons.xml file. This entry contains the link to the original configuration file, which we need in the next step. You will also require the remainder of the information in that entry in one of the last steps.

    To exclude SVG format support, we need to modify a setting of the TLcyDefaultDecodersAddOn. The entry in the addons.xml file for this add-on is: 

    <addon>
  <priority>data_producer</priority>
  <name>Default Formats</name>
  <class>com.luciad.lucy.addons.decoders.TLcyDefaultDecodersAddOn</class>
  <configFile>lucy/decoders/default_decoders.cfg</configFile>
</addon>

    The addons.xml file can use the <include> tag to include other XML files. If you do not find the entry of the add-on in the addons.xml file, make sure to check each of the included XML files as well.

    In this example, the entry for the TLcyDefaultDecodersAddOn is actually included in the addons_data.xml file.

  2. Create a new configuration file in a folder located on the classpath of your application. The new configuration file must point to the original configuration file of the add-on: define an includeConfig property, and re-use the link value you found in the <configFile> tags of the original add-on entry in the previous step. Next, re-define only those settings that you want to adjust.

    Because we just want to exclude the SVG format, we change only the value of the SVGFormat property from true to false.

    custom_default_decoders.cfg
    # Include the original config file.
# Use the value of the addon entry you looked up in the previous step
includeConfig = lucy/decoders/default_decoders.cfg

# Because we included the original file, we only have to specify the options
# we want to adjust.

# In this example, we only exclude the SVG format support
# and leave the remainder of the options untouched
SVGFormat = false

  3. Ensure that Lucy uses the custom configuration file instead of the default configuration file. The best way to do this is by creating a custom addons.xml file. Just like in the custom configuration file, the custom addons.xml file must include the original file, and override only the entry for the add-on we want to modify, the TLcyDefaultDecodersAddOn in this case.

    custom_addons.xml
    <?xml version="1.0" encoding="UTF-8"?>
<addonConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:noNamespaceSchemaLocation="../../../lucy/addons.xsd">
  <addons>
    <!-- Including the original addons.xml file to avoid having to specify all add-ons here -->
    <include>lucy/addons.xml</include>

    <!-- Adjusting the configuration file can be done by including the original entry,
         but altering the configFile option. The other options must be identical. -->
    <addon>
      <priority>data_producer</priority>
      <name>Default Formats</name>
      <class>com.luciad.lucy.addons.decoders.TLcyDefaultDecodersAddOn</class>
      <configFile>path/to/custom_default_decoders.cfg</configFile>
    </addon>
  </addons>
</addonConfiguration>

    We create our own addons.xml file for the same reason we created a new configuration file. The custom add-on file keeps the original files of the release intact, and will make upgrading easier.

  4. In the final step, we pass the custom_addons.xml file to Lucy, by providing it as an argument to TLcyMain: 

    TLcyMain.main(new String[]{"-addons", "path/to/custom_addons.xml"});

    or as program argument to the Lucy.bat or Lucy.sh file: 

    Lucy.bat -addons path/to/custom_addons.xml

    See How to customize the add-ons used by your application for more details on how to use a custom addons.xml file.