Configuration reference

Externalizer4J is very easy to configure. These pages give a comprehensive overview of the different options related to:

  • basic configuration
  • exclusions and inclusions
  • advanced performance optimization features
  • debugging options

Configuration: minimal by design

Getting started with Externalizer4J is easy it only requires one configuration file called externalizer4j.properties . This file is used by all the Externalizer4J tools: the ant task, the maven plugin or the IntelliJ IDEA plugin.

How easy is it to get started

Externalizer4J is designed to get started very quickly. Following the convention over configuration approach it comes with useful defaults values for all its options. As a result one can get started in less than 2 minutes.

Required configuration

#
# Accept the EULA by setting to true to activate
#
# default: false
#
acceptEULA=true

Externalizer4J requires only one option! The acceptEULA option should be set to true to enable optimization by Externalizer4J. If this value is not set to true a short message will be displayed. No optimization will happen as long as this is not set.

Getting more information

#
# Provide information during optimization
#
# default: true
#
explain=true

To get an insight in the optimizations applied by Externalizer4J one can set explain to true. Externalizer4J displays short and clear information for each class that gets optimized.

 

#
# Provide more detailed information about decision made during the optimization. Set to true to
# get some insight why a class does not get optimized for instance
#
# default: false
#
explainDetails=false

Sometimes Externalizer4J will appear not to optimize a certain class. With the explainDetails option Externalizer4J displays more details about its analysis and optimization process. Externalizer4J will explain why a given class will not be optimized.

Externalizer4J will only optimize a class when it is 100% safe to do so. Reasons why a class C  will not optimized by Externalizer4J:

  • Missing information
    • about the parent of class C
    • about an interface implemented by class C
  • Exclusions — see Exclude and include for optimization
    • class C has been excluded from optimization
    • The parent of class C has been excluded from optimization
    • a conflict in inclusions and exclusion (exclusions have precedence)
  • A subclass of class C can not be optimized

 

Exclude and include for optimization

By default Externalizer4J optimizes all the classes of a build. At times one may not want to optimize certain classes. Existing client may rely on the existing API for instance. Excludes and includes are used to narrow down the set of classes that get optimized.

#
# Comma separated list of regular expression that defines classes and/or packages that should NOT be optimized.
# Classes which do not match the excludes are candidates for optimization.
#
# IMPORTANT note: excludes have precedence over includes
#
# The regex format uses the period ('.') to denote the package separator and the wildcard ('*') to denote any character.
# The transformation to the java.util.regex.Pattern is :
# String regex = ourRegex.replace(".", "/").replace("*", ".*");
#
# default: none
#
excludes=my.company.p1.*,demo.serialization.reference.*

A comma separated list of regular expression that define which classes should not be optimized. The regular expression use the ‘.’ (dot) as package separator. The ‘*’ (asterisk) for wildcards. In the example above classes is in both the my.company.p1 and demo.serializatio.reference package will get excluded. Note that packages will get excluded too since they match the regular expression.

To exclude a specific class specify the fully qualified package class name. For example: my.company.SpecialClass

#
# Comma separated list of regular expressions that defines classes and/or packages that can be optimized.
# Classes which do not match the includes are not optimized.
#
# The regex format uses the period ('.') to denote the package separator and the wildcard ('*') to denote any character.
# The transformation to the java.util.regex.Pattern is :
# String regex = ourRegex.replace(".", "/").replace("*", ".*");
#
# default: none
#
#includes=my.company.p1.special.*,my.company.p1.other.*,my.company.Data*
includes=

A comma-separated list of regular expression that define which classes should be considered for optimization. The regular expression use the ‘.’ (dot) as package separator. The ‘*’ (asterisk) for wildcards. In the example above classes is in both the my.company.p1.special.* and my.company.p1.other.* package as well as the classes in the my.company package whose name starts with Data will considered during optimization. Note that subpackages will get included as well.

 

Include/exclude logic

The exclusion-inclusion logic can be found below.

    if (inclusions is not empty)
    {
        boolean included = false;
                
        foreach (pattern in inclusions)
        {
            if (pattern matches classname)
            {
                included = true;
                break;
            }
        }
                
        if (not included) return classname_is_excluded;
    }

    if (exclusions is not empty)
    {
        foreach (pattern in exclusions)
        {
            if (pattern matches classname) return classname_is_excluded;
        }
    }

    return classname_is_included;