PreEmptive Protection - DashO v8.1 User Guide

Project File Reference

This section documents PreEmptive Protection - DashO’s XML project file. 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 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> tag is the outermost tag 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="6.9" project with version 7.2 of DashO without having to edit the project.

<dasho version="7.2.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.

<propertylist> Section

The optional <propertylist> section 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:

${prop} Simple replacement. If the value for prop is undefined or is blank, then no replacement takes place and ${prop} is left unchanged.
${prop:-default} Replacement with default value. If prop is defined and not blank, use its value. Otherwise, use default as the value.
${prop:+value} Replace when defined. If prop is defined and not blank, then value is used. Otherwise a blank string is substituted when prop is defined.
${prop:?message} Generate error if not set. If prop is defined and not blank then its value is used. Otherwise an error with the text of message is generated and the build ends.
${prop/pattern/replace} Replacement after pattern substitution. Replaces the first occurrence of the regular expression pattern with the replacement text replace. If replace is blank, then the matching text is deleted.
${prop//pattern/replace} Replacement after pattern substitution. Replaces all occurrences of the regular expression pattern with the replacement text replace. If replace is blank, then the matching text is deleted.
${prop/#pattern/replace} Replacement after pattern substitution. Replaces the leading regular expression pattern with the replacement text replace. If replace is blank then the matching text is deleted.
${prop/%pattern/replace} Replacement after pattern substitution. Replaces the trailing regular expression pattern with the replacement text replace. If replace is blank then the matching text is deleted.
${prop#pattern} Replacement after pattern deletion. Deletes the leading regular expression pattern.
${prop%pattern} Replacement after pattern deletion. Delete the trailing regular expression pattern.
${!prop} Indirect replacement. If prop is defined and not blank, then its value is used as a property name. The value of this property is then used as the replacement value. You can use indirect placement followed by any of the previously described references.

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.

And these properties depend upon the execution environment.

  • ${dasho.java.version} - the JVM version DashO detected; "1.7" or "1.8".

  • ${jce.jar} – the absolute path of the Java Cryptography Extension jar.

  • ${jsse.jar} – the absolute path of the Java Secure Socket Extension jar.

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

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:

  • 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 tags:

  • <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>/<quickjar>'s path 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 attribute

  • <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

  • <expiry>’s period, warningperiod, date, and warningdate attributes

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

  • <tamperCheck>'s action and customDataSource attributes

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

  • <tamperResponse>'s source and customDataSource attributes

  • <debugEnabledCheck>'s action and customDataSource attributes

  • <debugEnabledResponse>'s source and customDataSource attributes

  • <debuggingCheck>'s action and customDataSource attributes

  • <debuggingResponse>'s source and customDataSource attributes

  • <annotations>/<property>'s value attribute when the name's value is customDataSource

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

<global> Section

The optional <global> section is for defining options that apply across the entire run. This section 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.

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

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

Note:

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

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

Makepublic and Nomakepublic Global Options

By default, DashO changes the access modification of all classes, non-private methods, and non-private fields to public before writing them to disk. This has several ramifications:

  • This solves the problem of classes that change package membership and use protected or default(package-private) access modifiers.

  • In general, this is not dangerous since DashO does not induce method calls into your program. After all, the compiler enforced the access restrictions at compile time.

  • Feasibly, dynamic linking of public methods should be faster than that of more restricted access levels. Primarily because public has no restrictions there is no need for the runtime to verify equivalent package or class membership.

To stop this behavior, use the nomakepublic option; to force this behavior, use the makepublic option; to use the default behavior, that is to let DashO decide what to do, do not include either option.

Note:

Using nomakepublic may cause access errors with protected or default(package-private) access modifiers on classes, methods, or fields. That is, a class that was in a given package may now be in a new renamed package. However, it may still attempt to access non-public classes, methods, or fields from the original package causing an access exception.

DashO’s default behavior generally avoids this problem and has been shown to be safe for most applications.

<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> section. These ambiguous cases correspond to what the fornamedetection option would report as a possible confidence level.

Note:

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.

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

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>

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

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> Section

The <inputpath> section 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.

<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> Section

The <globalProcessingExclude> section contains the location of classes which should be excluded in all processing. This has the same effect as including them in the excludes sections of the individual areas such as ControlFlow and Renaming.

<globalProcessingExclude>
    <classes name=”android**”/>
    <classes name=”com.example.ExcludeMe”/>
</globalProcessingExclude>

<classpath> Section

The <classpath> section 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, and jar files in the classpath. The location can also contain multiple entries when separated by the OS specific classpath separator.

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

Note:

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

Systemclasspath attribute

Optionally you can append or prepend the system classpath in addition to the directories and jars specified in the <classpath> section. The following option appends the system classpath to the list of the directories and jars specified in the <classpath> section.

<classpath systemclasspath=”append”>
    <pathelement location="c:\test\classes"/></classpath>

Note: The system classpath is composed of the values in the sun.boot.class.path property and the CLASSPATH environment variable where available.

Appendrtjar attribute

By default DashO adds the runtime jar of the version of Java it is currently using. If you need to use a different version you can control this behavior.

<classpath appendrtjar=”false”>
    <pathelement location="c:\Java\jre1.7.0_80\lib\rt.jar"/>
</classpath>

Note:

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

<entrypoints> Section

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.

Entry points are analyzed by DashO to determine which classes, methods, and fields are required for classes to function. For example, all methods called by your entry points, and subsequent methods called by those methods, are required by DashO. That is, if you tell DashO a specific main method is required, then all the methods that main method calls are required as well.

<quickjar> Entry Point

The Quick Jar entry point may be used to obfuscate a program or an API library encapsulated in a JAR file.

In order for this option to work for an application, the manifest of the JAR file must contain a line of the form Main-Class: {classname}. Here, {classname} identifies the class having the public static void main(String[] args) method that serves as your application's starting point.

DashO uses this information in the manifest to do the static dependency analysis. If the manifest does not have Main-Class information, DashO processes the jar as a library. DashO automatically uses all the public methods in the jar as entry points.

Assume the input jar has a manifest file with a Main-Class entry:

Main-Class: test.MyApplication

In this case, the main method of the class test.MyApplication will be considered as entry point.

  • You may specify multiple Quick Jar entry points; however, you cannot mix Quick Jar entry points with any other kind of entry points.

  • The pruning or removal feature of DashO is shut-off in quick jar mode and the values put in the <removal> section are ignored.

  • If you specify multiple Quick Jars as entry points, then DashO writes the obfuscated classes to only a single output jar or directory.

  • All the non-class files in the input jar are automatically included in the output.

  • Control Flow, Optimization, and String Encryption includes and excludes are ignored.

<entrypoints>
    <quickjar path="c:\myapp.jar"/>
</classpath>

<method> and <field> Entry Points

Entry point methods indicate where your application starts. If you were looking at a code listing and someone asked what that code did, where would you look first? You would probably check if the code contained a main method. That main is the entry point method for that application. In general, you use the main of a given class:

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

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 &lt; and &gt; 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

By default entry points are not renameable since they are referenced by some outside mechanism. In some cases entry points can be renamed. For example, DashO will update the Main-Class attribute of a jars manifest with the renamed class. In this case the class can be renamed, but the main method cannot. The <classes>, <method> and <field> tag all have a rename attribute to control the renameability of the item.

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

<publics> Entry Point

Like the <classes> entry point, the name attribute can be a literal, a pattern, or a regular expression. At times, you may have a class that is an interface to your application. It may have many methods that are entry points into your application. If you wish to specify all the public methods of a given class as entry points, you can specify each individually or use the <publics> tag.

<entrypoints>
    <publics name="test.MyApplet"/>
</entrypoints>

The classes and members specified by the <publics> can also be made renameable using the rename-class and rename-members attributes: both attributes are optional and default to false.

<entrypoints>
    <publics name="com.yoyodyne.**Bean" rename-class="true" rename-members="false"/>
</entrypoints>

<library> Entry Point

For API libraries, you can specify all public and protected methods of all classes in a directory or jar by using the library option.

<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 value of public can be on or off. If omitted, on is assumed.

All public methods of all classes found through a recursive descent of all directories below myAPIDirectory will be used as Triggers. The myAPIDirectory should not be part of a package designation. It is to be the directory where the packages live: it would be the same directory you would put on the classpath. Using a jar is straightforward - all classes found in the jar are used. The path value location can contain multiple entries by separating them with the OS specific classpath separator.

If you would like only public methods to be used as entry points, you may use the library tag with public set to on.

<classes> Entry Point

It is also possible to include classes without making assumptions about which methods are to be included. Manually specifying classes here is vital for some applications to package correctly. If you use the Class.forName() construct in your application, DashO cannot determine all possible classes that are needed. In this case, DashO informs you of the locations of the forName(s) and exits. You must then manually enter those classes here and re-run DashO with the force option. Any classes specified here are open to method and/or field removal.

<entrypoints>
    <classes name="com.yoyodyne.Application"/>
</entrypoints>

This would cause DashO to load com.yoyodyne.Application but not use any methods or fields as entry points. If that class overrides system methods or other user-created methods, then its methods are included too. Classes entered this way are renameable if the global renameforname option is turned on.

<unconditional> Entry Point

At times, you need a class to be included, even if it is not explicitly referenced by other classes. This is done through the unconditional entry points. In this case all members of the class are used as entry points and will appear in the output. Like other entry points, the name may be a literal, a pattern or a regular expression. By default the class and members are not renameable, but they can be made renameable by using the rename-class and rename-members attributes.

Entry Points for Special Applications

DashO has several distinct types of Java application configurations built-in. For convenience, DashO defines special syntax to specify the entry points for some of these applications. Names can be specified as literals, patterns or as regular expressions: See Names: Literals, Patterns, and Regular Expressions. By default the class and members are not renameable. All types use the rename-class attribute and some support the rename-members attribute.

<applets>

An applet’s init() and paint() methods, among others, are automatically included. Any methods that an applet overrides automatically become entry points. However, you do need to specify the full format designation for what applet class is the entry point class.

<entrypoints>
    <applet name="test.MyApplet"/>
</entrypoints>

The <applets> tag uses the rename-class attribute (false by default), but not the rename-members: the entry point members are defined by the interface and are not renameable. Other methods in the class are renameable.

<servlets>

You may specify entry points for servlets as:

<entrypoints>
    <servlet name="test.MyServlet"/>
</entrypoints>

The <servlets> tag uses the rename-class attribute (false by default), but not the rename-members: the entry point members are defined by the base classes and are not renameable. Other methods in the class are renameable.

<ejb> Enterprise Java Beans

Enterprise JavaBeans have their own notation to designate classes related to a given EJB:

<entrypoints>
    <ejb name="MyEntityBean"/>
    <ejb name="MyRemoteInterface"/>
    <ejb name="MyHomeInterface"/>
    <ejb name="MySessionBean"/>
    <ejb name="MyPrimaryKey"/>
</entrypoints>

The <ejb> tag uses both the rename-class (false by default) and rename-members (false by default) attributes.

Note:

Alternatively, you can use the <publics> notation with the EJBs to specify their entry points.

<midlet> and <iappli>

DashO provides explicit support for applications written to the Mobile Interconnected Device Profile (MIDP) specification (midlets). Your midlet class can be a subclass of javax.microedition.midlet.Midlet at any level of descendancy.

<entrypoints>
    <midlet name="test.MyMidlet"/>
</entrypoints>

Similarly, DashO explicitly supports applications written for NTT DoCoMo’s iAppli framework. Your iAppli class can be a subclass of com.nttdocomo.ui.IApplication at any level of descendancy.

<entrypoints>
    <iappli name="test.MyIappli"/>
</entrypoints>

Both tags use the rename-class attribute (false by default), but not the rename-members: the entry point members are defined by the base classes and are not renameable. Other methods in the class are renameable.

Configuration for Midlet Projects

Do not include the Java Runtime Jar. See the appendrtjar attribute section. Instead setup an environment variable or property that points to your installation of the Wireless Toolkit from Oracle.

Note: If you have an environment variable called WTK_HOME setup you can use it directly or you can create a DashO property to use its setting.

<propertylist>
    <!-- To force the environment variable to be set -->
    <property name="wtk.home" value="${WTK_HOME:?WTK_HOME not defined}"/>
    <!-- To use a default if not set -->
    <property name="wtk.home" value="${WTK_HOME:-C:\WTK2.5.1}"/>
</propertylist>

Add the cldcapi and midpapi jars to the classpath. These jars are part of the Wireless Toolkit from Oracle.

<classpath>
    <jar path="${wtk.home}/lib/cldcapi10.jar"/>
    <jar path="${wtk.home}/lib/midpapi10.jar"/>
</classpath>

Set up preverification for the project.

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

<android>

DashO provides support android classes. Your class can be a subclass of android.app.Application, android.app.Activity, android.app.Service, android.content.BroadcastReceiver, or android.content.ContentProvider. The entry points are the classes listed in the AndroidManifest.xml. Only classes that are not referenced outside your application should be renamed.

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

The <android> tag uses both the rename-class (false by default) and rename-members (true by default) attributes.

<springbean>

DashO provides support Spring Beans. These will be classes referenced in your beans.xml file. 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.

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

  • renameEntryPointsTrue/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>

The <springbean> tag uses both the rename-class (true by default) and rename-members (true by default) attributes. All public constructors of these beans will be preserved.

<report> Section

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.

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

Since there is no removal in Quick Jar mode, there is also no report file produced. 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> Section

The <output> tag 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.

<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\dashoed.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 zip 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> tag or when merge=false, you can specify attributes that customize the jar creation:

  • compress=”boolean” – Determines if the entries in the jars be compressed. Defaults to true.

  • level="0-9" – The compression level for jar entries. Defaults to 6. Higher values give higher compression.

  • filesonly="boolean" – Determines if the jars contain only file entries or both field and directory entries. Defaults to true.

  • includenonclassjars="boolean" – Determines if the jars that do not contain any remaining classes should be included in the output. Defaults to false.

<output merge="false" compress="true" level="4" filesonly="false">
    <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 Attribute

When DashO creates an APK using the <apk> tag, you can specify if it should be aligned after it is signed:

  • zipAlign=”boolean” – Determines if zipalign should be called after it is signed. Defaults to false. It should only be set to true if the APK is also being signed.

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> tag'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. 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 that a <dir path="…"/> tag. If a <jar path="…"/> tag is provided then themerge="false" setting is ignored. In Quick Jar mode the merging always takes place.

Autocopy Attribute

When merge="false" is specified you can also specify the autocopy attribute. When autocopy="true" is specified non-class files in input jars input are automatically copied to their respective output. Non-class files that appear in input directories are never copied. This setting only applies to <dir> outputs.

<output merge="false" 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 tag 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> Section

The <removal> option allows you to specify what level of granularity you want for class, method and/or field removal, and metadata removal. For class and member removal there are two attributes on the tag classes and members. 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>, removal will not occur.

If you are packaging a true application - not something that’s sub-classed or called by other classes - then the unused option is the best choice.

Pursuant to the license agreements you have with the third-party API libraries you use, it is best practice to allow DashO to include all classes your application needs. That way the resulting output would be one jar or directory that contains every class your application needs, tailored specifically to how your application uses it.

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"/>

Note:

Removal is off in Quick Jar mode. Quick Jar mode ignores all the options set in the removal section.

<debug> Section

This section instructs DashO to remove debug information inserted into the class files by a compiler. The type attribute is used to specify the types of information to be removed. The following types can be removed:

  • SourceFile - The name of the source file from which the class was compiled.

  • SourceDirectory - The location of the source file from which the class was compiled.

  • SourceDebugExtension - A tool specific string that is interpreted as extended debugging information.

  • LineNumberTable - Maps byte codes to a given line number in the original source file. Used by debuggers and stack traces.

  • LocalVariables - Used by debuggers to determine the name and type of local variables during the execution of a method.

  • LocalVariableTypes - Signatures for local variables that use generics.

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> section 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="SourceDirectory SourceDebugExtension" />

Note:

The use of the control flow obfuscation transform requires the removal of local variable information even when the section does not request their removal.

<attributes> Section

The compiler stores additional metadata in attributes inside the class file. DashO lets you determine the disposition of these attributes individually. The types attribute of the tag is used to specify the type of attributes to be removed. The following types can be removed:

  • Exceptions - Indicates which checked exceptions a method may throw.

  • Signature - Indicates generic types, method declarations with generics, and parameterized types.

  • Deprecated - Indicates that the class, interface, method, or field has been superseded.

  • Synthetic - Indicates a class member that does not appear in the source code.

  • EnclosingMethod - Indicates the enclosing method for a local or anonymous class.

  • RuntimeVisibleAnnotations - Holds the annotations on a class, method, or field that are visible with reflection. (E.G. @Deprecated, @FunctionalInterface, and @SafeVarargs)

  • RuntimeInvisibleAnnotations - Holds the annotations on a class, method, or field that are not visible with reflection.

  • RuntimeVisibleParameterAnnotations - Holds the annotations on the parameters to a method that are visible with reflection.

  • RuntimeInvisibleParameterAnnotations - Holds the annotations on the parameters to a method that are not visible with reflection.

  • AnnotationDefault - Default values for annotation elements.

  • InnerClasses - Indicates relationships between inner and outer classes.

  • Unknown - All other attribute types. (including the MethodParameters attribute)

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> section 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> Section

DashO can remove calls to methods with void return types. This allows calls to logging or console output to be easily removed from the production code. There are no attributes for the <methodCallRemoval> element. All configuration is contained in the <method> sub elements.

<method> Section

This section defines the methods that should not be called in the output.

The attributes of this tag identify the method not to call by class, method name and signature.

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

  • methodName – This string attribute specifies the name of the method.

  • signature – This string attribute specifies the parameters of the method.

className attribute

The className string attribute contains the full name of the package and class that contain the method. Only calls made to methods on this class directly will be removed. Calls made to the same method name and signature on a subclass will not be removed. Specifying a class name of ** will instruct DashO to remove all calls the method and signature regardless of which class contains it. If ** is used, a renaming exclusion rule must be added to prevent those methods from being renamed.

methodName attribute

The methodName string attribute contains the name of the method. The method specified cannot be an initialization or constructor method and must return void.

signature attribute

The signature string attribute contains the parameter types of the method. The parameters must be specified in order and separated by commas. Array parameters are specified by adding a [] for each dimension after the type name. When entering object type parameters, the full path must be used. Exact case and spelling is necessary as mistyping “double” as “doubel” will treat that parameter as an Object with the name “doubel” instead of a primitive double.

<methodCallRemoval>
    <method className="**" methodName="method1" signature="java.lang.String"/>
    <method className="com.example.methodCallRemoval.SubSubClassOne"
        methodName="method2" signature="java.lang.String, int, double,
        float[][]"/>
</methodCallRemoval>

<renaming> Section

DashO can rename classes, methods, and fields to short meaningless names. This is significant in class size reduction and as an obfuscation technique. Subsequent sections allow you to exclude given classes and members from being renamed.

Note:

See the Advanced Topics regarding DashO’s renaming algorithm and its ramifications.

This tag 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> Section

The attributes of this tag control the renaming of classes.

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

  • keeppackages – This boolean option allows you to rename the classes itself while keeping the original package names and hierarchy.

  • alphabet – a string that defines the characters used to create new class names.

  • minlength – the minimum length of new class names.

  • randomize – The new names for classes can be assigned in either a sequential or random order. When this option is true, identifiers are assigned in a random order.

  • prefix – This attribute specifies a prefix that is added to all renamed classes. If it contains a period then the class is effectively placed in a new package.

prefix attribute

The prefix is appended to all renamed classes. By defining a prefix that contains a period the renamed classes can be placed in a custom package.

<renaming option="on"/>
    <class-options prefix="pkg.X_"/>
</renaming>

The following table shows the renaming possibilities using a prefix:

Prefix New Name
C Ca
pkg. pkg.a
pkg.X_ pkg.X_a
keeppackage attribute

When this option is true the name of the class is changed but the package portion of its name remains unchanged.

<renaming option="on"/>
    <class-options keeppackages="true"/>
</renaming>

An example of this type of renaming is:

Original Name New Name
yoyodyne.application.Main yoyodyne.application.a
yoyodyne.application.LoadData yoyodyne.application.b
yoyodyne.tools.BinaryTree yoyodyne.tools.c
yoyodyne.tools.LinkedList yoyodyne.tools.d

When used with a prefix the original package name appears before the portion added by the prefix.

<renaming option="on"/>
    <class-options keeppackages="true" prefix="x_"/>
</renaming>

This would result in:

Original Name New Name
yoyodyne.application.Main yoyodyne.application.x_a
yoyodyne.application.LoadData yoyodyne.application.x_b
yoyodyne.tools.BinaryTree yoyodyne.tools.sub.x_c
yoyodyne.tools.LinkedList yoyodyne.tools.sub.x_d
alphabet attribute

The optional alphabet attribute defines the characters that are used to create new class names. If omitted the default alphabet is used. When defining an alphabet the following restrictions apply:

  • The minimum length of the alphabet is two characters. Three or more are recommended for larger projects.

  • The initial characters of the alphabet must be valid starting characters for Java identifiers. You must have at least one starting character.

  • The remaining characters of the alphabet must be valid characters for Java identifiers.

<member-options> Section

This section 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> section treats all public methods as entry points inherently retaining their original names. Specifying this option would be redundant.

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

  • minlength – the minimum length of new member names.

  • randomize – The new names for members can be assigned in either a sequential or random order. When this option is true, identifiers are assigned in a random order.

<renaming> Exclude List

This section provides a dynamic way to fine tune the renaming of the input class files. It can contain a list of exclude rules that are applied at runtime. If a rule selects a given class, method, or field, then that item is not renamed.

Note:

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

The rules are logically OR-ed together: any item selected by at least one rule is not renamed. The <excludelist> has support for excluding names by class, method, and field.

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

<mapreport> Section

DashO can produce a report of all the renaming it has performed as well as statistics about the renamed results. This is created using the nested <mapreport> tag.

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

Note:

The path attributes support properties.

An example of the listing is:

one.A (b)
========================================================================
a pub1(int)
b def1(int)
c pub2(int)

two.B (c)
========================================================================
a pub1(int)
b pub2(int)
c def1(int)

The new names of the classes and methods are shown. Bug tracking becomes difficult after renaming, especially with a high incidence of method overloading, making the map file essential. The map file also provides statistics regarding the success of overload-induction:

Number of Methods : 7095
Renamed to ’a’ : 2031 (28.6%)
Renamed to ’b’ : 786 (11.0%)
Renamed to ’c’ : 484 (6.8%)
Renamed to ’d’ : 327 (4.6%)
Renamed to ’e’ : 230 (3.2%)
Renamed to ’f’ : 169 (2.4%)
Renamed to ’g’ : 131 (1.8%)
Renamed to ’h’ : 120 (1.7%)
Renamed to ’i’ : 106 (1.5%)

These statistics represent the total number of methods that were renamed to each given name.

<mapoutput> Section

Specifying the <mapoutput> file option instructs DashO’s renamer to keep track of how things were renamed for both your immediate review and to be used as input in a future DashO run. This option creates a file that is used in the map input file to do Incremental Obfuscation and decode obfuscated stack traces.

Accidental loss of this file can destroy your chances of incrementally updating your application in the future. Therefore, proper backup of this file is crucial. For this reason, DashO does not automatically overwrite this file if an existing one is found.

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

Note:

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

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

<mapinput> Section

A file created from the <mapinput> option can be used in the incremental input file option.

<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> Section

The <optimization> section allows you to specify options that are specific to byte code optimization including fine-grained rules for including and excluding items. When the option attribute is set to off, DashO skips optimization altogether, regardless of what is in the rest of the section.

<optimization option="on"/>

To fine tune where optimization takes paces the <optimization> section 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>

Note:

Quick Jar mode ignores all includes and excludes in the <optimization> section.

<controlflow> Section

The <controlflow> section allows the user to specify options that are specific to control flow obfuscation including fine-grained rules for including and excluding items. When the option attribute is set to off, DashO skips control flow obfuscation altogether, regardless of what is in the rest of the section. When the tryCatch attribute is not set or is set to on, additional exception handlers will be added to the code to further confuse decompilers. The catchHandlers attribute determines the maximum number of exception handlers to add to a method.

<controlflow option="on" tryCatch="on" catchHandlers="1" />

Control flow obfuscation adds an extra level of protection for your Java code but at times, this transformation is drastic and can affect performance. To fine tune where control flow obfuscation is performed the <controlflow> tag 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>

Note:

Quick Jar mode ignores all includes and excludes in the section.

<stringencrypt> Section

The <stringencrypt> section allows the user to specify options that are specific to string encryption obfuscation including fine-grained rules for including and excluding items. When the option attribute is set to off, DashO skips string encryption altogether, regardless of what is in the rest of the section.

<stringencrypt option="on"/>

String encryption hinders examination of your code by making it more difficult to use simple string searches to locate critical parts of your program but decrypting the strings at runtime does add some performance overhead. To fine tune where strings are encrypted the <stringencrypt> tag 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. This section also may include a <seInput> and <seOutput> which are explained in the <seInput> and <seOutput> section.

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

Note:

Quick Jar mode ignores all includes and excludes in the <stringencrypt> section.

level and implementations attributes

The level and implementations attributes allow you to increase the complexity of the string encryption process. The value for level goes from 1 with a simple but fast decryption to 10 with a complex implementation that can slow down parts of your application. The default value for level is 2. Increasing the value uses a mix of expressions that complicate the decompilation or reverse engineering of the string values. Larger values also introduce randomness into the implementation of the decryption methods to make locating them by byte code patterns more difficult.

The implementations attribute determines how many unique decryption methods will be generated and added to classes in the input. The names of the methods and signatures are randomly selected. The decryption methods are placed in the shortest named classes to minimize application size growth. For classes with equal length names those with more methods or greater complexity are selected first. Up to ten implementations can be added. The default value for implementations is 2.

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

<decrypter> Section

The <decrypter> section lets you control where DashO will place the methods that are used to decrypt the strings at runtime. This tag is similar to the <classes> tag used in <includelist> and <excludelist> Rules.

Classes selected in this section will be used as the outer classes for generated anonymous static inner classes that will house the decrypters.

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

  • name – The name of the class. This can be the name of the class, a pattern that selects multiple classes, or a regular expression.

  • regex – Determines the interpretation of the name attribute. If true then name is a regular expression.

  • modifiers – The modifiers used to select the classes. See Modifiers attribute for details.

  • excludedPackages – A comma separated list of packages that are excluded from placing a decrypter class. The default root packages names are: java, javax, and android.

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

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

<seInput> Section

The <seInput> section holds the file that describes the string decrypters from a previous run. It is used during an incremental obfuscation.

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

<seOutput> Section

The <seOutput> section holds the file to store information regarding the string decrypters from the current run. If this file exists, it will be overwritten.

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

<customEncryption> Section

The <customEncryption> section holds the information concerning using a custom encryption and decryption methods.

  • useCustomEncryption – Sets if the custom encryption should be used (true/false).

  • encryptionJar – The path to the jar file containing the custom encryption class and method.

  • encryptionClass – The full name of the class that implements the custom encryption method.

  • encryptionMethod – The name of the method used to encrypt the strings.

  • decryptionClass – The full name of the class that implements the custom decryption method.

  • decryptionMethod – The name of the method used to decrypt the strings.

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.

Please see the Using Custom Encryption section for more information concerning custom 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> Section

The <make-synthetic> section controls the make synthetic obfuscation option. This option marks methods and fields as synthetic, generated by the Java compiler, which confuses some decompilers. The tag contains a single attribute, value, which has four possible settings:

  • none – No methods or fields are affected. This is the same as omitting the entire section.

  • private – Methods and fields that are private or package-private are made synthetic.

  • non-public – Methods and fields that are private, package-private, or protected are made synthetic.

  • all – All methods and fields are made synthetic. This is the default if the value attribute is omitted.

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

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

<premark> Section

The <premark> section explains how to specify options that are specific to software watermarking. If the option set to off, DashO skips PreMark altogether, regardless of what’s in the rest of the premark section. When it is on, DashO watermarks your application using the specified encoding and watermark string.

<premark option="on"/>

Truncate Attribute

It is not possible for DashO to predict the maximum watermark string length until the output jar has been generated. You can tell DashO what to do during a build when your watermark string will not fit in the output jar. The default setting stops the build with an error message. When set to on DashO truncates the string so it fits and prints a warning message. In both cases, the message will indicate the maximum watermark size.

<premark truncate="on" option="on"/>

<encoding>

DashO uses character encodings, called character maps, to minimize the number of bits required to encode a character. A small character encoding allows you to create a longer watermark string.

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

DashO defines five character maps you can choose from to encode your watermark string.


Name Description Bits/Character
6bit-a 6 bit Uppercase Alphanumeric and symbols 6
6bit-b 6 bit Alphanumeric and symbols 6
7bit-a 7 bit Alphanumeric and symbols 7
4bit-a 4 bit Hexadecimal 4
utf8 Any Character 8

The watermark string can have only those characters that are legal for the specified encoding. For example, if your string contains lower case letters, you cannot use an encoding such as 6bit-a which only holds upper case letters.

Note:

The user interface displays the specific characters defined in each character map.

<watermark>

The <watermark> option sets the watermark to be embedded in the output jar. The characters in the watermark string must comply with the character set permitted for the specified encoding.

The maximum size of the watermark string is governed by your configuration options and by the complexity of the target jar. In general, you can fit bigger strings in bigger jars.

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

<passphrase>

In addition, the encryption algorithm has a fixed block size. If you choose to encrypt the watermark string, it will require more space. As a result, the maximum length of your watermark string may be smaller than it is without encryption.

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

<includenonclassfiles> Section

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>

Note:

All non-class files from a jar specified using entry points are automatically copied to the destination jar.

<preverifier> Section

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.

The tag also contains the following attributes that pass additional options to the preverifier:

  • nofinalize="true/false" – Pass -nofinalize to the preverifier: no finalizers allowed.

  • nonative="true/false" – Pass -nonative to the preverifier: no native methods allowed.

  • nofp="true/false" – Pass -nofp to the preverifier: no floating point operations allowed.

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

<signjar> Section

The <signjar> section lets you run the jarsigner tool on the jars or APK created by DashO. Additional details on jar signing can be found in jarsigner - JAR Signing and Verification Tool. The <signjar> tag has the following attributes:

  • option="on/off" – Turns signing on or off. If not present, the default is on.

  • keystore="…" – The URL to the key store. Optional, 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="…" – Password for the key store. Required. This is also the default value for the private key if keypass is not specified. 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. Optional, defaults to the value set for keystore.type in the Java security properties file. May reference DashO properties.

  • alias="…" – Alias used to store the private key in the key store. Required. May reference DashO properties.

  • keypass="…" – Password for the private key used to sign the jar. Optional, defaults to 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.

  • sigfile="…" – Base name for the .SF and .DSA files. Optional, defaults to value derived from the alias.

  • internalsf="true/false" – Include a copy of the signature file in the .DSA. Optional, defaults to false.

  • sectionsonly="true/false" – The signature file will not include a header containing a hash of the manifest file. Optional, defaults to false.

  • addArgs="…" – Any additional arguments for jarsigner. Optional. If signing APKs, you may need set this to "-sigalg SHA1withRSA -digestalg SHA1".

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

<injection> Section

<instrumentation> Section

This section describes how to specify instrumentation for PreEmptive Analytics. This section includes options to define instrumentation properties, the handling of annotations, and the definition of virtual annotations.

The <instrumentation> tag has the following attributes:

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

  • honorAnnotations="true/false" – Determines if instrumentation annotations present in the compiled classes will be acted upon. If true, then DashO will process the instrumentation annotations in the classes. If not preset, then the default is true.

  • stripAnnotations="true/false" – Determines if instrumentation annotations present in the compiled class will be retained in the output. If true, DashO will remove the annotations. If not present, then the default is true.

  • sendMessages="true/false" – When set to false no messages will be sent to a PreEmptive Analytics server. If supportOffline is true then the messages will be saved for later transmission. This feature can be controlled by the OfflineMode and OfflineModeSource annotations or programmatically. If not present, then the default is true.

  • supportOffline="true/false" – Determines the disposition of messages that cannot be immediately sent to a PreEmptive Analytics server. If set to true then the messages will be stored locally until they can be sent to the server. Messages may be stored locally when sendMessages is false or communication to the server is not possible. This feature can be controlled by the OfflineModeSupport and OfflineModeSupportSource annotations or programmatically. If not present, the default is true.

  • fullData="true/false" – Determines how much information is sent that identifies the user/host and the data sent with a system profile message. Setting this to false will send the minimal amount of information which can reduce startup and shutdown time. If not present, the default is true.

If the instrumentation tag 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 <instrumentation> tag is ignored regardless of its contents. Since the attributes have default values, the following tags are equivalent:

<instrumentation />
<instrumentation option="on"
    honorAnnotations="true"
    stripAnnotations="true"
    sendMessages="true"
    supportOffline="true"
    fullData="true"/>

Note:

Instrumentation is not available in Quick Jar mode. Quick Jar mode ignores all the options set in the instrumentation section.

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

<endpoint> Section

The <endpoint> defines where the runtime information will be sent. The <endpoint> tag has the following attributes:

  • name="name" – This is the location of the PreEmptive Analytics server. The endpoint is like a URL but does not include the protocol. If not specified the PreEmptive Analytics Commercial Endpoint is used.

  • ssl="true/false" – Should HTTP or HTTPS protocol be used when sending data to the endpoint. The default value is true.

These values can also be set by the EndPoint and UseSSL annotations.

<runtime> Section

The <instrumentation> tag can contain an optional <runtime> tag that is used to specify which PreEmptive Analytics System implementation jar will be used with the application and how it will be handled. If the tag is omitted then the default values for its attributes will be used. The runtime tag has the following attributes:

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

  • merge="true/false" – Will the runtime library be merged with the application’s classes. The default value is true which allows DashO to merge the classes into the output allowing for full renaming and pruning of the implementation’s classes. If false, then the implementations jar will need to be shipped with the application and added to its class path.

<instrumentation>
    <runtime target="java15" merge="true" />
</instrumentation>

Android Use:

For Android projects you must add the android.permission.INTERNET permission to your AndroidManifest.xml so that PreEmptive Analytics can send data.

<company> and <application> Sections

The <instrumentation> tag can contain optional <company> and <application> tags. These define property values that are used by instrumentation. The tags and all their attributes are optional.

<company>
  • name="name" – the name of the application.

  • id="id" The ID of the company providing the application. This value must be specified as a GUID.

<application>
  • name="name" – The name of the application.

  • id="id" – The ID of the application. This value must be specified as a GUID.

  • version="version" – The version of the application. This version can be expressed in any format.

  • type="type" – The type of application. The type can be any user defined string.

<instrumentation>
    <company name="Yoyodyne Engineering, Inc."
        id="DF29A894-C1AB-5947-E0A2-0D9779CFFB63" />
    <application id="40A80B91-FB16-BB0F-96CF-6931B4472204"
        version="9.3.4" type="Swing App" />
</instrumentation>

<expiry> Section

The <instrumentation> tag can contain optional expiration information. 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 is provided by the application with the StartDateSource annotation.

  • 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 or are defined via virtual annotations can override or augment these values.

<instrumentation>
    <expiry key="../yoyodyne.slkey"
        date="10/25/${EXP_YR}"
        warningperiod="90"/>
</instrumentation>
Expiration Token Properties

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

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

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

Virtual Annotations

The <instrumentation> tag can contain one or more virtual annotation definitions. DashO acts on these annotations as if they were in the compiled class files. Virtual annotations can be used to augment existing annotations or to override their values. The virtual annotations are associated with the compiled classes by using one or more <classes> tags. These tags follow the same syntax as those found in include and exclude lists. See the section on <includelist> and <excludelist> Rules for more information.

Note:

The <classes> tag does not support the excludeclass attribute, nor can it contain <field> tags.

One or more annotations tags may appear inside a <classes> tag or its contained <method> tag.

<annotation> Tag

The <annotation> tag defines the virtual annotation that will be applied to a class or method. An annotation has two attributes and can have any number of nested properties.

  • name="name" – The name of the annotation. Although any name can be used here, DashO only processes the annotations that are found in the com.preemptive.annotation.instrumentation package. Annotations can be referenced by their simple name, e.g., ApplicationStart, rather than their fully qualified name.

  • value="value" – An optional value for the annotation. Some annotations such as SystemProfile do not use values, while others such as FeatureTick require one. Values can contain property references that will be expanded when the annotation is applied.

<classes name="com.yoyodyne.Overthruster">
    <annotation name="CompanyId"
        value="DF29A894-C1AB-5947-E0A2-0D9779CFFB63"/>
    <method name="main" signature="java.lang.String[]">
        <annotation name="ApplicationStart">
            <property name="customDataSource" value="staticProps"/>
        </annotation>
        <annotation name="ApplicationStop">
            <property name="customDataSource" value="staticProps"/>
        </annotation>
    </method>
</classes>

In the example above, the main method bounds the application’s start and stop. Both messages send along additional properties from the static field staticProps. Note that the company name has been set on the class, but is then used by the ApplicationStart in the main method. The order of the annotations is not important - DashO sorts out the details when the code is instrumented.

<classes name="com.yoyodyne.Overthruster">
    <method name="start" signature="">
        <annotation name="ApplicationStart">
            <property name="where" value="End"/>
        </annotation>
        <annotation name="Company">
            <property name="name" value="Yoyodyne Engineering, Inc."/>
            <property name="id" value="DF29A894-C1AB-5947-E0A2-0D9779CFFB63"/>
        </annotation>
    </method>
    <method name="stop" signature="">
        <annotation name="ApplicationStop"/>
    </method>
    <method name="testOscillation " signature="">
        <annotation name="FeatureStart" value="Oscillation Test">
            <property name="customDataSource" value="getTestParameters()"/>
        </annotation>
        <annotation name="FeatureStop" value="Oscillation Test">
            <property name="customDataSource" value="getTestParameters()"/>
        </annotation>
    </method>
</classes>

The example above shows the use of annotations that contain properties. The ApplicationStart is performed at the end of the start method. Although the Company annotation does not have a value, it consists of two properties. Both feature messages send along additional properties from the method getTestParameters().

Annotation values can use both class and method dynamic properties. You can use METHOD_NAME and PROP_NAME in annotations used at the class level. The actual values will be expanded only when the annotation is applied to a specific method.

<checks> Section

This section describes checks and responses to be injected into the code. These checks and responses must contain a <locations> Section.

<tamperCheck> Section

A tamper check determines if your application has been modified (see Tamper Checking and Response). The tamper check supports the following attributes:

  • action – The optional action call/set (see Specifying Sources and Actions).

  • response The response to take.

    • exit – exit the application with a randomly non-zero return code

    • hang – cause the current thread to hang.

    • error – throw a randomly selected error.

    • exception – throw a randomly selected unchecked exception.

    • none – Do nothing (default).

  • sendMessage – Should a message be sent to PreEmptive Analytics? (default: false)

  • customDataSource – The optional source of custom data to be sent with the message (see Custom Data Source).

  • where – Where should the code be injected?

    • Beginnging – the beginning of the method (default).

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

    • End – the end of the method.

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"
        sendMessage="false" 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> Section

A tamper response allows you to have the application respond to a tamper check in an area from the check itself occurred (see Tamper Checking and Response). The tamper response supports the following attributes:

  • source – The source to determine if the application has been tampered (see Specifying Sources and Actions).

  • response – The response to take.

    • exit – exit the application with a randomly non-zero return code.

    • hang – cause the current thread to hang.

    • error – throw a randomly selected error. .

    • exception – throw a randomly selected unchecked exception.
  • probability – The probability the response should happen. Expects a decimal from 0.0 to 1.0 (default: 1.0).

  • sendMessage – Should a message be sent to PreEmptive Analytics? (default: false)

  • customDataSource – The optional source of custom data to be sent with the message (see Custom Data Source).

  • where – Where should the code be injected?

    • Beginnging – the beginning of the method (default).

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

    • End – the end of the method.

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

<debuggingCheck> Section

A debugging check determines if your application is being debugged (see Debug Checking and Response). The debugging check supports the following attributes:

  • action – The optional action call/set (see Specifying Sources and Actions).

  • response The response to take.

    • exit – exit the application with a randomly non-zero return code

    • hang – cause the current thread to hang.

    • error – throw a randomly selected error.

    • exception – throw a randomly selected unchecked exception.

    • none – Do nothing (default).

  • sendMessage – Should a message be sent to PreEmptive Analytics? (default: false)

  • customDataSource – The optional source of custom data to be sent with the message (see Custom Data Source).

  • where – Where should the code be injected?

    • Beginnging – the beginning of the method (default).

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

    • End – the end of the method.

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

<debuggingResponse> Section

A debugging response allows you to have the application respond to a debugging check in an area from the check itself occurred (see Debug Checking and Response). The debugging response supports the following attributes:

  • source – The source to determine if the application is being debugging (see Specifying Sources and Actions).

  • response – The response to take.

    • exit – exit the application with a randomly non-zero return code.

    • hang – cause the current thread to hang.

    • error – throw a randomly selected error. .

    • exception – throw a randomly selected unchecked exception.

    • none – Do nothing (default).

  • probability – The probability the response should happen. Expects a decimal from 0.0 to 1.0 (default: 1.0).

  • sendMessage – Should a message be sent to PreEmptive Analytics? (default: false)

  • customDataSource – The optional source of custom data to be sent with the message (see Custom Data Source).

  • where – Where should the code be injected?

    • Beginnging – the beginning of the method (default).

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

    • End – the end of the method.

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

<debugEnabledCheck> Section

A debug enabled check determines if your application has debugging enabled (see Debug Checking and Response). The debug enabled check supports the following attributes:

  • action – The optional action call/set (see Specifying Sources and Actions).

  • response The response to take.

    • exit – exit the application with a randomly non-zero return code

    • hang – cause the current thread to hang.

    • error – throw a randomly selected error.

    • exception – throw a randomly selected unchecked exception.

    • none – Do nothing (default).

  • sendMessage – Should a message be sent to PreEmptive Analytics? (default: false)

  • customDataSource – The optional source of custom data to be sent with the message (see Custom Data Source).

  • where – Where should the code be injected?

    • Beginnging – the beginning of the method (default).

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

    • End – the end of the method.

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

<debugEnabledResponse> Section

A debug enabled response allows you to have the application respond to a debug enabled check in an area from the check itself occurred (see Debug Checking and Response). The debug enabled response supports the following attributes:

  • source – The source to determine if the application allows debugging (see Specifying Sources and Actions).

  • response – The response to take.

    • exit – exit the application with a randomly non-zero return code.

    • hang – cause the current thread to hang.

    • error – throw a randomly selected error. .

    • exception – throw a randomly selected unchecked exception.

    • none – Do nothing (default).

  • probability – The probability the response should happen. Expects a decimal from 0.0 to 1.0 (default: 1.0).

  • sendMessage – Should a message be sent to PreEmptive Analytics? (default: false)

  • customDataSource – The optional source of custom data to be sent with the message (see Custom Data Source).

  • where – Where should the code be injected?

    • Beginnging – the beginning of the method (default).

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

    • End – the end of the method.

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

<shelfLifeCheck> Section

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 supports the following attributes:

  • action – The name of a method as the action to take, optional (see Specifying Sources and Actions). The method must accept a Token argument and return void. (default: the default action as described in ShelfLifeCheck)

  • sendMessage – Should a message be sent to PreEmptive Analytics? (default: false)

  • customDataSource – The optional source of custom data to be sent with the message (see Custom Data Source).

  • where – Where should the code be injected?

    • Beginnging – the beginning of the method (default).

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

    • End – the end of the method.

  • 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 run-time 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.

<shelfLifeCheck action="customShelfLifeAction()" sendMessage="true"
        where="End" customDataSource="getLicensingDetails()"
        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>

<locations> Section

All the checks and responses require locations to be set. The locations tag requires <classes> as its children.

Specifying Sources and Actions

Several annotations, checks, and responses specify sources or actions for dynamic information that will be used with the generated information. These 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. 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.

Note:

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. Make sure the fields are the expected type as required by the annotation. Make sure the methods have the expected return type and parameters as required by the annotation.
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.

Custom Data Source

When defining the customDataSource of an injected event or message, the value must be the name of a java.util.Properties field or a no-argument method which returns an instance of java.util.Properties. By default all properties are strings and interpreted and collated as strings by the server. Any type of object may be placed in the properties and they are converted to strings using the object's toString() method. Numeric values can be sent to the server by using java.lang.Number for example:

Properties properties = new Properties();
String theName = "My Name";
int theCount = 42;
// This property is a string
properties.setProperty("name", theName);
// This property is also a string
properties.setProperty("countString", Integer.toString(theCount));
// This property is a number
properties.put("countNumber", new Integer(theCount));
// This property is a string and uses MyObj.toString()
properties.put("myObject", new MyObj());

<includelist> and <excludelist> Rules

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

For tags 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> section 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> Tag

The <classes> tag 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> tag selects a class in order to specify additional rules for selecting fields and methods. If the tag does not contain any <field> or <method> tags, 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 tags 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> Tag

<method> tags are used inside the <classes> tag. Methods may be selected by name and signature. The setting for the <method>’s regex is inherited from the <classes> tag: 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> Tag

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

The <field> tag is not applicable to all include or exclude lists as the actions of some options only apply to methods. Please consult the individual tags that use include or exclude lists to see if the <field> tag 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> tag can contain multiple <method> and <field> tags 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> tags 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 tag.

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:

* ** long,* long,**
()
(int)
(java.lang.String)
(long,int)
(long,boolean,int)

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

PreEmptive Protection - DashO Version 8.1.0. Copyright © 2017 PreEmptive Solutions, LLC