| lmandel | 554d491 | 2005-11-22 07:46:33 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| 2 | "http://www.w3.org/TR/html4/loose.dtd"> |
| 3 | <html> |
| 4 | |
| 5 | <head> |
| 6 | <title>Checking for internal references Requirements</title> |
| 7 | <link |
| 8 | rel="stylesheet" |
| 9 | type="text/css" |
| 10 | href="sources/formate.css"> |
| 11 | |
| 12 | </head> |
| 13 | |
| 14 | <body> |
| 15 | |
| 16 | <p class="ueberschrift">Requirements for A Tool for Checking API Usage |
| 17 | in Eclipse-based Components</p> |
| 18 | <p>Jim des Rivieres<br> |
| 19 | |
| 20 | Last updated Dec. 10, 2004</p> |
| 21 | <p>This document lists the general requirements for a tool for checking |
| 22 | API usage in Eclipse-based components and products.</p> |
| 23 | <p class="ueberschrift">1. The Problem</p> |
| 24 | <p>The context is the same as the current API Usage Scanner tool. That |
| 25 | is, we need a tool for checking Eclipse-based products that will help in |
| 26 | identifying inappropriate use of APIs and non-APIs. We want tools to be |
| 27 | able to check Eclipse-based plug-ins and products for obvious cases of |
| 28 | where plug-ins are not playing by the rules. The open-ended, |
| 29 | heterougeous, and heavily componentized nature of Eclipse are what make |
| 30 | it somewhat different from checking more monolithic applications.</p> |
| 31 | <p>Eclipse is based on the notion of a plug-in. Products end up being a |
| 32 | collection of plug-ins, collected from diverse development efforts |
| 33 | spanning open source projects, multiple IBM teams, and third-party tool |
| 34 | vendors. Set of these plug-ins are often bundled into various |
| 35 | "platforms" (e.g., Eclipse Platform, IBM Eclipse SDK), and |
| 36 | assembled into product stacks or families (IBM RAD, WBIT). |
| 37 | Component-based software is easier to develop, maintain, and evolve when |
| 38 | the inter-component coupling is well understood and well managed. This |
| 39 | is done by having each component offer its services through a |
| 40 | well-defined API that serves are the sole interface between it and other |
| 41 | components. To the extent that all inter-component coupling abides by |
| 42 | the contracts spelled out in the API specifications, replacing one |
| 43 | component by a different version supporting the same API contracts will |
| 44 | work the same way. Moreover, component APIs can be evolved in compatible |
| 45 | ways to meet changing requirements, without invalidating previously |
| 46 | working configurations. However, when inter-component coupling does not |
| 47 | follow the terms of the API contracts, replacing a component by a |
| 48 | different version supporting the same API contracts may break some |
| 49 | previously-working configurations. This is a destabilizing factor that |
| 50 | decreases robustness, increases maintenance costs, and inhibits |
| 51 | component growth.</p> |
| 52 | <p>In component-based software, the premium is on all inter-component |
| 53 | coupling being through the components API and in accord with all API |
| 54 | contracts. Although the Java language has some features for controlling |
| 55 | visibility that are enforced at compile-time (e.g., private fields and |
| 56 | methods cannot be referenced from outside the code of the class itself), |
| 57 | there are many constraints restrictions that the Java language cannot |
| 58 | express (e.g., that a particular public class is internal rather than |
| 59 | API, or that a particular interface must not be implemented outside its |
| 60 | own component). Detection of inappropriate inter-component coupling is |
| 61 | most useful when the component is under development; after a problematic |
| 62 | component has shipped in a product, the information can at least be |
| 63 | useful in managing the problem (although not solving it).</p> |
| 64 | |
| 65 | <p>The problem we are addressing is helping development teams to manage |
| 66 | inter-component coupling in Eclipse-based components. In particular, we |
| 67 | aim to do this by providing an automatic tool that can detect obvious |
| 68 | cases where one component is more tightly coupled to another component |
| 69 | that it should be.</p> |
| 70 | <p class="ueberschrift">2. General Requirements</p> |
| 71 | <p>The tool should meet the following general requirements:</p> |
| 72 | <ol> |
| 73 | <li><b>Tool will be used for checking Eclipse components.<br> |
| 74 | </b>The notion of a "component" in Eclipse is not formally |
| 75 | defined. Rather, a component is a loosely-defined grouping of a small |
| 76 | number of plug-ins and/or plug-in fragments that are designed and |
| 77 | maintained as a unit, generally by a small team of developers. For |
| 78 | instance, the Eclipse Platform itself is made of a number of |
| 79 | components each with between 1 and 5 plug-ins. The Java code for each |
| 80 | plug-in is housed in one or more JARs (this relationship is formalized |
| 81 | and captured in the plug-in's mainfest). Whereas coupling within a |
| 82 | component in intended to be tight/intimate, all coupling between |
| 83 | components is intended to be mediated through well-defined Java-based |
| 84 | APIs. The primary use of the tool will be used for checking |
| 85 | collections of Eclipse components to see whether the inter-component |
| 86 | couplings are in line with the component APIs. the Java code in the |
| 87 | various plug-ins.</li> |
| 88 | <li><b>Helpful to component developers.<br> |
| 89 | |
| 90 | </b>Component developers (and development teams) are the primary |
| 91 | customers of this tool. The tool should be designed to meet their |
| 92 | needs. Their main need for such a tool is helping manage |
| 93 | inter-component dependencies to ensure that they do not accidentally |
| 94 | exceed the bounds of the component APIs. Early detection of problems |
| 95 | means they can be addressed while the component is still under |
| 96 | development. So the tool should detect and report cases of <i>illegitimate</i> |
| 97 | couplings from component A to component B are not covered by B's API, |
| 98 | the most common mistake being A referencing one of B's internal |
| 99 | classes. A secondary need is to detect and report <i>legitimate</i> |
| 100 | API couplings components, as an aid for planning and impact |
| 101 | assessment.</li> |
| 102 | <li><b>Modular, component-based input.<br> |
| 103 | </b>Eclipse components to be checked will be fed to the tool. Since |
| 104 | the notion of component and API are not formally specified in Eclipse, |
| 105 | the tool will also need to be fed some a description of each component |
| 106 | capturing things like the set of plug-ins that comprise the component, |
| 107 | and the rules for separating component API from component internals |
| 108 | and for distinguishing legitimate from illegitimate API usage. |
| 109 | Component owners should create and maintain the component descriptions |
| 110 | for their individual components (although it should also be easy to |
| 111 | furnish an after-market component description for a component |
| 112 | that does not come with its own). Each component description should be |
| 113 | in a file that the component owner can easily maintain. Component |
| 114 | description files should be in a well-specified XML-based format so |
| 115 | that they could be read or generated by other tools. A set of relevant |
| 116 | component description files would be fed to the tool whenever checking |
| 117 | components.</li> |
| 118 | |
| 119 | <li><b>Performant and scalable.</b> <br> |
| 120 | The tool should be amenable to checking large numbers of Eclipse |
| 121 | components. We already have instances for Eclipse-based products with |
| 122 | 1500 plug-ins. The tool should make it easy to check anything from a |
| 123 | single component, to a group of components that form a |
| 124 | "platform" of some ilk, to an entire product distribution. |
| 125 | The components may be a heterogeneous mix of product-specific, open |
| 126 | source, or third party. The tool should deal gracefully with |
| 127 | incompleteness, so that it is possible to check a component without |
| 128 | necessarily having complete information about other components. The |
| 129 | tool should be reasonably fast, with speed proportional to the number |
| 130 | of components being checked.</li> |
| 131 | <li><b>Modular, component-based output.<br> |
| 132 | </b>The tool should produce modular, component-based reports. The |
| 133 | outputs should be in a well-specified XML-based format so that they |
| 134 | could be post-processed for populating databases, generating web |
| 135 | pages, printing reports, etc.</li> |
| 136 | <li><b>Fully-automatic operation.</b><br> |
| 137 | |
| 138 | The tool should be suitable for inclusion in automated build processes |
| 139 | that build the components, or repackage components into larger |
| 140 | aggregations. In other words, something without a GUI that can be run |
| 141 | from the command line, or from an Ant build file.</li> |
| 142 | <li><b>Open source.</b><br> |
| 143 | The tool itself should be open source, so that it can be used by |
| 144 | development teams working on open source Eclipse components, which |
| 145 | includes those at eclipse.org.</li> |
| 146 | </ol> |
| 147 | <p class="ueberschrift">References</p> |
| 148 | <ul> |
| 149 | <li><a href="how_to_use_api.html">How to Use the Eclipse API<br> |
| 150 | </a>This is a good example of the ways some Eclipse-based components |
| 151 | separate API from internals at the Java package level, and of the |
| 152 | kinds of blanket API usage rules that are out there. Note that these |
| 153 | rules apply only to the components in the Eclipse Platform itself; |
| 154 | other Eclipse-based components will have their own rules and |
| 155 | practices.</li> |
| 156 | |
| 157 | <li><a |
| 158 | href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/jdt-core-home/tools/internal/index.html">JDT |
| 159 | Core "Internal" tool</a><br> |
| 160 | This simple tool is used for locating references to internal types in |
| 161 | Eclipse-based distributions. It has many of the right characteristics, |
| 162 | but is overly simplistic in assuming that 1 plug-in = 1 component and |
| 163 | that all components separate API from internal based on Eclipse's |
| 164 | package-level naming conventions.</li> |
| 165 | </ul> |
| 166 | |
| 167 | </body> |
| 168 | |
| 169 | </html> |