| <html> |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link rel="stylesheet" href="../../../default_style.css" type="text/css"> |
| <link rel="stylesheet" href="../../../webtools/wtp.css" type="text/css"> |
| <title>Eclipse API Scanner</title> |
| </head> |
| <body> |
| <table width="100%" cellspacing="5" cellpadding="2" border="0"> |
| <tbody> |
| <tr> |
| <td width="60%" align="left"><font class="indextop">Eclipse API Scanner</font> |
| <br> |
| <font class="indexsub">Eclipse API Scanner</font></td><td width="40%"><img width="120" hspace="50" height="86" align="middle" src="../../../images/Idea.jpg"></td> |
| </tr> |
| </tbody> |
| </table> |
| <table width="100%" cellspacing="5" cellpadding="2" border="0"> |
| <col width="16"> |
| <col width="*"> |
| <tbody> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"><em>Updated 2005-02-07</em></td> |
| </tr> |
| <tr> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">Introduction</font></b></td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| This document summarizes the usage of the Eclipse API scanner. |
| The goal of the Eclipse API scanner is to identify any internal API references in |
| any Eclipse-based products. You can view the requirements document |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.wtp.releng/apitools/api-usage-checking.html?rev=HEAD&cvsroot=WebTools_Project&content-type=text/html">here</a>, and the design document |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.wtp.releng/apitools/api-usage-checking-design.html?rev=HEAD&cvsroot=WebTools_Project&content-type=text/html">here</a>. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p></p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">Downloading and running the Eclipse API scanner</font></b></td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| A binary version of the Eclipse API scanner is available here: |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| |
| <a href="http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/apiscanner.zip">Download the Eclipse API scanner</a>. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The source of the Eclipse API scanner is also available in |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/?cvsroot=WebTools_Project">CVS</a>. |
| Check out the <b>org.eclipse.wtp.releng.tools.component.core</b> project and the |
| <b>org.eclipse.wtp.releng.tools.component.ui</b> project. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../images/Adarrow.gif"></td><td>Running the Eclipse API scanner from the command line environment</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Before running the Eclipse API scanner, you should get yourself familiar with what is a |
| component. For a definition of component, visit the |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.wtp.releng/apitools/api-usage-checking-design.html?rev=HEAD&cvsroot=WebTools_Project&content-type=text/html">design document</a>. |
| To begin, have your Eclipse components/plug-ins and your component.xml files ready. |
| The Eclipse API scanner will scan all the API references in each component and check whether |
| they are internal API references. An API violation report will be generated for each component. |
| To generate the API violation reports, run: |
| <pre> |
| genViolation.bat -eclipseDir <eclipseDir> -compXMLDir <compXMLDir> -compRefDir <compRefDir> -compVioDir <compVioDir> -genHTML -debug |
| </pre> |
| where: |
| <ul> |
| |
| <li> |
| <b>eclipseDir</b> - a space separated list of directories containing the plug-ins |
| for your product. These directories do not have to include the base Eclipse plug-ins |
| (ex: org.eclipse.jdt.core). You only need the plug-ins that you want to generate API |
| violation reports for.</li> |
| |
| <li> |
| <b>compXMLDir</b> - a space separated list of directories containing component.xml |
| files for your product. The Eclipse API scanner will generate an API violation report for each component.xml |
| found in these directories. So, if you do not want to generate violation reports for the |
| Eclipse components (ex: org.eclipse.jdt.core), do not include their component.xml files here.</li> |
| |
| <li> |
| <b>compRefDir</b> - a space separated list of directories containing component.xml |
| files that your product/components depend on. For example, the component.xml files |
| for org.eclipse.jdt.core goes here.</li> |
| |
| <li> |
| <b>compVioDir</b> - the output directory of the API violation reports.</li> |
| |
| <li> |
| <b>genHTML</b> - generates the API violation report in HTML (default is XML format).</li> |
| |
| <li> |
| <b>debug</b> - generates debug information (ex: line numbers).</li> |
| |
| </ul> |
| For a list of all the options available, simply run genViolation.bat without any arguments. |
| Note that genViolation.bat uses relative paths. Therefore, if you want to run it |
| out-of-the-box, we must "cd" to genViolation.bat's directory before running it. Other |
| options include: |
| <ul> |
| |
| <li> |
| <b>include</b> - a space separated list of package names to be included in the scan.</li> |
| |
| <li> |
| <b>exclude</b> - a space separated list of package names to be excluded in the scan. |
| For example, if you specify "java.lang. sun.", then the API violation report will not include |
| internal API references to those two packages.</li> |
| |
| <li> |
| <b>genAPI</b> - generates a component-api.xml file per component. This file lists all |
| the public APIs that a component has.</li> |
| |
| <li> |
| <b>genUsage</b> - generates a component-use.xml file per component. This file lists all |
| the API references that a component has.</li> |
| |
| <li> |
| <b>classRefOnly</b> - treats all API references as class reference. By default, |
| the Eclipse API scanner will categorize API references into different categories such |
| as class references, method references, field references and etc. By specifying this |
| option, all API references are consider class references. This speeds up the scanning |
| process.</li> |
| |
| </ul> |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| To get you started more quickly, you can use <b>genComponent.bat</b> to generate a component.xml |
| file per plugin. Any packages with the word "internal" in it will be excluded from the generated |
| component.xml file. To generate default component.xml files, run: |
| <pre> |
| genComponent.bat -eclipseDir <eclipseDir> -compXMLDir <compXMLDir> |
| </pre> |
| where: |
| <ul> |
| |
| <li> |
| <b>eclipseDir</b> - a space separated list of directories containing the plug-ins |
| for your product. Again, do not include base Eclipse plug-ins in here.</li> |
| |
| <li> |
| <b>compXMLDir</b> - the output directory of the generated component.xml files.</li> |
| |
| </ul> |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../images/Adarrow.gif"></td><td>Running the Eclipse API scanner within Eclipse</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The Eclipse API scanner is also available as two Eclipse plug-ins. Therefore, you can overlay |
| them on top of an Eclipse driver and use them to check API violations as you develop your |
| product/plug-ins. To get these plug-ins, go to: |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/?cvsroot=WebTools_Project">http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/?cvsroot=WebTools_Project</a> |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| and check out the <b>org.eclipse.wtp.releng.tools.component.core</b> project and the |
| <b>org.eclipse.wtp.releng.tools.component.ui</b> project. They provide an |
| editor for editing component.xml files. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| <img src="./figure01.gif"></p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| They will also scan the plug-ins in your workspace and generate API violations in the problems |
| views. The figure below shows a plug-in in my workspace called <b>org.eclipse.sample</b>. |
| I have also created a component.xml file for this plugin. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| <img src="./figure02.gif"></p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| In the next figure, I have added a reference to one of the Eclipse internal class. The |
| Eclipse API scanner will flag this as an API violation and display it in the problems |
| view. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| <img src="./figure03.gif"></p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| You can find some sample component.xml files |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/components/?cvsroot=WebTools_Project">here</a>. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| |
| <b>Disclaimer:</b> these sample component.xml files are provided as an example only. They |
| <b>DO NOT</b> reflect the actual APIs provided by the Eclipse projects. |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </body> |
| </html> |