| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| |
| <head> |
| <title>Checking for internal references Requirements</title> |
| <link |
| rel="stylesheet" |
| type="text/css" |
| href="sources/formate.css"> |
| |
| </head> |
| |
| <body> |
| |
| <p class="ueberschrift">Requirements for A Tool for Checking API Usage |
| in Eclipse-based Components</p> |
| <p>Jim des Rivieres<br> |
| |
| Last updated Dec. 10, 2004</p> |
| <p>This document lists the general requirements for a tool for checking |
| API usage in Eclipse-based components and products.</p> |
| <p class="ueberschrift">1. The Problem</p> |
| <p>The context is the same as the current API Usage Scanner tool. That |
| is, we need a tool for checking Eclipse-based products that will help in |
| identifying inappropriate use of APIs and non-APIs. We want tools to be |
| able to check Eclipse-based plug-ins and products for obvious cases of |
| where plug-ins are not playing by the rules. The open-ended, |
| heterougeous, and heavily componentized nature of Eclipse are what make |
| it somewhat different from checking more monolithic applications.</p> |
| <p>Eclipse is based on the notion of a plug-in. Products end up being a |
| collection of plug-ins, collected from diverse development efforts |
| spanning open source projects, multiple IBM teams, and third-party tool |
| vendors. Set of these plug-ins are often bundled into various |
| "platforms" (e.g., Eclipse Platform, IBM Eclipse SDK), and |
| assembled into product stacks or families (IBM RAD, WBIT). |
| Component-based software is easier to develop, maintain, and evolve when |
| the inter-component coupling is well understood and well managed. This |
| is done by having each component offer its services through a |
| well-defined API that serves are the sole interface between it and other |
| components. To the extent that all inter-component coupling abides by |
| the contracts spelled out in the API specifications, replacing one |
| component by a different version supporting the same API contracts will |
| work the same way. Moreover, component APIs can be evolved in compatible |
| ways to meet changing requirements, without invalidating previously |
| working configurations. However, when inter-component coupling does not |
| follow the terms of the API contracts, replacing a component by a |
| different version supporting the same API contracts may break some |
| previously-working configurations. This is a destabilizing factor that |
| decreases robustness, increases maintenance costs, and inhibits |
| component growth.</p> |
| <p>In component-based software, the premium is on all inter-component |
| coupling being through the components API and in accord with all API |
| contracts. Although the Java language has some features for controlling |
| visibility that are enforced at compile-time (e.g., private fields and |
| methods cannot be referenced from outside the code of the class itself), |
| there are many constraints restrictions that the Java language cannot |
| express (e.g., that a particular public class is internal rather than |
| API, or that a particular interface must not be implemented outside its |
| own component). Detection of inappropriate inter-component coupling is |
| most useful when the component is under development; after a problematic |
| component has shipped in a product, the information can at least be |
| useful in managing the problem (although not solving it).</p> |
| |
| <p>The problem we are addressing is helping development teams to manage |
| inter-component coupling in Eclipse-based components. In particular, we |
| aim to do this by providing an automatic tool that can detect obvious |
| cases where one component is more tightly coupled to another component |
| that it should be.</p> |
| <p class="ueberschrift">2. General Requirements</p> |
| <p>The tool should meet the following general requirements:</p> |
| <ol> |
| <li><b>Tool will be used for checking Eclipse components.<br> |
| </b>The notion of a "component" in Eclipse is not formally |
| defined. Rather, a component is a loosely-defined grouping of a small |
| number of plug-ins and/or plug-in fragments that are designed and |
| maintained as a unit, generally by a small team of developers. For |
| instance, the Eclipse Platform itself is made of a number of |
| components each with between 1 and 5 plug-ins. The Java code for each |
| plug-in is housed in one or more JARs (this relationship is formalized |
| and captured in the plug-in's mainfest). Whereas coupling within a |
| component in intended to be tight/intimate, all coupling between |
| components is intended to be mediated through well-defined Java-based |
| APIs. The primary use of the tool will be used for checking |
| collections of Eclipse components to see whether the inter-component |
| couplings are in line with the component APIs. the Java code in the |
| various plug-ins.</li> |
| <li><b>Helpful to component developers.<br> |
| |
| </b>Component developers (and development teams) are the primary |
| customers of this tool. The tool should be designed to meet their |
| needs. Their main need for such a tool is helping manage |
| inter-component dependencies to ensure that they do not accidentally |
| exceed the bounds of the component APIs. Early detection of problems |
| means they can be addressed while the component is still under |
| development. So the tool should detect and report cases of <i>illegitimate</i> |
| couplings from component A to component B are not covered by B's API, |
| the most common mistake being A referencing one of B's internal |
| classes. A secondary need is to detect and report <i>legitimate</i> |
| API couplings components, as an aid for planning and impact |
| assessment.</li> |
| <li><b>Modular, component-based input.<br> |
| </b>Eclipse components to be checked will be fed to the tool. Since |
| the notion of component and API are not formally specified in Eclipse, |
| the tool will also need to be fed some a description of each component |
| capturing things like the set of plug-ins that comprise the component, |
| and the rules for separating component API from component internals |
| and for distinguishing legitimate from illegitimate API usage. |
| Component owners should create and maintain the component descriptions |
| for their individual components (although it should also be easy to |
| furnish an after-market component description for a component |
| that does not come with its own). Each component description should be |
| in a file that the component owner can easily maintain. Component |
| description files should be in a well-specified XML-based format so |
| that they could be read or generated by other tools. A set of relevant |
| component description files would be fed to the tool whenever checking |
| components.</li> |
| |
| <li><b>Performant and scalable.</b> <br> |
| The tool should be amenable to checking large numbers of Eclipse |
| components. We already have instances for Eclipse-based products with |
| 1500 plug-ins. The tool should make it easy to check anything from a |
| single component, to a group of components that form a |
| "platform" of some ilk, to an entire product distribution. |
| The components may be a heterogeneous mix of product-specific, open |
| source, or third party. The tool should deal gracefully with |
| incompleteness, so that it is possible to check a component without |
| necessarily having complete information about other components. The |
| tool should be reasonably fast, with speed proportional to the number |
| of components being checked.</li> |
| <li><b>Modular, component-based output.<br> |
| </b>The tool should produce modular, component-based reports. The |
| outputs should be in a well-specified XML-based format so that they |
| could be post-processed for populating databases, generating web |
| pages, printing reports, etc.</li> |
| <li><b>Fully-automatic operation.</b><br> |
| |
| The tool should be suitable for inclusion in automated build processes |
| that build the components, or repackage components into larger |
| aggregations. In other words, something without a GUI that can be run |
| from the command line, or from an Ant build file.</li> |
| <li><b>Open source.</b><br> |
| The tool itself should be open source, so that it can be used by |
| development teams working on open source Eclipse components, which |
| includes those at eclipse.org.</li> |
| </ol> |
| <p class="ueberschrift">References</p> |
| <ul> |
| <li><a href="how_to_use_api.html">How to Use the Eclipse API<br> |
| </a>This is a good example of the ways some Eclipse-based components |
| separate API from internals at the Java package level, and of the |
| kinds of blanket API usage rules that are out there. Note that these |
| rules apply only to the components in the Eclipse Platform itself; |
| other Eclipse-based components will have their own rules and |
| practices.</li> |
| |
| <li><a |
| href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/jdt-core-home/tools/internal/index.html">JDT |
| Core "Internal" tool</a><br> |
| This simple tool is used for locating references to internal types in |
| Eclipse-based distributions. It has many of the right characteristics, |
| but is overly simplistic in assuming that 1 plug-in = 1 component and |
| that all components separate API from internal based on Eclipse's |
| package-level naming conventions.</li> |
| </ul> |
| |
| </body> |
| |
| </html> |