As a final step in developing a LuciadFusion application, you can obfuscate the code. This is an optional step that can bring several benefits for your application:

  • Protection of the source code of an application from reverse engineering.

  • Reduction of application footprint. Obfuscated names are shorter and can significantly reduce the application footprint. Obfuscation programs, such as ProGuard, also allow for other optimizations. One example is ‘shrinking’ which removes unused byte code. This can also drastically reduce the application footprint. Experiments with Lucy resulted in a functional Lucy application that was less than 4MB in size.

What is obfuscation?

Obfuscating Java class files means replacing the original class names, method names, and field names by short, meaningless names. For instance, obfuscation may rename a method double getX() to double a(). Obfuscation makes it much harder to reverse engineer the code. Although it does not necessarily make decompilation impossible, understanding the decompiled code becomes more difficult.

Obfuscation also removes the debugging information that is not required for deployment. By default, Java class files still contain all class/method/field/argument/variable names, source file names, and source line numbers. Removing this information typically reduces the footprint of the application by 30% as an interesting side-effect.

In addition, many obfuscating tools further shrink the processed applications by removing classes, methods, and fields that are not actually used in the code. Especially when your are using large APIs like LuciadFusion, this operation can considerably reduce the size of the jars.

LuciadFusion and obfuscation

You can choose to obfuscate the class files of the LuciadFusion API when you deploy your applications (i.e. application, a servlet, …​). Obfuscating the class files serves as protection against uncontrolled distribution of the API. If you obfuscate your own code too, in the sense of changing its class names, method names, and field names, you will have to process your code together with the LuciadFusion API, to make sure all references to the LuciadFusion API are updated correctly.

How to obfuscate your application

In these instructions, it is assumed that you are using a recent version of the obfuscation program ProGuard, which we highly recommend.

LuciadFusion comes with a collection of sample scripts and ProGuard configuration files that demonstrate how to obfuscate your application. To use them, install ProGuard by following the instructions in this article.

The sample deployment scripts are located in build/samples and build/fusionplatform. The scripts are written for Ant, which is also included in the release.

You can call the *.xml scripts directly using Ant, or you can call one of the wrapper shell scripts (*.bat or *.sh) to automatically use the bundled Ant. The sections below explain how you can use the scripts for basic obfuscation. For a more advanced usage, see the documentation in the script source files.

Using the sample deployment scripts to obfuscate your code

To obfuscate an application with ProGuard, you must specify a few things. The sample scripts take care of all of this and do not require any parameters:

  • injars: the code to be obfuscated. This means all Luciad jars (lcd_*.jar) and your own code.

  • libraryjars: all dependencies of the code. This means all other jars, including the Java run-time libraries.

  • outjars: a directory or jar file to write the obfuscated result to.

  • The configuration to use, either specified directly or in a .pro file.

We suggest using the sample scripts as a guide when obfuscating your own application.

Configuring ProGuard correctly

The sample configuration files in build/proguard specify all required and recommended settings for deploying and obfuscating a LuciadFusion-based application. They can be included in your own configuration with -include and are also used in the sample scripts mentioned above. If you are modifying or extending these configuration files, take the following into account:

  • Obfuscators typically rename all classes by default, making their names unrecognizable. Therefore, at least specify the main class of your application to the obfuscator, so its name can be preserved as an entry point.

  • The names of classes that are instantiated dynamically, based on their names (using the method Class.forName), must be preserved. For instance, classes that implement javax.swing.plaf.ComponentUI are instantiated dynamically, so their names must be kept. LuciadFusion also instantiates a number of classes dynamically. For instance, all implementations of ILcdGXYPainter and ILcdGXYEditor in the packages com.luciad.internal.symbology and sub-packages have to be kept.

  • You can find a complete list of LuciadFusion classes that have to be preserved in the configuration file /build/proguard/luciad_fusion_platform_service.pro. You can find a sample configuration for processing all the samples in the file build/proguard/samples.pro.

Troubleshooting

Refer to How to fix common obfuscation problems for more information.