| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html lang="en"> |
| <head> |
| <meta name="copyright" |
| content="Copyright (c) IBM Corporation and others 2010, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=ISO-8859-1"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <link rel="STYLESHEET" href="../../../book.css" type="text/css"> |
| <title>API Use Patterns Wizard</title> |
| </head> |
| <body> |
| <h1>API Use Patterns Wizard</h1> |
| <p>This wizard helps guide you through creating regular expression patterns for controlling an API Use analysis.</p> |
| <p>To activate the wizard use the following steps:</p> |
| <ol> |
| <li>While creating a new API Use Report launch configuration, switch to the <strong>Patterns</strong> tab.</li> |
| <li>On the tab press the <strong>Add...</strong> button</li> |
| </ol> |
| |
| <table border="1" cellspacing="0" cellpadding= "5" width="100%"> |
| <thead> |
| <tr> |
| <th rowspan="1" colspan="1" width="20%"> <p> Option </p></th> |
| <th rowspan="1" colspan="1"> <p> Description </p></th> |
| <th rowspan="1" colspan="1" width="5%"> <p> Default </p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Pattern Types</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">This listing shows all of the patterns that can be created with the wizard.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">First element in list</td> |
| </tr> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Description</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">Shows the human-readable description of the pattern kind selected in the <strong>Pattern Types</strong> listing.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left"> </td> |
| </tr> |
| </tbody> |
| </table> |
| <p> |
| 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 <strong>Description</strong> field. |
| </p> |
| <p> |
| <img src="../images/api-use-pattern-wizard.png" alt="API Use pattern wizard - pattern selection page"> |
| </p> |
| |
| <h3>Archive Patterns</h3> |
| <p> |
| 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. |
| </p> |
| <table border="1" cellspacing="0" cellpadding= "5" width="100%"> |
| <thead> |
| <tr> |
| <th rowspan="1" colspan="1" width="20%"> <p> Option </p></th> |
| <th rowspan="1" colspan="1"> <p> Description </p></th> |
| <th rowspan="1" colspan="1" width="5%"> <p> Default </p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Bundle Name</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">The complete symbolic name of the bundle to apply this pattern to. |
| For example: <code>org.eclipse.pde.api.tools</code>.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">empty</td> |
| </tr> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Archive Name</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">The complete name or regular expression of the archive(s) to apply the pattern to. |
| For example: <code>*.jar</code> - which will ignore any nested jar file.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">empty</td> |
| </tr> |
| </tbody> |
| </table> |
| <p> |
| <img src="../images/api-use-pattern-wizard-archive-page.png" alt="API Use pattern wizard - creating archive patterns"> |
| </p> |
| |
| <h3>Package Patterns</h3> |
| <p> |
| 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 <strong>Package Pattern</strong> 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. |
| </p> |
| <table border="1" cellspacing="0" cellpadding= "5" width="100%"> |
| <thead> |
| <tr> |
| <th rowspan="1" colspan="1" width="20%"> <p> Option </p></th> |
| <th rowspan="1" colspan="1"> <p> Description </p></th> |
| <th rowspan="1" colspan="1" width="5%"> <p> Default </p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Pattern</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">The regular expression pattern to match packages against. |
| For example: <code>.*\.internal\..*</code>.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">empty</td> |
| </tr> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">API Pattern</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">If the pattern should make matching packages be considered as API or not.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">checked</td> |
| </tr> |
| </tbody> |
| </table> |
| <p> |
| <img src="../images/api-use-pattern-wizard-package-page.png" alt="API Use pattern wizard - creating package patterns"> |
| </p> |
| |
| <h3>Report Conversion Patterns</h3> |
| <p> |
| 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. |
| </p> |
| <table border="1" cellspacing="0" cellpadding= "5" width="100%"> |
| <thead> |
| <tr> |
| <th rowspan="1" colspan="1" width="20%"> <p> Option </p></th> |
| <th rowspan="1" colspan="1"> <p> Description </p></th> |
| <th rowspan="1" colspan="1" width="5%"> <p> Default </p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Filter references to this pattern</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">Allows you to ignore reporting references to the pattern. |
| For example if the pattern was <code>org\.eclipse\.jdt\..*</code>, selecting this option would not report any references made to JDT.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">selected</td> |
| </tr> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Filter references from this pattern</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">Allows you to ignore reporting references to the pattern. |
| For example if the pattern was <code>org\.eclipse\.jdt\..*</code>, selecting this option would not report any references from JDT.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left"> </td> |
| </tr> |
| <tr> |
| <td rowspan="1" colspan="1" valign="top" align="left">Pattern</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">The regular expression pattern.</td> |
| <td rowspan="1" colspan="1" valign="top" align="left">empty</td> |
| </tr> |
| </tbody> |
| </table> |
| <p> |
| <img src="../images/api-use-pattern-wizard-conversion-page.png" alt="API Use pattern wizard - creating report conversion patterns"> |
| </p> |
| |
| <h3 class="related">Related tasks</h3> |
| <a href="../../../tasks/api_tooling_setup.htm">Setting up API Tools</a> |
| |
| <h3 class="related">Related references</h3> |
| <a href="../actions/ref-apitooling-setup-action.htm">API Tools Setup Action</a><br> |
| <a href="../../actions/ref-pdetools.htm">PDE Tools Menu</a><br> |
| <a href="ref-api-use-dialog.htm">API Use Reports</a> |
| </body> |
| </html> |
