blob: 771a98be90535f1f31f7852f7108cad5d0e78b8f [file] [log] [blame]
lmandel554d4912005-11-22 07:46:33 +00001<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
6<title>Checking for internal references Requirements</title>
8 rel="stylesheet"
9 type="text/css"
10 href="sources/formate.css">
16<p class="ueberschrift">Requirements for A Tool for Checking API Usage
17in Eclipse-based Components</p>
18<p>Jim des Rivieres<br>
20Last updated Dec. 10, 2004</p>
21<p>This document lists the general requirements for a tool for checking
22API 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
25is, we need a tool for checking Eclipse-based products that will help in
26identifying inappropriate use of APIs and non-APIs. We want tools to be
27able to check Eclipse-based plug-ins and products for obvious cases of
28where plug-ins are not playing by the rules. The open-ended,
29heterougeous, and heavily componentized nature of Eclipse are what make
30it 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
32collection of plug-ins, collected from diverse development efforts
33spanning open source projects, multiple IBM teams, and third-party tool
34vendors. Set of these plug-ins are often bundled into various
35&quot;platforms&quot; (e.g., Eclipse Platform, IBM Eclipse SDK), and
36assembled into product stacks or families (IBM RAD, WBIT).
37Component-based software is easier to develop, maintain, and evolve when
38the inter-component coupling is well understood and well managed. This
39is done by having each component offer its services through a
40well-defined API that serves are the sole interface between it and other
41components. To the extent that all inter-component coupling abides by
42the contracts spelled out in the API specifications, replacing one
43component by a different version supporting the same API contracts will
44work the same way. Moreover, component APIs can be evolved in compatible
45ways to meet changing requirements, without invalidating previously
46working configurations. However, when inter-component coupling does not
47follow the terms of the API contracts, replacing a component by a
48different version supporting the same API contracts may break some
49previously-working configurations. This is a destabilizing factor that
50decreases robustness, increases maintenance costs, and inhibits
51component growth.</p>
52<p>In component-based software, the premium is on all inter-component
53coupling being through the components API and in accord with all API
54contracts. Although the Java language has some features for controlling
55visibility that are enforced at compile-time (e.g., private fields and
56methods cannot be referenced from outside the code of the class itself),
57there are many constraints restrictions that the Java language cannot
58express (e.g., that a particular public class is internal rather than
59API, or that a particular interface must not be implemented outside its
60own component). Detection of inappropriate inter-component coupling is
61most useful when the component is under development; after a problematic
62component has shipped in a product, the information can at least be
63useful in managing the problem (although not solving it).</p>
65<p>The problem we are addressing is helping development teams to manage
66inter-component coupling in Eclipse-based components. In particular, we
67aim to do this by providing an automatic tool that can detect obvious
68cases where one component is more tightly coupled to another component
69that it should be.</p>
70<p class="ueberschrift">2. General Requirements</p>
71<p>The tool should meet the following general requirements:</p>
73 <li><b>Tool will be used for checking Eclipse components.<br>
74 </b>The notion of a &quot;component&quot; 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>
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&nbsp; 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>
119 <li><b>Performant and scalable.</b>&nbsp;<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 &quot;platform&quot; 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>
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</li>
147<p class="ueberschrift">References</p>
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>
157 <li><a
158 href="">JDT
159 Core &quot;Internal&quot; 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>