# API Use Patterns Wizard

This wizard helps guide you through creating regular expression patterns for controlling an API Use analysis.

To activate the wizard use the following steps:

1. While creating a new API Use Report launch configuration, switch to the Patterns tab.
2. On the tab press the Add... button

Option | Description | Default
--- | --- | ---
Pattern Types | This listing shows all of the patterns that can be created with the wizard. | First element in list
Description | Shows the human-readable description of the pattern kind selected in the Pattern Types listing. |

The first page of the wizard allows you to select what kind of pattern you would like to create. Descriptions for each pattern are given to help you choose - simply select the pattern and the description is displayed in the Description field.

### Archive Patterns

When API use analysis is done all folders and archives within a bundle are scanned; ensuring all class files are analyzed. In some cases a bundle may contain an archive with old versions of class files (for example) that you do not want to be analyzed. In this case an archive pattern can be used to completely ignore a specific archive or all archives matching a given regular expression.

Option | Description | Default
--- | --- | ---
Bundle Name | The complete symbolic name of the bundle to apply this pattern to. For example: `org.eclipse.pde.api.tools`. | empty
Archive Name | The complete name or regular expression of the archive(s) to apply the pattern to. For example: `*.jar` - which will ignore any nested jar file. | empty

### Package Patterns

When extracting references for analysis, the API Use search engine uses meta-data from the bundle to determine if a reference is internal or not. In some cases a bundle has not been set up to properly describe what classes are internal and which are not. A Package Pattern allows you to augment these malformed bundles - only from the search engine point of view, the actual bundle is not changed in any way - to describe what is or is not internal.

Option | Description | Default
--- | --- | ---
Pattern | The regular expression pattern to match packages against. For example: `.*\.internal\..*`. | empty
API Pattern | If the pattern should make matching packages be considered as API or not. | checked

### Report Conversion Patterns

When an API use analysis is complete, there can be an immense amount of information to look through. With a report conversion pattern though you can cut down on the reference information presented in the HTML reports to only see what you are interested in. To do so you can create exclusion patterns used to prune the references that are reported.

Option | Description | Default
--- | --- | ---
Filter references to this pattern | Allows you to ignore reporting references to the pattern. For example if the pattern was `org\.eclipse\.jdt\..*`, selecting this option would not report any references made to JDT. | selected
Filter references from this pattern | Allows you to ignore reporting references to the pattern. For example if the pattern was `org\.eclipse\.jdt\..*`, selecting this option would not report any references from JDT. |
Pattern | The regular expression pattern. | empty

Setting up API Tools

API Tools Setup Action
PDE Tools Menu
API Use Reports