Class And Interface Merging

Property settings

This optimization is turned ON by default. By default it is configured to operate in Simple mode with CLASS.MERGING.SIMPLE.LEVEL=8

 

In the properties file,
OPT.CLASS.MERGING=ON turns on this optimization
OPT.CLASS.MERGING=OFF turns off this optimization

mBooster reduces the number of Java classes and interfaces by combining them. As of mBooster 2.5, mBooster is capable of merging classes that are instantiated.

To guarantee correctness, the extensive safety checks are by necessity conservative. The user may optionally relax some of these checks through this set of properties. In addition if a class is specified in the REFLECTEDCLASSES property, it is excluded from class merging.

mBooster provides two methods to control the process of class merging:

  1. Simple mode is easy to configure, and generally provides good results.
  2. Advanced mode allows fine-grain control of the class merging process for heap memory constrained J2ME applications. This mode enables maximum size reduction while allowing the user to budget for heap memory usage increase. In this mode the user is expected to supply the instance count of every Java class.


By default mBooster is configured to operate in Simple mode with CLASS.MERGING.SIMPLE.LEVEL=8

Tips
  • This optimization is particularly useful in conjunction with an objected oriented programming framework. It reduces the overhead of the object oriented programming style.
  • Keep the class initializer and static field initializers simple. A complex class initializer or static field initializers, for example one that calls methods in a different class, is likely to rule the class out from class merging.
  • mBooster currently does not perform class merging if the two candidate classes are in different packages. Most obfuscators have the ability to combine packages. It is highly recommended to configure your obfuscator to combine packages as this would significantly increase class merging opportunites and result in significantly smaller JAR files.

    If you are using Proguard, the configuration file should look like this:
    Proguard configuration file fragment
    ...
# Tells Proguard to combine packages
-defaultpackage
...

Heap usage

mBooster is capable of merging instantiated classes. When two instantiated classes are merged, the merged class may have more fields than either of the original classes. As a result class merging may increase the heap usage of the application.

mBooster offers two modes to allow the user to control the process of the class merging and the consequential increase in heap memory usage. Please see Simple mode and Advanced mode for details.

If the optimized application runs out of heap memory, please

  • Consider using Advanced mode. Advanced mode allows you to specify explicitly the allowable heap memory usage increase.
  • OR set the CLASS.MERGING.SIMPLE.LEVEL property to a lower value. Setting to 0 would prohibit any class merging that results in increased heap memory usage.

Simple mode

Simple mode is selected by setting CLASS.MERGING.MODE=1.

When operating in Simple mode, the set of class merged is determined by the CLASS.MERGING.SIMPLE.LEVEL and CLASS.MERGING.SIMPLE.AVOID.CLASSES properties. When CLASS.MERGING.SIMPLE.LEVEL is set to the maximum setting (10), all possible classes are merged to give the smallest JAR file. When this property is set to the minimum setting (0), classes are only merged as long as the heap memory usage does not increase as a result.

Classes specified in the CLASS.MERGING.SIMPLE.AVOID.CLASSES property are never merged, unless the heap memory usage for instances of that class will not increase following the merge.

Tips

If the application is constrained by the amount of heap memory available on the handset, it is generally recommended to specify the classes with many concurrent instances in the CLASS.MERGING.SIMPLE.AVOID.CLASSES property.

In simple mode, the MBOOSTER_MAX_INSTANCES field can be used as a more convenient way to identify classes which must not be merged when their usage increases ('avoided') and classes that can never be merged ('excluded'). Other values of the field will be ignored, please see here.

Advanced mode

Advanced mode is selected by setting CLASS.MERGING.MODE=2

Advanced mode enables fine grain control of the class merging process providing you with the ability to specify the maximum heap usage increase through the property CLASS.MERGING.ADVANCED.MAX.HEAP.INCREASE.

In determining how and what classes to merge, the algorithm takes account of the maximum number of concurrent instances of each class. This means you must provide an estimate of the maximum number of simultaneous instances of each class (not the total over execution of the program). There are two ways to specify this information:

  1. If there exists a static final int field named MBOOSTER_MAX_INSTANCES in a class, the constant value assigned indicates the maximum number of instances.
  2. The property CLASS.MERGING.ADVANCED.MAX.INSTANCES specifies the maximum instance counts. This property overrides the value specified in the corresponding MBOOSTER_MAX_INSTANCES field.

For a particular class, if no instance information is supplied through the MBOOSTER_MAX_INSTANCES field or the CLASS.MERGING.ADVANCED.MAX.INSTANCES property, it becomes an 'avoided' class and will only be merged with another class if doing so will not increase the heap usage of instances of the avoided class.

Meaning of the Max Instances field

The MBOOSTER_MAX_INSTANCES field must be of type static final int and be initialized with a constant value.

There are special meanings to two possible values:

  • -1 indicates the class is an 'avoided' class
  • -2 indicates the class must not be merged with any other. (Equivalent to using the CLASS.MERGING.EXCLUDE property)


For interfaces and any class declared abstract, we assume the value of 0 unless that class is marked for 'excluded'(-2) or 'avoided'(-1).

For any class with subclasses, only consider the count of instances of that class without including the instances of subclasses.

The following example code fragement demonstrates how to specify the maximum number of current instances using the MBOOSTER_MAX_INSTANCES field.

code fragement
class MyClass {
    ...
    // Tell mBooster that there is a maximum of 5 concurrent instances. 
    // This field must be static final.
    static final int MBOOSTER_MAX_INSTANCES = 5;
    ...
}
Warning

A number of obfuscators will automatically remove static final fields from the class files. Consequently if you are specifying the number of instances through the MBOOSTER_MAX_INSTANCES field, it is nececessary to instruct the obfuscator to preserve that field.

If you are using Proguard, the configuration file should look like this:

Proguard configuration file fragment
...
# Tells Proguard to keep any static final int field 
#    named MBOOSTER_MAX_INSTANCES
-keepclassmembers class * {
    static final int MBOOSTER_MAX_INSTANCES;
}
...

— Previous page – Contents – Next page —