Overview
Many of the pages in DashO's user interface are rule editors, primarily for including and excluding elements in your application in an obfuscation transformation. A rule editor is divided into two lists – a class list on the left hand side that shows the classes and members of the inputs and a rule list on the right. The rules specify what parts of the inputs are affected by the operation and in some cases the actions to be taken. The rules editor is used to set rules on the following pages:
Other parts of DashO, such as entry points, use an interface very similar to the rule editor.
Creating Rules
There are several ways to create rules in the interface:
-
Right-click items in the class list – you can right-click on items in the class list to bring up a contextual menu. From there you can build a rule that will match the item that you have selected. If you hold down the shift key when you create the rule the rule will be made a regular expression. If you create a rule for a method or a field, DashO will add the new rule to a pre-existing class rule or create one if needed.
-
Drag and drop items from the class list – you can drag an item from the class list and drop it on the rules. If you drag and drop either a method or a field, DashO will add the new rule to a pre-existing class rule or create one if needed. If you drag an annotation associated with a class, method, or field, it will automatically bring up the editor after creating the appropriate rule.
-
Using the buttons – You can click the New buttons to the right of the rules list to create a new entry.
-
Using the contextual menu - You can click the New buttons on the contextual menu to create a new entry.
Editing Rules
The basic parts of a rule can be modified directly in the editor. The name of any item and the signature or methods can be changed by using the text field immediately below the rules list. Specialized editors may also provide for direct editing of their values.
When a rule is created using the New buttons or the contextual menu, the editor will be launched allowing you to edit all of the settings for the rule.
You have several options to access all the settings for a rule after the rule is created:
-
Right-click on the rule and select the Edit... item on the contextual menu
-
Double-click on the rule
-
Select the rule and press the Enter key
-
Select the rule and click the Edit... button
This will bring up the editor for the rule.
Java Class, Method, and Field Rule Editors
You can set some of the following values on editors for rules that match specific classes, methods, or fields; not all values are available on all rule types.
-
Type – determines whether or not values for Name, Signature, Annotations, and Supertypes will be interpreted as regular expressions. The Type setting for a method or field rule is inherited from the enclosing class rule. See Patterns and Regular Expressions for details.
-
Name – an expression tested against the name of a class, method, or field to determine if this rule should be applied to it.
-
Signature – an expression tested against the signature of a method to determine if this rule should be applied to it. Use fully-qualified names for non-primitive types and simple names (e.g.
int) for primitive types. Use[]to specify array types (e.g.java.lang.String[]). -
Annotations - the Java annotations which are required to match annotations associated with an item. See the description of the Annotations attribute for values you can use here.
-
Supertypes - the supertypes (superclasses, extended interfaces, or implemented interfaces) that a class must have in order to match this rule. See the description of the Supertype attribute for values you can use here.
-
Modifiers – the Java modifiers, or their negation, which are required for this rule to match an item. See the description of the Modifiers attribute for values you can use here.
-
Renaming controls – Entry points are non-renameable by default. Some types of entry points can be made renameable and these controls determine if the class and/or its members can be renamed.
-
Selects Class – For rules that affect the class itself as well as its members, this setting determines if the rule applies to the class, or if the class is just a container for nested field or method rules.
-
Update References - Global Processing Exclude rules allow for partial processing of classes. When selected, references to classes, methods, and fields will processed by DashO and updated, if necessary, in the excluded classes matching the rule. See the <globalProcessingExclude> element for details.
User Property Editor
You can set the following values on the editor for the User Properties page:
-
Property - the name of the property you want to create and/or assign a value to.
-
Value - the value assigned to the property.
Non-Class File Editor
You can set the following values on the editor for the Input — Included Non-Class Files page:
-
Source - the path to the non-class file.
-
Destination - the desired output destination.
Resource Encryption Item Editor
You can set the following values on editors for the Resource Encryption pages:
-
Type - determines whether or not the Name value should be interpreted as a regular expression. See Patterns and Regular Expressions for details.
-
Name - an expression tested against the name of a raw resource or an asset to determine if this rule should be applied to it.
Previewing rules
You can use the preview function to determine what will be affected by the rules. You can elect to preview a single rule or all rules. Right-click a rule to bring up the contextual menu and select Preview Rule or Preview All. The items in the class list that will be affected by the rule will be displayed in bold. You can use the contextual menu in either list to clear the highlighting.
Patterns and Regular Expressions
The Type setting for a rule indicates whether or not specific values (Name, Signature, Annotations, and Supertypes) should be interpreted as regular expressions. If the type is not set to "Regular Expression" then these values will be interpreted as literal values unless they contain special wild card characters, in which case they will be treated as patterns.
Literal values will be evaluated for exact matches. For example, if the Name for a class rule is com.example.TimeStream then the rule will only match a class with exactly the name com.example.TimeStream. A pattern or regular expression may match multiple items. See Patterns and Regular Expressions.
Regular Expressions are checked automatically. If your expression has an error a red X will be displayed next to it. Move the pointer over the rule and the tooltip will display the location of the error and its description.
Combining Include and Exclude Rules
DashO can use a combination of inclusion and exclusion to determine what parts of your application to obfuscate. When an obfuscation transformation allows for the definition of both includes and exclude it is important to remember how the two are combined:
-
Exclude rules always override any inclusions.
-
If no include rules are defined, all items are included by default.
-
If no exclude rules are defined, no items are excluded by default.
For example, usage of Global Exclude: com.example.mypackage.MyClass, and renaming it: com.example.*, will not receive any transformation. The entire package com.example will not be renamed.