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