Project File Reference

This section documents the configuration file for PreEmptive Protection™ DashO™ for Android & Java projects. It contains detailed descriptions of each option, making it useful as a reference, even if you are using the user interface to generate a file for you.

PreEmptive Protection™ DashO for Android & Java project files may have any name or extension, but the preferred extension is .dox. Project files contain information about how a given application is to be obfuscated. The project file is an XML document conforming to dasho.xsd distributed with DashO.

Note:
In most cases, leading and trailing whitespace found in elements or attributes will be trimmed.

<dasho>

The <dasho> element is the outermost element of the .dox file.

Version Attribute

The file version is a required attribute. It specifies the earliest version of DashO that is capable of reading the project file. For example, you should be able to use a version="8.5" project with version 9.2 of DashO without having to edit the project.

<dasho version="8.5.0">

Note:
DashO may create project files with versions different from the application version. The file version represents the minimum version of DashO that is able to use the project file.

Mode Attribute

Mode is an optional attribute. It specifies how DashO should process the configuration. The mode attribute will either be missing (for Standard Mode) or set to android (for Android Mode.

<dasho mode="android" version="10.0.0">

<propertylist> Element

The optional <propertylist> element allows for the definition and assignment of variables called properties. These may be used in the project file or to define the values of other properties.

<propertylist>
    <property name="projectname" value="myproject"/>
    <property name="projectdir" value="c:\myprojects"/>
</propertylist>

There is a built-in external property called dasho.basedir, which reflects the directory in which the project file resides. For a new project that has not been saved, dasho.basedir is not applicable.

Properties are useful for creating project files that act as templates for multiple projects, for different versions of the same project, and for simple portability across different build environments.

Property References

A property is referenced with the following syntax:

${property_name}

Property references are case sensitive, therefore, ${MyProjectDir} references a different property than does ${myprojectdir}. If you reference a property that has not been defined, its literal value is used. Properties may be defined in the terms of other properties. The value of a property may be specified using one or more property references including to references to environment variables. These property references can include default values, indirection, or substitution syntax. Recursive variable definition is not allowed.

DashO provides many flexible ways to reference properties:

Note:
You can use ${prop:-} to substitute an empty string when prop is undefined or blank.

Dynamic Properties

In some places of the project file you can use dynamic properties whose values contain information about the class or method that is being processed:

• ${CLASS_NAME} - the full name of the current class, including its package name.

• ${CLASS_SIMPLENAME} - the simple name of the class, i.e. the class name without its package name.

• ${CLASS_PACKAGE} - the package name of the class, including a trailing period. This will be an empty string for classes in the default package: use ${CLASS_PACKAGE:-} to ensure that the property will be expanded.

• ${METHOD_NAME} - the name of the current method. For constructors this is the same as ${CLASS_SIMPLENAME}.

• ${PROP_NAME} - if the method is a setter or getter the name of the related property. For constructors this is the same as ${CLASS_SIMPLENAME}.

The following properties values are dependent upon the location and name of the project file:

• ${dasho.file} – the absolute path of the project file.

• ${dasho.basedir} – the absolute path to the directory of the project file.

• ${dasho.project} – the name of the project file; no path or extension.

If you have enabled useJDKHome, have a valid JDKHome value, and have enabled setJDKHomeProperties, then the following properties will evaluate to the specified JDKHome value:

• ${JDK_HOME}

• ${JAVA_HOME}

The following property depends on either the specified JDKHome value if it exists and is valid, or the environment in which DashO is running:

• ${javaws.jar} – the absolute path of the Java Web Start jar. Deprecated

Timestamp property

DashO provides the tstamp property to allow the insertion of information about the current date and/or time. The tstamp property can be used in two different ways:

• ${tstamp} - insert the date information using the default format for the locale.

• ${tstamp[pattern]} - inserts the date information using a format specification. The pattern is the same as used by Java's SimpleDateFormat class.

Property Precedence

You can reference properties defined in your project file, values from Java's system properties, or from the environment. To resolve the value for the property DashO consults the sources in the following order:

• DashO dynamic properties

• Java system properties

• Environment properties

• Project file properties

You can override properties defined in the project file by using Java's command line -D option, DashO's command line --properties <filename> option, and via the Gradle and Ant integrations.

Note:
Properties set via the --properties argument override java system properties set with the -D option.

Properties may be used with the following elements:

• <classpath>'s JDKHome attribute

• <entrypoints>/<applet>'s name attribute

• <entrypoints>/<ejb>'s name attribute

• <entrypoints>/<iappli>'s name attribute

• <entrypoints>/<library>/<jar>'s and <entrypoints>/<library>/<dir>'s path attribute

• <entrypoints>/<midlet>'s name attribute

• <entrypoints>/<android>'s name attribute

• <entrypoints>/<publics>'s name attribute

• <entrypoints>/<servlet>'s name attribute

• <entrypoints>/<unconditional>'s name attribute

• <global>/<exclude>'s classname attribute

• <includenonclassfiles>/<copy>'s source and relativedest attributes

• <inputpath>/<pathelement>'s and <classpath>/<pathelement>'s location attribute

• <mapping>/<mapinput>'s suffix attribute

• <mapping>/<mapinput>'s path attribute

• <mapping>/<mapoutput>'s path and proguardMap attributes

• <mapping>/<mapreport>'s path attribute

• <output>/<dir>'s path attribute

• <output>/<jar>'s path and manifest attributes

• <output>/<constpooltag>'s value

• <output>/<sourcefile>'s value

• <premark>/<passphrase>'s value

• <premark>/<watermark>'s value

• <preverifier>'s value

• <rename>/<class-options>'s prefix attribute

• <rename>/<class-options>'s alphabet attribute

• <rename>/<member-options>'s alphabet attribute

• <report>'s path attribute

• <shelflife>'s period, warningperiod, date, and warningdate attributes

• <shelflife>/<property>'s name and value attributes

• <tamperCheck>'s action attribute

• <tamperCheck>/<signerInfo>'s alias, keystore, storepass, and storetype attributes

• <tamperResponse>'s source attribute

• <debugEnabledCheck>'s action attribute

• <debugEnabledResponse>'s source attribute

• <debuggingCheck>'s action attribute

• <debuggingResponse>'s source attribute

• <shelfLifeCheck>'s action, expirationDate, warningDate, startDateSource, expirationPeriod, warningPeriod, and tokenSource attributes.

• <signJar>'s value and its keystore, storetype, storepass, alias, keypass, sigfile, and addArgs attributes

<global> Element

The optional <global> element is for defining options that apply across the entire run. This element contains the global options and the global excludes.

Note:
Global options are not case sensitive.

Fornamedetection Global Option

The fornamedetection option turns on DashO's built-in ability to search for dynamically included classes. This adds significant processing time to the run. It is best to run your application with this on initially and then add these classes as entry points to your file.

In some cases, it is not possible for DashO to determine which classes are dynamically loaded. A program could request the name of the class to be loaded as user-input or to be specified in an external file. However, most inclusions are not that vague and DashO can safely determine what they are. The report file reports a confidence level associated with a given class inclusion discovery. A HIGH confidence level is almost assuredly correct. In other words, DashO detected something such as:

Class a = Class.forName("java.awt.Rectangle");

A POSSIBLE confidence level is an educated guess. DashO has detected code similar to:

String s = getUnknownString();
Class a = Class.forName(s);
Rectangle r = (Rectangle)a.newInstance();

In this case, DashO cannot detect which exact class is loaded. However, it does "know" that the loaded class will be cast to a Rectangle. Therefore, DashO finds all subclasses of Rectangle and includes them with a possible confidence level.

Using the fornamedetection option and running in force mode instructs DashO to automatically include what it finds. Only do this if you are confident in DashO's determination.

Running in force mode does not stop even if it cannot determine dynamically loaded classes for any given forName() call.

<global>
    <option>fornamedetection</option>
</global>

Ignorenotfoundclasses Global Option

The ignorenotfoundclasses option allows DashO to process an application even if it encounters references to classes that are not present in the classpath. DashO cannot ignore all missing classes: if it cannot find a super class or super interface it cannot continue.

This option should only be used as a means to allow DashO to finish so that information from the run can be gathered. Without access to all classes, DashO cannot safely determine all needed dependencies.

Note:
This option is always on in Android Mode.

<global>
    <option>ignorenotfoundclasses</option>
</global>

Ignorebrokencalls Global Option

The ignorebrokencalls option allows DashO to process an application even if it encounters references to methods in classes that it cannot find. This can be caused by errors in your classpath or by jars that are out of date. Although DashO will be able to process the classes, you will want to check the classpath and jars to make sure they contain the classes you expect.

Note:
This option is always on in Android Mode.

<global>
    <option>ignorebrokencalls</option>
</global>

Force Global Option

When DashO detects the use of reflection in classes, it makes note of the location and target of the reflective code and continues its analysis. At the end of the analysis, it prints a reflection report and halts the build process. Once you have dealt with all of the reflection issues in your project, the force option can be added to let DashO complete the build. The force option can be specified in the project file or passed to DashO via the command line --force option. We recommend you the set the value in the .dox file as it allows the obfuscation to be performed via the UI and build system integrations; --force only works with the DashO command line.

Notes:
You may need to disable checks when running without this option because some injected code uses reflection.

This option is always on in Android Mode.

<global>
    <option>force</option>
</global>

Makepublic and Nomakepublic Global Options

The makepublic and nomakepublic options control when DashO makes classes and members public.

Note:
makepublic and nomakepublic are ignored in Android Mode.

<global>
    <option>nomakepublic</option>
</global>

Renameforname Global Option

The renameforname option allows dynamically loaded classes to be renamed. In the case where DashO cannot unambiguously determine the string used to load a class, that class should be listed in the <entrypoints> element. These ambiguous cases correspond to what the fornamedetection option would report as a possible confidence level.

Notes:
Using assertions in your code with Java's assert keyword makes a class self-reflective. DashO will make that class non-renameable unless you use the renameforname option.

This option is ignored in Android Mode.

<global>
    <option>renameforname</option>
</global>

Nooverloadinduction Global Option

The nooverloadinduction option disables Overload Induction™ in favor of simple renaming. I.e., DashO will not create additional overloads during renaming.

Global <exclude>

The exclude option allows you to specify classes or methods that appear as part of the input classes but should not be included in the final output of DashO. The classes matching the regular expression of a global exclude will not be processed or included in the final output.

For example, you could exclude tests or samples present in third party jars:

<global>
    <exclude classname="com\.thirdparty\.tests\..*"/>
    <exclude classname="com\.thirdparty\.sample\..*"/>
</global>

Notes:
The names of excluded classes are always specified as regular expressions.

This option is ignored in Android Mode.

Bypassdasho Global Option

The bypassdasho option configures DashO to not process the inputs. The input jars and directories will be directly copied to the output. This option can only be used when merge attribute (on output) is set to false or when outputting an APK.

<global>
    <option>bypassdasho</option>
</global>

<inputpath> Element

The <inputpath> element contains the location of the classes that DashO will process. DashO can handle directories, zip files, and jar files. The location can also contain multiple entries when separated by the OS-specific classpath separator.

Note:
This element is ignored when running with the --pathMap argument.

<inputpath>
    <pathelement location="c:\test\app.jar"/>
    <pathelement location="c:\test\classes"/>
    <pathelement location="c:\test\one.jar;c:\test\two.jar"/>
</inputpath>

Note:
c:\test\classes is not to be any part of a package designation. It is to be the root directory of the packages.

<globalProcessingExclude> Element

The <globalProcessingExclude> element contains the location of classes which should be excluded in all processing. This has the same effect as including them in the <excludelist> elements of the individual areas such as Control Flow and Renaming.

<globalProcessingExclude>
    <classes name="org.package.excludeMe.**"/>
    <classes name="com.example.ExcludeMe"/>
</globalProcessingExclude>

<classpath> Element

The <classpath> element contains the location of classes that DashO may need in analyzing the input classes. These classes are typically third-party packages or jars that are part of the Java Runtime Environment. DashO can handle directories, zip files, Java modules, and jar files in the classpath. The location can also contain multiple entries when separated by the OS-specific classpath separator.

Note:
This element is ignored in Android Mode.

<classpath>
    <pathelement location="c:\test\app.jar"/>
    <pathelement location="c:\test\classes"/>
    <pathelement location="c:\test\one.jar;c:\test\specialModule.jmod"/>
</classpath>

When providing a directory (e.g. c:\test\classes), it should either be:

• A directory containing Java modules (e.g. myFirstModule.jmod, anotherModule.jmod)
• The root directory for .class files with folders representing the package hierarchy (e.g. com\example\MyClass.class, com\example\util\MyUtilities.class).

Note:
If the directory contains any .jmod files DashO will not look for any .class files.

JDKHome, useJDKHome, and setJDKHomeProperties attributes

Setting useJDKHome tells DashO to use the runtime classes from that JDK when evaluating dependencies. The JDKHome attribute allows you to specify the location of the JDK used for this project. Setting setJDKHomeProperties tells DashO to use the specified value for JDKHome as a value for the properties JDK_HOME and JAVA_HOME.

<classpath useJDKHome="true" JDKHome="c:\Program Files\Java\jdk-9.0.4" setJDKHomeProperties="true">
    <pathelement location="c:\test\classes"/>
    …
</classpath>

Notes:

Projects that use the Android API or J2ME should not use this option. These projects require the runtime jar for these particular environments: e.g. Android.jar or midpapi10.jar.

<entrypoints> Element

Entry points are starting points for the dependency analysis that DashO performs in order to determine which classes, methods, and fields are used by your application. In other words, these are the entry points for your application.

Note:
This element is ignored in Android Mode.

<classes>, <method>, and <field> Entry Points

You can use <classes>, <method> and <field> elements to specify classes, methods, and fields as entry points into your application.

<entrypoints>
    <classes name="test.AClass"/>
    <classes name="test.MyApplication">
        <method name="main" signature="java.lang.String[]"/>
        <field name="value"/>
    </classes>
</entrypoints>

If you specify a class without any methods or fields, only the class itself and methods that override other retained methods will be considered entry points.

When specifying a signature for methods use fully qualified class names: as in the above example, use java.lang.String[] rather than String[]. Multiple parameters should be separated by commas without spaces. You can also specify constructors as entry points using the special <init> notation as the method name. Remember to use < and > since the project file is in XML.

Names of classes, members and method signatures can be specified as literals, patterns, or regular expressions. See Names: Literals, Patterns, and Regular Expressions for details.

Rename Attribute

The rename attribute controls whether or not a class or member specified in a <classes>, <method>, or <field> element can be renamed.

<entrypoints>
    <classes name="test.OtherApplication" rename="true">
        <method name="main" signature="java.lang.String[]"/>
    </classes>
</entrypoints>

In this example, the class test.OtherApplication can be freely renamed, but the main method that DashO is to treat as an entry point cannot be renamed.

<library> Entry Point

You can use the <library> element to specify a Library Entry Point.

<entrypoints>
    <library public="off">
        <dir path="myAPIDirectory"/>
    </library>
</entrypoints>

Note:
If you add a directory or jar as a library it does not need to be added to the <classpath>. DashO does this automatically.

<entrypoints>
    <library public="off">
        <jar path="myAPI.jar"/>
    </library>
</entrypoints>

The public attribute of the <library> element controls whether only public members should be treated as Entry Points (public="on"), or whether protected members should also be treated as Entry Points (public="off"). If omitted, on is assumed.

The <library> element can contain either a <jar> element, specifying a JAR, or a <dir> element, specifying a directory containing classes. The path attribute contains one or more paths, separated by the OS-specific path separator (; for Windows, : for macOS and Linux).

Special Class Entry Points

The following elements allow you to specify Special Class Entry Points:

See Special Class Entry Points for more details on these entry points.

These elements support the following attributes:

• name - A literal, pattern, or regular expression describing the name(s) of the classes to be treated as entry points. See Names: Literals, Patterns, and Regular Expressions.
• rename-class - If true, the classes to be treated as entry points can be renamed; defaults to false except for <springbean>.

Additionally, many of these elements support this attribute (see table above):

• rename-members - If true, the members of the specified classes can be renamed; defaults to false, except for <springbean> and <android>.

<entrypoints>
    <android name="com.example.myApp.MyActivity"/>
    <android name="com.example.myApp.MyIntActivity" rename-class="true"/>
</entrypoints>

<springbean>

There are additional attributes supported on a <springbean> which do not exist on other special classes:

• entrypoints – A comma separated list of the method names used in the bean definition in attributes like:

  • init-method – The method called by the Spring framework after creating the bean.

  • destroy-method – The method called by the Spring framework before destroying the bean.

  • factory-method – The method called by the Spring framework to instantiate the bean.

• renamePropertyMethods – True/False (false by default): rename the property methods: get*(), set*(*), and is*() (and the fields represented by those methods).

• renameEntryPoints – True/False (false by default): rename the entry point methods listed under the entrypoints.

<entrypoints>
    <springbean name="com.example.spring.beans.MyBean"
        entrypoints="initBean,destroyBean,createBeanOne,createBeanTwo"
        rename-class="false" renamePropertyMethods="true" renameEntryPoints="true"/>
</entrypoints>

<report> Element

If a report file is specified, DashO creates a report indicating all methods and fields removed. It also summarizes the total numbers for the entire project including total method, field, and constant pool entry removals.

Note:
This element is ignored in Android Mode.

<report path="c:\output\dasho-report.txt"/>

Warnings and errors go to the console.

A snippet from a report looks like:

Removal Option : Remove all unused

Dependency Report for Entry Points:
GifWiz.Editor.main(java.lang.String[])
------------------------------------------------------------------------

gifwiz.ConsoleMessage
========================================================================
Removable Method display()
Removable Method outline(int)
Removable Field n
Removable Field z1

gifWiz.Arc
========================================================================
Removable Method round(double)
Removable Method update_scp()
Removable Method update_scp(int)
Removable Method corners()
Removable Field ccw
Removable Field cw
Removable Field dalpha21
Removable Field dalpha10

Each Removable method was determined by DashO to be unneeded during the execution of the program.

DashO also outputs summary results for the run:

Statistics In Out Change
========================================================================
Classes 612 596 -2.6%
Methods 8975 7095 -20.9%
Fields 4953 2792 -43.6%
Constants 103306 90756 -21.9%

Processing Time: 4:46.977 min

This DashO run was able to remove almost 21% of all methods. However, this does not mean the application size was reduced by 21%. The percentage of methods removed may be only 1% of the application size.

<output> Element

The <output> element indicates whether you want DashO to write the output to a directory, a jar file, or an APK file. The format of the output is dependent upon your renaming options. It also controls whether the results are merged into a single output or retain the same packaging as the input. If you specify no renaming, then the directory/package structure that currently exists will be recreated in the specified directory so be sure your destination is not the same as your source! If you rename, notions of packages can be removed and all classes will be put in the directory specified.

Note:
This element is ignored when running with the --pathMap argument.

<output merge="true">
    <dir path="c:\output\"/>
</output>

Optionally you can specify a manifest with the jar output. DashO will copy the manifest file to the output jar. If you specify a jar file for the manifest, it will be used as the source of the manifest.

<output merge="true">
    <jar path="c:\output\protected.jar" manifest="c:\misc\Manifest.mf"/>
</output>

If outputting to an APK you must have an APK file as input. You can specify if you want the APK aligned. It should only be set to true if the APK is also being signed.

<output zipAlign="true">
    <apk path="c:\output\myApp.apk"/>
</output>

Note:
Both path and manifest attributes support properties.

Jar Attributes

When DashO creates one or more jars, either by using the <jar> element or when merge=false, you can specify attributes that customize the jar creation:

<output merge="false" compress="true" level="4" filesonly="false" includenonclassjars="true">
    <dir path="c:\output\"/>
</output>

This sample would produce jars with a moderate level of compression that contained entries for both the files and their directory structure.

APK Attributes

When DashO creates an APK using the <apk> element, you can specify if it should be aligned and which version of AAPT should be used:

<output aaptVersion="AAPT2" zipAlign="true">
    <apk path="c:\output\myApp.apk"/>
</output>

Merge Attribute

DashO can combine the obfuscated results into a single directory or jar or keep the original packaging of the input classes. This behavior is controlled using the <output> element's merge attribute. The value for the merge attribute is either true or false. If the merge attribute is not provided it defaults to true.

merge="true"

This is the default mode for DashO. When merge="true" either a <dir path="…"/> or <jar path="…"/> may be used for output. DashO will combine all obfuscated classes into the indicated jar or output directory.

merge="false"

When merge="false" is specified, only a <dir path="…"/> may be used for output. DashO will preserve the original packaging of the input classes in the output directory. Classes that came from jars will be placed in identically named jars in the output directory. In addition, the manifest and non-class files from the jars will be copied to the obfuscated jars. Classes that came from directories will be placed in subdirectories in the output directory. Non-class files that appear in input directories are never copied. DashO will try to preserve relative paths between jars and directories that come from a common root location. This setting only applies to <dir> and <jar> outputs.

Note:
The merge="false" option requires a <dir path="…"/> element be used for output. If a <jar path="…"/> or <apk path="…"/> element is provided then the merge="false" setting is ignored.

Autocopy Attribute

When merge="true" is specified (or the output type is <jar>) you can also specify the autocopy attribute. When autocopy="true" is specified, non-class files in input jars and directories are automatically copied to the output. When autocopy="false" is specified, non-class files in input jars and directories are not copied to the output. This setting only applies to <dir> and <jar> outputs.

<output merge="true" autocopy="true">
    <dir path="obfuscated"/>
</output>

<constpooltag>

You can covertly add constant pool entries for your class files to mark them. This string will be placed in every class DashO outputs and will not be printed or evident to the casual user. Only those using a class disassembly tool will be able to view this string. The value attribute can contain property references including dynamic class properties.

<output>
    <constpooltag value="Copyright 1984 Yoyodyne Engineering, Inc."/>
</output>

Note:
The value is referenced as a custom class attribute so it cannot be a reserved attribute name.

<sourcefile>

This element allows you to set the value of Java's SourceFile attribute that is used in stack traces. The value attribute can contain property references including dynamic class properties.

<output>
    <sourcefile value="${CLASS_SIMPLENAME}-v${ver}"/>
</output>

<removal> Element

The <removal> element allows you to configure Removal.

Note:
This element is ignored in Android Mode.

The classes and members attributes of the <removal> element allow you to specify which classes and members (fields/methods) can be removed. The options for these are:

• none - no removal

• unused-non-public - only remove unused items that are not public

• unused - remove all unused items

If both attributes are omitted or you do not specify <removal>, classes and member removal will not occur.

Removal supports an <excludelist> element that contains rules that select classes, methods, and fields that will not be removed. This element is explained in the section on <includelist> and <excludelist> Rules.

<removal classes="unused-non-public" members="unused"/>

<debug> Element

The <debug> element instructs DashO to remove debug information attributes from processed classes, and specifies which attributes to remove. The types attribute is used to specify the types of information to be removed. See this section for information about the types of debug information that can be removed, and the attribute names that you can specify in this type attribute. Multiple items are separated by spaces.

Two special keywords are also supported:

• All – All the debug information will be removed.

• None – None of the debug information will be removed.

If the <debug> element is not present then all debugging information is retained. If it is present but the type attribute is not present then all debugging information is removed.

<debug/>

<debug types="None" />

<debug types="SourceDir SourceDebugExtension" />

<attributes> Element

The <attributes> element instructs DashO to remove attributes from processed classes, other than those specified in the <debug> element. The types attribute of the element is used to specify the type of attributes to be removed. See this section for information about the types of attributes that can be removed. Multiple items are separated by spaces.

Two special keywords are also supported:

• All – All the attributes will be removed.

• None – None of the attributes will be removed.

If the <attributes> element is not present then all attributes are retained. If it is present but the types attribute is not present then the following attributes are removed: Deprecated, Synthetic, RuntimeInvisibleAnnotations, and RuntimeInvisibleParameterAnnotations.

<attributes/>

<attributes types="All" />

<attributes types="Deprecated Synthetic" />

Note:
Type Annotation attributes will always be removed. This is hard coded and cannot be configured.

<methodCallRemoval> Element

The <methodCallRemoval> element allows you to configure Method Call Removal.

There are no attributes for the <methodCallRemoval> element. All configuration is contained in the <method> sub elements.

Note:
This element is ignored in Android Mode.

<method> Elements

These elements define the method calls to remove.

The attributes of this element identify the method by class name, method name and signature. Thus for overloaded methods, one entry must be made for each.

• className – This string attribute specifies the fully qualified name of the class containing the method.

• methodName – This string attribute specifies the name of the method. Cannot be a constructor or static initializer method.

• signature – This string attribute specifies the parameter list of the method. Use the types of the parameters, separated by commas. Use fully qualified names for non-primitive types and simple names for primitive types (int, char, etc.). Use [] to specify array parameters. These types are case sensitive.

<renaming> Element

The <renaming> element allows you to configure Renaming.

Note:
This element is ignored in Android Mode.

This element allows for the global control of renaming using the option attribute the renaming of annotations. Valid values are on and off.

<renaming option="on" renameAnnotations="on"/>

<class-options> Element

The attributes of the <class-options> element control the renaming of classes.

• rename – This boolean option turns the renaming of classes on or off. When false the classes will retain their original names.

• keeppackages – If true, DashO will maintain the package hierarchy; otherwise, DashO will flatten the package hierarchy. Defaults to false. See this section for more details.

• alphabet – a string that defines the alphabet used to create new class names. If omitted, the default alphabet is used.

• minlength – the minimum length of new class names.

• randomize – If true, DashO will use randomized renaming for class names; otherwise, DashO will use sequential renaming. Defaults to false.

• prefix – Specifies a Class Prefix.

<member-options> Element

The <member-options> element controls the renaming of methods and fields.

• keeppublics – When set to true all public methods and fields will retain their original names. Usage of the library option in the <entrypoints> element treats all public methods as entry points inherently retaining their original names. Specifying this option would be redundant.

• alphabet – a string that defines the alphabet used to create new member names. The use is the same as for the alphabet attribute of the <class-options> element.

• minlength – the minimum length of new member names.

• randomize – If true, DashO will use randomized renaming for member names; otherwise, DashO will use sequential renaming. Defaults to false.

<renaming> Exclude List

The <renaming> element supports an <excludelist> element that contains rules that select classes, methods, and fields that will not be renamed. This element is explained in the section on <includelist> and <excludelist> Rules.

<renaming option="on">
    <excludelist>
        <classes name="samples.SimpleApp" excludeclass="true"/>
    </excludelist>
</renaming>

Note:
These rules are applied in addition to renaming restrictions defined by entry points.

<mapreport> Element

The <mapreport> element allows you to configure a location for DashO to output a Renaming Report.

<renaming option="on">
    <mapping>
        <mapreport path="c:\workproject-mapreport.txt"/>
        </mapping>
</renaming>

Note:
The path attributes support properties.

<mapoutput> Element

The <mapoutput> element allows you to configure a location for DashO to output the Renaming Map File.

The optional attribute proguardMap stores a location to output a ProGuard-compatible map file.

The attribute overwrite="true" instructs DashO to allow overwriting an existing map file.

Note:
The overwrite attribute is optional and if omitted, it defaults to false.

<renaming option="on">
    <mapping>
        <mapoutput path="c:\work\project.map"
            proguardMap="c:\work\mapping.txt" overwrite="true"/>
    </mapping>
</renaming>

<mapinput> Element

The <mapinput> element allows you to specify an Input Renaming Map File for Incremental Obfuscation.

<renaming option="on">
    <mapping>
        <mapinput path="c:\work\project.map"/>
    </mapping>
</renaming>

Suffix Attribute

The mapinput has an optional suffix option that can be used to immediately track changes across incremental obfuscations (i.e., the suffix could be the date or some other identifying string).

<renaming option="on">
    <mapping>
        <mapinput suffix="new">
            <file path="c:\work\project.map"/>
        </mapinput>
    </mapping>
</renaming>

<optimization> Element

The <optimization> element allows you to configure DashO's Optimization. When the option attribute is set to off, DashO skips Optimization altogether, regardless of what is within the element.

Note:
This element is ignored in Android Mode.

<optimization option="on"/>

To fine tune where Optimization takes place, the <optimization> element can contain both a <includelist> and <excludelist> which contain rules that select classes and methods. These are explained in the section on <includelist> and <excludelist> Rules.

<optimization option="on">
    <includelist>
        <classes name="samples.**"/>
    </includelist>
    <excludelist>
        <classes name="samples.SimpleApp"/>
    </excludelist>
</optimization>

<controlflow> Element

The <controlflow> element allows you to configure Control Flow Obfuscation. The element supports an option attribute; when option is set to off, DashO will skip Control Flow Obfuscation altogether, regardless of what is contained within the element. The option attribute defaults to on.

The <controlflow> element supports the following attributes:

<controlflow option="on" tryCatch="on" catchHandlers="1" blockSplitting="on" blockSplittingBlockSize="3" jumbling="on" />

To fine tune where Control Flow obfuscation is performed, the <controlflow> element can contain both an <includelist> and <excludelist> which contain rules that select classes and methods. These are explained in the section on <includelist> and <excludelist> Rules.

<controlflow option="on">
    <excludelist>
        <classes name="SimpleApp"/>
    </excludelist>
</controlflow>

<stringencrypt> Element

The <stringencrypt> element allows you to configure String Encryption, and supports the following attributes:

<stringencrypt option="on" level="3" implementations="4"/>

The <stringencrypt> element can contain both an <includelist> and <excludelist> which contain rules that select classes and methods to be included or excluded from String Encryption. These are explained in the section on <includelist> and <excludelist> Rules.

<stringencrypt option="on">
    <includelist>
        <classes name="com.yoyodyne.**"/>
    </includelist>
    <excludelist>
        <classes name="com.yoyodyne.ui.**"/>
    </excludelist>
</stringencrypt>

<decrypter> Element

The <decrypter> element lets you control which classes can be chosen as Decrypter Classes. This element is similar to the <classes> element used in <includelist> and <excludelist> Rules.

The <decrypter> element has four attributes that select the outer classes:

If the <decrypter> element is omitted then DashO will determine the locations automatically.

<decrypter modifiers="static class" name="com.yoyodyne.**"/>

<seInput> Element

The <seInput> element specifies a String Encryption Input Map File.

<seInput path="c:\example_project\prev_project-se.map" />

Note:
This element is ignored in Android Mode.

<seOutput> Element

The <seOutput> element specifies a String Encryption Output Map File. If this file exists, it will be overwritten.

<seOutput path="c:\example_project\project-se.map" />

Note:
This element is ignored in Android Mode.

<customEncryption> Element

The <customEncryption> element allows you to configure Custom Encryption. It supports the following attributes:

It must also contain an <includelist> which contains rules that the select classes and methods on which to use the custom encryption. These are explained in the section on <includelist> and <excludelist> Rules. Please note this <includelist> should be a subset of the overall classes/methods selected for String Encryption.

<customEncryption useCustomEncryption="true" encryptionJar="custEncryption.jar"
        encryptionClass="com.example.myCustomEncryption.Encrypt" encryptionMethod="myEncrypter" decryptionClass="com.example.myProject.Decrypt" decryptionMethod="myDecrypter" >
    <includelist>
        <classes name="com.example.mySpecialClasses.**"/>
    </includelist>
</customEncryption>

<make-synthetic> Element

The <make-synthetic> element controls the Make Synthetic obfuscation option. The element contains a single attribute, value, which has four possible settings:

• none
• private
• non-public
• all - This is the default if the value attribute is omitted.

See Make Synthetic for additional information about these options.

Make Synthetic supports an <excludelist> element that contains rules that select classes, methods, and fields which will not be marked synthetic. This element is explained in the section on <includelist> and <excludelist> Rules.

Note:
This option is always none in Android Mode.

<make-synthetic value="non-public"/>

<premark> Element

The <premark> element allows you to configure PreMark™. It supports an option attribute which enables (option="on") or disables (option="off") PreMark. It also supports a truncate attribute that controls overflow behavior - if truncate="on", then DashO will truncate watermarks if they are too long to embed into a Jar and warn accordingly. Otherwise, DashO will issue an error if a watermark is too long to apply.

Note:
This element is ignored in Android Mode.

<premark option="on"/>

<encoding>

The <encoding> element allows you to specify a Character Map for your watermark.

<premark option="on">
    <encoding name="7bit-a"/>
</premark>

<watermark>

The <watermark> element sets the watermark to be embedded in the output jar.

<premark option="on">
    <watermark>Copyright Yoyodyne Engineering, Inc.</watermark>
</premark>

<passphrase>

The <passphrase> element sets a passphrase required to read your watermark.

<premark option="on">
    <passphrase>secret</passphrase>
</premark>

<includenonclassfiles> Element

DashO can copy related non-class files into its destination directory to jar as part of the run. For example, assume your application is embedded within a jar file that contains gif files scattered throughout the directory hierarchy in the jar. In addition to putting obfuscated class files into the destination, it can also copy the gifs to any other non-class files into the destination you specified.

It is also possible with non-class file includes to specify a relative path from the root of the destination directory or root of the jar to which the non-class files are copied. This relative path is optional. If a relative path is not specified, individual non-class files are copied to the root of the destination directory or jar.

Note:
XML configuration files found when processing the non-class files may be updated allowing class and method names to be changed.

In the following example DashO copies the non-class file to the root of the destination directory or jar.

<includenonclassfiles>
    <copy source="c:\gifs\important.gif"/>
</includenonclassfiles>

In the following example DashO will copy the .gif files in the directory c:\gifs to the root of the destination directory or jar. Other directories in the source will not be searched for the .gif files.

<includenonclassfiles>
    <copy source="c:\gifs\*.gif"/>
</includenonclassfiles>

In the following example the non-class file will be copied to the directory c:\test\dashoed\gifs. A sub directory gifs will be created in the output directory c:\test\dashoed.

<output>
    <dir path="c:\test\dashoed"/>
</output>

<includenonclassfiles>
    <copy source="c:\gifs\important.gif" relativedest="/gifs"/>
</includenonclassfiles>

If a directory is specified as the source, all non-class files, found through a recursive decent, are copied to the destination while preserving the hierarchy.

<includenonclassfiles>
    <copy source="c:\nonclassfiles\"/>
</includenonclassfiles>

If a jar or zip file is specified, all non-classes are copied while preserving the internal hierarchy.

<includenonclassfiles>
    <copy source="c:\test\nonclassfiles.jar"/>
</includenonclassfiles>

If a relative path is specified with a jar or zip file, the hierarchy is recreated under the specified relative path.

<includenonclassfiles>
    <copy source="c:\test\nonclassfiles.jar" relativedest="misc"/>
</includenonclassfiles>

<preverifier> Element

If you are running a J2ME CLDC application, DashO allows you to run the preverifier on the class files after DashO has finished processing the application. If you have set the run attribute to true, you can specify the path to the preverifier program. If you specify only a path, DashO assumes that the program name is preverify.

Note:
This element is ignored in Android Mode.

The <preverifier> element contains the following attributes that pass additional options to the preverifier:

<preverifier run="true" nonative="true" nofp="true">
    ${wtk.home}/bin/preverify.exe
</preverifier>

<signjar> Element

The <signjar> element lets you run the jarsigner or apksigner tool on the jars or APK created by DashO. Additional details on jarsigner can be found at http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/jarsigner.html. Additional details on apksignercan be found at https://developer.android.com/studio/command-line/apksigner.html.

Note:
This option is ignored in Android Mode.

The <signjar> element has the following attributes:

Notes:
If signing APKs using jarsigner, you may need set addArgs to "-sigalg SHA1withRSA -digestalg SHA1". If using apksigner you may want to set it to --v1-signing-enabled [true|false] --v2-signing-enabled [true|false] or --min-sdk-version nn --max-sdk-version nn (where nn is an sdk version) to set the APK signature scheme.

All the non-boolean attributes can reference DashO properties.

<signjar option="on" keystore="../dev/keystore" storepass="${keystore.psw}"
        alias="lazardo">
    ${JDK_HOME}/bin/jarsigner
</signjar>

<injection> Element

The <injection> element is used to configure Check injection has the following attributes:

• option="on/off" – Turns DashO's check injection feature on or off. If not present, the default is on.

• honorAnnotations="true/false" – Determines if injection annotations present in the compiled classes will be acted upon. If true, then DashO will process the injection annotations in the classes. The default value of this attribute is true.

• stripAnnotations="true/false" – Determines if injection annotations present in the compiled class will be retained in the output. If true, DashO will remove the annotations. The default value of this attribute is true.

If the <injection> element is not present then annotations in the compiled classes will be ignored, but retained in the output. If the option attribute is off, then the entire <injection> element is ignored regardless of its contents. The following sample XML shows the allowed attributes with their default values:

<injection option="on"
    honorAnnotations="true"
    stripAnnotations="true" />

Note:
The <injection> element only processes or removes the annotations from the com.preemptive.annotation.instrumentation package. For information on these annotations see the related javadocs.

<runtime> Element

The <injection> element can contain an optional <runtime> element that is used to specify which check implementations will be injected and which Shelf Life implementation jar will be used with the application if Shelf Life checks are injected. If the element is omitted then the default value for its target attribute will be used. The runtime element has the following attribute:

• target="java" – The execution environment for the application. The supported values are: java (Java 1.5 and up) and android (Android SDK 1.6 and up).

<injection>
    <runtime target="java" />
</injection>

<shelflife> Element

The <injection> element can contain optional Shelf Life settings. These define the values that will be used by the ShelfLifeCheck annotation to create an expiration token that is placed in the application. Note that all of the attributes can contain property references that are expanded at the time the injection takes place.

• key="file" – The Shelf Life key file obtained from PreEmptive Solutions.

• date="date" – A fixed expiration date in MM/DD/YYYY format. This is the date at which the application will be considered expired.

• warningDate="date" – A fixed warning date in MM/DD/YYYY format. This is the date on which warnings about expiration will be begin.

• period="days" – An expiration period. This is the number of days from a starting date on which the application will be considered expired. The starting date for a given shelf life check can be configured on an individual shelf life check.

• warningPeriod="days" – A warning period. This is the number of days before the expiration when the expiration warning period starts.

Combinations of fixed dates and periods are allowed. If values for both the fixed date and period are present, the fixed date is used. Annotations that appear in the application code can override or augment these values.

<injection>
    <shelflife key="../yoyodyne.slkey"
        date="10/25/${EXP_YR}"
        warningperiod="90"/>
</injection>

Expiration Token Properties

User defined properties may be added to the expiration token. These properties have the same form as other DashO property elements. The properties may be examined by the application when a user action is specified with the ShelfLifeCheck annotation.

<injection>
    <shelflife key="…" date="10/25/2016">
        <property name="REGION" value="2"/>
        <property name="COUNTRY" value="GB"/>
    </shelflife>
</injection>

Both the name and value attributes may contain property references and are expanded at the time the ShelfLifeCheck is injected.

<checks> Element

The <checks> element describes Checks and Responses to be injected into the code. These Checks and Responses must contain a <locations> element.

Checks

Most of the Checks have the following standard attributes:

• action – The optional action call/set with the Check's status. In most Checks, this will be a boolean type (see Specifying Sources and Actions).

• response The response to take when the Check is triggered.

  • exit – Exit the application with a random, non-zero return code.

  • hang – Cause the current thread to hang.

  • error – Throw a randomly selected subclass of java.lang.Error.

  • exception – Throw a randomly selected unchecked subclass of java.lang.Exception.

  • none – Do nothing (default).

• where – Where should the code be injected?

  • Beginning – The beginning of the method (default).

  • End – The end of the method (all exit points).

  • BeginningAndEnd – Both the beginning and end of the method.

Responses

All the Responses have the following standard attributes:

• source – The source to determine if the Check is triggered. This will be a boolean type (see Specifying Sources and Actions).

• response – The response to take when the source indicates the Check was triggered.

  • exit – Exit the application with a random, non-zero return code.

  • hang – Cause the current thread to hang.

  • error – Throw a randomly selected subclass of java.lang.Error.

  • exception – Throw a randomly selected unchecked subclass of java.lang.Exception.

  • none – Do nothing (default).

• probability – The probability the response (i.e. exit, hang, error or exception) should happen. Expects a decimal from 0.0 to 1.0 (default: 1.0).

• where – Where should the code be injected?

  • Beginning – The beginning of the method (default).

  • End – The end of the method (all exit points).

  • BeginningAndEnd – Both the beginning and end of the method.

<debuggingCheck> Element

A Debugging Check determines if your application is being debugged (see Debug Checks and Responses). The Debugging Check has the standard attributes.

<debuggingCheck action="myBoolean" response="none" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation" signature="int,int"/>
        </classes>
    </locations>
</debuggingCheck>

<debuggingResponse> Element

A Debugging Response allows you to have the application respond to a Debugging Check in an area away from where the Check itself occurred (see Debug Checks and Responses). The Debugging Response has the standard attributes.

<debuggingResponse source="myBoolean" response="error" where="Beginning"
        probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation" signature="double"/>
        </classes>
    </locations>
</debuggingResponse>

<debugEnabledCheck> Element

A Debug Enabled Check determines if your application has debugging enabled (see Debug Checks and Responses). The Debug Enabled Check has the standard attributes.

<debugEnabledCheck action="myBoolean" response="none" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation" signature="int,int"/>
        </classes>
    </locations>
</debugEnabledCheck>

<debugEnabledResponse> Element

A Debug Enabled Response allows you to have the application respond to a Debug Enabled Check in an area away from where the Check itself occurred (see Debug Checks and Responses). The Debug Enabled Response has the standard attributes.

<debugEnabledResponse source="myBoolean" response="error"
        where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation" signature="double"/>
        </classes>
    </locations>
</debugEnabledResponse>

<emulatorCheck> Element

An Emulator Check determines if your application is being run on an emulator (see Emulator Check and Response). The Emulator Check has the standard attributes.

<emulatorCheck action="myBoolean" response="none" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation" signature="int,int"/>
        </classes>
    </locations>
</emulatorCheck>

Note:
Emulator Checks are only supported on Android.

<emulatorResponse> Element

An Emulator Response allows you to have the application respond to an Emulator Check in an area away from where the Check itself occurred (see Emulator Check and Response). The Emulator Response has the standard attributes.

<emulatorResponse source="myBoolean" response="error"
        where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation" signature="double"/>
        </classes>
    </locations>
</emulatorResponse>

Note:
Emulator Responses are only supported on Android.

<hookCheck> Element

A Hook Check determines if your application is being hooked (see Hook Check and Response). The Hook Check has the standard attributes.

<hookCheck action="myBoolean" response="none" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation" signature="int,int"/>
        </classes>
    </locations>
</hookCheck>

Note:
Hook Checks are only supported on Android.

<hookResponse> Element

A Hook Response allows you to have the application respond to a Hook Check in an area away from where the Check itself occurred (see Hook Check and Response). The Hook Response has the standard attributes.

<hookResponse source="myBoolean" response="error"
        where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation" signature="double"/>
        </classes>
    </locations>
</hookResponse>

Note:
Hook Responses are only supported on Android.

<rootCheck> Element

A Root Check determines if your application is running on a rooted device (see Root Check and Response). The Root Check has the standard attributes.

<rootCheck action="myBoolean" response="none" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation" signature="int,int"/>
        </classes>
    </locations>
</rootCheck>

Note:
Root Checks are only supported on Android.

<rootResponse> Element

A Root Response allows you to have the application respond to a Root Check in an area away from where the Check itself occurred (see Root Check and Response). The Root Response has the standard attributes.

<rootResponse source="myBoolean" response="error"
        where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation" signature="double"/>
        </classes>
    </locations>
</rootResponse>

Note:
Root Responses are only supported on Android.

<shelfLifeCheck> Element

A Shelf Life Check determines if the application has expired or is about to expire based on the expiration parameters (see Shelf Life). The Shelf Life Check has all of the standard attributes, except response, and adds the following:

• expirationDate - absolute date that the application expires in MM/DD/YYYY format.

• warningDate - absolute date that warnings about expiration will start to be emitted in MM/DD/YYYY format.

• startDateSource - source for the start date provided at runtime as a java.util.Date.

• expirationPeriod - relative expiration date in number of days since the start date.

• warningPeriod - relative warning date in number of days until the expiration date.

• tokenSource - source of the Shelf Life token as a java.io.Reader if managing it externally.

Note: The standard action attribute, in this case, expects a method which accepts a Token argument and returns void. (default: the default action as described in ShelfLifeCheck)

<shelfLifeCheck action="customShelfLifeAction()" where="End"
        expirationDate="11/01/2016" warningDate="10/01/2016">
    <locations>
        <classes name="com.example.Main">
            <method name="earlySetupMethod" signature="java.lang.String"/>
        </classes>
        <classes name="com.example.MyOtherClass">
            <method name="infrequentButCriticalCalculation" signature="double"/>
        </classes>
    </locations>
</shelfLifeCheck>

<tamperCheck> Element

A Tamper Check determines if your application has been modified (see Tamper Check and Response). The Tamper Check has the standard attributes.

The Tamper Check can optionally include a signerInfo element configuring the signing information. This will override the information set in <signjar>.

• alias - The alias used to store the private key in the key store. May reference DashO properties.

• keystore – The URL to the key store; defaults to .keystore in the user's home directory. If the URL does not include a protocol the key store is assumed to be a file. May reference DashO properties.

• storepass – The password for the key store. The user interface stores this in an encoded form but the value can be in plain text. May reference DashO properties.

• storetype – The type of the key store; defaults to the value set for keystore.type in the Java security properties file. May reference DashO properties.

<tamperCheck action="myBoolean" response="none" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation" signature="int,int"/>
        </classes>
    </locations>
    <signerInfo alias="correct_cert" storepass="[SbJlvHrFg8s4GblvgMcQ4w==]"
                keystore="keystore.ks"/>
</tamperCheck>

<tamperResponse> Element

A Tamper Response allows you to have the application respond to a Tamper Check in an area away from where the Check itself occurred (see Tamper Check and Response). The Tamper Response has the standard attributes.

<tamperResponse source="myBoolean" response="error"
        where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation" signature="double"/>
        </classes>
    </locations>
</tamperResponse>

<locations> Element

All the Checks and Responses require locations to be set. The <locations> element requires <classes> as its children.

Specifying Sources and Actions

Checks and Responses may specify sources and actions. Sources provide data to injected code at run time either in a field or as the result of a method call. Actions provide either custom behavior invoked by injected code or specify a field in which to record results. Sources and actions can reference either a field or a method defined in the current class or a static method or field in a different class.

Static fields and methods can be used from any method. Instance fields and methods can only be used from instance methods in the same class. Fields must have the expected type as required by the annotation. Methods must have the expected return type and parameters as required by the annotation. Specified fields and methods must be accessible from the injection location at runtime.

Use the following format for specifying the field or method:

• field - use the field field in the current class as the source. If the source is used from a static method it must be static, otherwise it may be an instance or static field.

• @field - use the static field field in the current class as the source. This can be used from static or instance methods.

• class.field - use the static field field in the class class as the source. class is a fully qualified Java class name. This can be used from static or instance methods.

• method() - use the method method in the current class as the source. If the source is used from a static method it must be static, otherwise it may be an instance or static method.

• @method() - use the static method method in the current class as the source. This can be used from static or instance methods.

• class.method() - use the static method method in the class class as the source. class is a fully qualified Java class name. This can be used from static or instance methods.

Notes:

The @ cannot be used when referencing a static method or field in a different class. The @ is optional when referencing a static method or field in the same class.


If this source or action is being used by a Check or Response which is configured to inject into multiple locations, the specified source or action must be relative to each of the injection locations.


An incorrectly specified source or action will cause an error.

<includelist> and <excludelist> Rules

Some elements in the project file use <includelist> and/or <excludelist> to fine tune the items to which an operation is applied. These elements specify a list of rules that are applied to select a given class, method, or field.

For elements that use both includes and excludes includes are determined first. If the <includelist> is empty then all item are included. If an item is included then the exclude rules are checked. If the <excludelist> is empty then no items are excluded. Rules within each list are applied in the order that that they are specified in the project file. There is also a <globalProcessingExclude> element which used in addition to the <excludelist> configured for a given functionality. Additionally, internal rules of DashO, the requirements of other options, and the classes themselves may cause items to be excluded.

The name of classes and members and well as method signatures may be specified as literals, patterns or regular expressions. See Names: Literals, Patterns, and Regular Expressions for details. The modifiers of the item can also be used as criteria, see Modifiers attribute for details.

<classes> Element

The <classes> element is used to define a rule that selects one or more classes. Note that the class name should be fully qualified names and inner classes are specified by using a $ as the separator between outer and inner class names.

The <classes> element selects a class in order to specify additional rules for selecting fields and methods. If the element does not contain any <field> or <method> elements, then it can be used to apply to either all members of the class or the class itself. This behavior is determined by the option that is using the rule.

Some exclude lists allow a <classes> name to be applied to the class itself rather than the members of the class. This is controlled by the optional, excludeclass attribute. The default value for the excludeclass attribute is true. Please consult the individual elements that use <excludelist> to see if the excludeclass attribute is used by that option.

<classes name=".*" regex="true"/>

<classes name="library.Class1$NestedClass"/>

<classes name="myco.Test.MyOtherTest" excludeclass="false"/>

<method> Element

<method> elements are used inside the <classes> element. Methods may be selected by name and signature. The setting for the <method>'s regex is inherited from the <classes> element: if the value of regex for the enclosing <classes> is true, the name and signature attributes are regular expressions. The following example selects all methods beginning with set with any number of parameters using a regular expression:

<classes name=".*" regex="true">
    <method name="set.*" signature=".*"/>
</classes>

The signature attribute can be used as criteria for selection. The signature attribute is a comma separated list of Java types that match the types in the method's parameter list. The class names of the parameters must be fully qualified. Use an empty string to specify a method that has no parameters.

<classes name=".*" regex="true">
    <method name="get[A-Z].*" signature=""/>
</classes>

<classes name=".*">
    <method name="set*" signature="int,MyClass,MyClass[]"/>
</classes>

<classes name="AnalysisEngine">
    <method name="compute" signature="int,java.util.List,float[]"/>
</classes>

<field> Element

<field> elements are used inside the <classes> element. If the value of regex for the enclosing <classes> is true, the name attribute must be a regular expression.

The <field> element is not applicable to all include or exclude lists as the actions of some options only apply to methods. Please consult the individual elements that use include or exclude lists to see if the <field> element can be used. The following example selects all fields starting with counter using a regular expression:

<classes name=".*" regex="true">
    <field name="counter.*"/>
</classes>

Combining <method> and <field>

A <classes> element can contain multiple <method> and <field> elements to create a rule that selects many items in your project. For example:

<classes name="com\.yoyodyne\.beans\..*" regex="true">
    <method name="get[A-Z].*" signature=""/>
    <method name="set[A-Z].*" signature=".*"/>
    <method name="is[A-Z].*" signature=""/>
    <field name="CONST_.*"/>
</classes>

Modifiers attribute

The <classes>, <method> and <field> elements all have a modifiers attribute. The attribute is used to match the item by its Java modifiers or keywords. Multiple modifiers can be specified by separating them with spaces. If modifiers is omitted then the modifiers of the item are not used as part of the matching criteria. The modifiers are:

• public – the visibility of the item is public in the source code.

• protected – the visibility of the item is protected in the source code.

• private – the visibility of the item is private in the source code.

• default – this represents the default visibility given to an item when neither public, protected, nor private has been specified in the source code.

• abstract – the item has been marked abstract in the source code. It has no meaning when used with <field>.

• final – the item has been marked final in the source code.

• static – the item has been marked static in the source code.

• native – a method has been marked as native in the source code. It has no meaning when used with <classes> or <field>.

• strictfp – the item has been marked as strictfp in the source code.

• synchronized – the method has been marked as synchronized in the source code. It has no meaning when used with <classes> or <field>.

• transient – the field has been marked as transient in the source code. It has no meaning when used with <classes> or <method>.

• volatile - the field has been marked as volatile in the source code. It has no meaning when used with <classes> or <method>.

• class – the item is a class. This only has meaning when used with <classes>.

• interface – the item is an interface. This only has meaning when used with <classes>.

• enum – the item is an enum. This only has meaning when used with <classes>.

• annotation – the item is a Java annotation. This only has meaning when used with <classes>.

• synthetic – the Java compiler has created this item as an implementation detail and it does not appear as part of the source code.

Unrecognized modifiers are ignored. Modifiers can also be specified as a negation by adding a ! before the modifier. Modifiers are not case sensitive.

<classes modifiers="public class" name="com.yoyodyne.*">
    <method modifiers="!private !native" name="*" signature="**"/>
    <field modifiers="!public final" name="*"/>
</classes>

<classes modifiers="!default !private !enum !annotation" name="**">
    <method modifiers="!default !private" name="*" signature="**"/>
    <field modifiers="!default !private" name="*"/>
</classes>

Names: Literals, Patterns, and Regular Expressions

Name of classes and members may be specified as either a literal value, a pattern, or as a regular expression. A literal value lets you specify exactly what item to match while patterns and regular expressions let you match one or more items with a single entry. By default names are treated as literal values unless they contain a ? or *. To specify a regular expression, the regex="true" attribute must be added to the element.

Using regular expressions

The regular expressions entered must be able to be compiled by Java's regular expression support and build will fail if an invalid pattern is used. See the Java Regular Expression Tutorial for details on the supported syntax of Java regular expressions.

Note: If you are trying to match a method signature which has no arguments, use ^$ or \Q\E for the regular expression.

Using Patterns

Patterns are just like literal values but contain one or more of the following pattern indicators:

• ? - Matches a single character.

• * - Matches zero or more characters, with limits. What can be matched depends upon the type of item you are matching - this is discussed in the following sections.

• ** - Matches zero or more characters without limits.

Patterns in Class Names

When a * is used in a class name it will match items within a single package, but not in sub-packages. The ** pattern will match items within the package or any sub-package.

Patterns in Method and Field Names

There is no difference between a * and ** used in method and field names. Both match zero or more characters.

Patterns in Method Signatures

When patterns are used in method signatures, there is a difference between the * and **. The * pattern will match zero or one argument to the method while the ** will match any number of arguments.

Here are examples of signature matching:

Note: If you are trying to match a method signature which has no arguments, leave the pattern blank.