Many pages in the PreEmptive Protection™ DashO™ user interface are rules editors. Use them to include or exclude parts of your application from a protection, such as Renaming or String Encryption. Rules let you protect as much of your code as possible while keeping the parts that must stay unchanged working correctly.
Prerequisites
- A DashO project with inputs, so the class list shows your classes and members.
Pages That Use the Rules Editor
- Global Processing Exclusions
- Renaming - Exclude
- Removal - Classes
- Removal - Exclude
- Method Call Removal
- Control Flow - Include and Exclude
- String Encryption - Include and Exclude
- Custom String Encryption
- Resource Encryption - Include and Exclude
- Make Synthetic - Exclude
- Optimization - Include and Exclude
Other parts of DashO, such as entry points, use an interface very similar to the rules editor.
Create Rules
Create a Rule from the Class List
Use this method to match a specific item you can see in your inputs.
- In the class list, find the class, method, field, or annotation you want the rule to match.
- Create the rule in one of these ways:
- Right-click the item and use the context menu to build a rule that matches it. To make the rule a regular expression, hold down Shift when you create it.
- Drag the item from the class list and drop it on the rule list.
When you create a rule this way:
- For a method or field, DashO adds the rule to an existing class rule, or creates a class rule if needed.
- For an annotation you drag onto the rule list, DashO creates the rule and opens the rule dialog automatically.
Create a Rule from Scratch
Use this method to write a rule that matches items by name, pattern, annotation, supertype, or modifier.
- Click one of the New buttons to the right of the rule list, or right-click the rule list and choose a New item from the context menu. Button labels depend on the page. For example, the Entry Points - Methods and Fields page has New Class, New Methods, and New Fields.
DashO opens the rule dialog so you can enter all the rule's settings. -
Enter the Rule Dialog settings.
Setting Description Type Determines whether DashO interprets Name, Annotations, and Supertypes as regular expressions. Choose Text/Pattern or Regular Expression. Method and field rules inherit this setting. Name An expression DashO tests against each class name to decide whether the rule applies. Annotations The Java annotations an item must have to match. See the Annotations attribute for valid values. Supertypes The superclasses, extended interfaces, or implemented interfaces a class must have to match. See the Supertype attribute for valid values. Modifiers The Java modifiers, or their negation, an item must have to match. See the Modifiers attribute for valid values. Selects Class For rules that affect a class and its members. When selected, the rule applies to the class itself. When cleared, the class is only a container for its nested method and field rules. - Click OK.
- Save your project and build it to apply the changes.
Edit Rules
To change a rule's name, or a method's signature, edit it in the text field directly below the rule list. Some specialized editors also let you edit their values directly in the list.
To change all of a rule's settings, open its dialog in one of these ways:
- Right-click the rule and select Edit....
- Double-click the rule.
- Select the rule and press Enter.
- Select the rule and click Edit....
To remove a rule, right-click it and select Delete.
Save your project and build it to apply your changes.
Other Editors
These pages use the same list-based interface, with their own dialog settings:
| Editor | Setting | Description |
|---|---|---|
| User Properties | Property | The name of the property to create or assign a value to. |
| Value | The value to assign to the property. | |
| Input — Included Non-Class Files | Source | The path to the non-class file. |
| Destination | The output destination for the file. | |
| Resource Encryption | Type | Determines whether DashO interprets Name as a regular expression. See Patterns and Regular Expressions. |
| Name | An expression DashO tests against each raw resource or asset name. |
Preview Rules
Check which items your rules match before you build.
- Right-click a rule.
- Select Preview Rule to preview that rule, or Preview All to preview every rule.
DashO shows the matched items in bold in the class list. - To clear the highlighting, right-click either list and select the clear option.
Patterns and Regular Expressions
The Type setting controls how DashO reads Name, Signature, Annotations, and Supertypes:
| Type and value | How DashO matches it |
|---|---|
| Text/Pattern, no wildcard characters | As a literal value, matched exactly. For example, a class rule Name of com.example.TimeStream matches only the class named exactly com.example.TimeStream. |
| Text/Pattern, with wildcard characters | As a pattern, which can match multiple items. |
| Regular Expression | As a regular expression, which can match multiple items. |
For syntax details, see Patterns and Regular Expressions in the project file reference.
How Include and Exclude Rules Combine
When a protection supports both include and exclude rules, DashO combines them as follows:
| Rules defined | Result |
|---|---|
| No include rules | DashO includes all items by default. |
| No exclude rules | DashO excludes nothing by default. |
| Both include and exclude rules match an item | The exclude rule wins. Exclude rules always override include rules. |
Limitations and Troubleshooting
| Issue | Resolution |
|---|---|
| A red X appears next to a rule. | The regular expression has an error. Point to the rule to see the error's location and description. |
| Type is unavailable in a method or field rule dialog. | Method and field rules inherit Type from their class rule. Change it in the Class Rule dialog. |
| A rule matches more or fewer items than expected. | Preview the rule. Check whether its value is a literal, a pattern, or a regular expression, and whether Selects Class is set correctly. |
| An item isn't processed even though an include rule matches it. | Check for an exclude rule that matches it. Exclude rules always override include rules. |