The final step in developing a LuciadLightspeed application is obfuscating the code. This step is required by Hexagon to transition to the deployment phase and brings 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 LuciadLightspeed, this operation can considerably reduce the size of the jars.

LuciadLightspeed and obfuscation

Your LuciadLightspeed license requires you to obfuscate the class files of the LuciadLightspeed API when you deploy your applications (i.e. application, applet, servlet, …​). This requirement serves as protection against uncontrolled distribution of the API. You are not required to obfuscate your own code, in the sense of changing its class names, method names, and field names, but you will have to process your code together with the LuciadLightspeed API, in order to make sure all references to the LuciadLightspeed API are updated correctly.

When your LuciadLightspeed application has been obfuscated, it is ready to be deployed. You should then replace the developer license file (development_license.jar) in your class path by an end user license file (deployment_license.jar).

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.

LuciadLightspeed comes with a collection of sample scripts and ProGuard configuration files that demonstrate how to obfuscate your application. To use them, download the most recent version of ProGuard and place its proguard.jar in the build/proguard folder of the LuciadLightspeed release, next to the configuration files (+*+.pro).

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 LuciadLightspeed-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. LuciadLightspeed 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 LuciadLightspeed 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.