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 @@
+<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>
+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>
+  <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
+  </li>
+  <li><a href="">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="">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>