blob: fe54396fbff47883dabb63f53cbf3a5907fcd6a6 [file] [log] [blame]
jlanuti6f30d402007-04-18 19:54:42 +00001<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>
14Requirements for A Tool for Checking API Usage in Eclipse-based Components</h1>
15<p>Jim des Rivieres<br>
16Last updated Dec. 10, 2004</p>
17<p>This document lists the general requirements for a tool for checking API usage in Eclipse-based components
18and 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
21tool for checking Eclipse-based products that will help in identifying
22inappropriate use of APIs and non-APIs. We want tools to be able to check Eclipse-based plug-ins and products for
23obvious cases of where plug-ins are not playing by the rules. The open-ended,
24heterougeous, and heavily componentized nature of Eclipse are what make it
25somewhat different from checking more monolithic applications.</p>
26<p> Eclipse is based on the notion of a plug-in. Products end up being a
27collection of plug-ins, collected from diverse development efforts spanning open
28source projects, multiple IBM teams, and third-party tool vendors. Set of these
29plug-ins are often bundled into various &quot;platforms&quot; (e.g., Eclipse
30Platform, IBM Eclipse SDK), and assembled into product stacks or families (IBM
31RAD, WBIT). Component-based software is easier to develop, maintain, and evolve
32when the inter-component coupling is well understood and well managed. This is
33done by having each component offer its services through a well-defined API that
34serves are the sole interface between it and other components. To the
35 extent that all inter-component coupling abides by the contracts spelled out
36in the API specifications, replacing one component by a different version
37supporting the same API contracts will work the same way. Moreover, component
38APIs can be evolved in compatible ways to meet changing requirements, without
39invalidating 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
41API contracts may break some previously-working configurations. This is a
42 destabilizing factor that decreases robustness, increases maintenance costs,
43and 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
46the Java
47 language has some features for controlling visibility that are enforced at
48compile-time (e.g., private fields and methods cannot be referenced from
49 outside the code of the class itself), there are many constraints
50restrictions that
51 the Java language cannot express (e.g., that a particular public class is
52internal rather than API, or that a particular interface must not be implemented outside
53 its own component). Detection of inappropriate inter-component coupling is
54most useful when the component is under development; after a problematic component
55has shipped in a product, the information can at least be useful in managing the
56problem (although not solving it).</p>
57<p>The problem we are addressing is helping development teams to manage inter-component coupling
58in Eclipse-based components. In particular, we aim to do this by providing an
59automatic tool that can detect obvious cases where one component is more tightly
60coupled 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 &quot;component&quot; 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&nbsp; 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>&nbsp;<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 &quot;platform&quot; 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 &quot;Internal&quot; 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>