| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> |
| <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> |
| <meta name="ProgId" content="FrontPage.Editor.Document"> |
| <title>Checking for internal references Requirements</title> |
| </head> |
| |
| <body> |
| |
| <h1> |
| Requirements for A Tool for Checking API Usage in Eclipse-based Components</h1> |
| <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> |
| <h2>1. The Problem</h2> |
| <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> |
| <h2>2. General Requirements</h2> |
| <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> |
| <h2>References</h2> |
| <ul> |
| <li><a href="http://eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.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<br> |
| </a>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> |