releng.wtpbuilder/tools/apitools/api-usage-checking.html - webtools/webtools.releng - Gitiles

 <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 &quot;platforms&quot; (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 &quot;component&quot; 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&nbsp; 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>&nbsp;<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 &quot;platform&quot; 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 &quot;Internal&quot; 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>
	<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>