Initial commit of API tools design documents and schema.
diff --git a/archive/working/apitools/api-usage-checking.html b/archive/working/apitools/api-usage-checking.html
new file mode 100644
index 0000000..fe54396
--- /dev/null
+++ b/archive/working/apitools/api-usage-checking.html
@@ -0,0 +1,159 @@
+<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>