initial creation of tools project
diff --git a/releng.wtptools/api/api-usage-checking-design.html b/releng.wtptools/api/api-usage-checking-design.html
new file mode 100644
index 0000000..4183a20
--- /dev/null
+++ b/releng.wtptools/api/api-usage-checking-design.html
@@ -0,0 +1,301 @@
+<html>
+
+<head>
+<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>Design of a Tool for Checking API Usage in Eclipse-based Components</title>
+</head>
+
+<body>
+
+<h1>Design of a Tool for Checking API Usage in Eclipse-based Components</h1>
+<p>Jim des Rivieres<br>
+Last updated Jan 14, 2005</p>
+<p>This document contains the design for a tool for checking API usage in
+Eclipse-based components and products.</p>
+<h2>Components</h2>
+<p>For the purposes of this tool, a component is a set of plug-ins and plug-in
+fragments. Components must be disjoint, in that the plug-ins and fragments
+within one component must be distinct from those in other components. In other
+words, components partition the set of plug-ins and plug-in fragments into
+disjoint subsets. We also allow a form of library component containing&nbsp; no
+plug-ins or fragments; library components are used to describe class libraries
+such as J2SE that are not located inside any plug-in.</p>
+<p>The code for a component is the sum total of the code in the component's
+plug-ins and fragments (as described by the plug-in manifest). The code is in
+the form of Java types (predominantly classes and interfaces; J2SE 5.0 adds
+enumerations and annotation types). The types that are intended to be used by
+other components are called the component's API, and referred to as API types. A
+component can provide any number of API types, including none. Typically, only a
+subset of a component's types are part of its API. The rest are referred to as
+internal types. Non-public types are always considered internal.</p>
+<p>It's common to use Java packages to separate one component from another, and
+to separate API from internal within a component. Each component generally
+declares its code in packages different from those used by any other component.
+An API package is one that contains at least one API type. An internal package
+is one that contains no API types. The default assumption is that all public
+top-level types in an API package are API types.</p>
+<p>An API type declared in one component can be used by other components is
+various ways:</p>
+<ul>
+  <li>Declare a field, variable, parameter, or return type where the type is an
+    API type.</li>
+  <li>Cast the value on an expression to an API type.</li>
+  <li>Declare a class that implements an API interface.</li>
+  <li>Declare an interface that extends an API interface.</li>
+  <li>Declare a class that extends (subclasses) an API class.</li>
+  <li>Creates an instance of an API class.</li>
+</ul>
+<p>It is common for an API type to be intended to be used only in certain ways.
+In some cases, Java modifiers can be used to rule out unintended uses (e.g.,
+prevent subclassing by declaring the class &quot;final&quot;). But in many
+cases, the intended uses are spelled out in the type's specification (doc
+comment). The most common restrictions are:</p>
+<ul>
+  <li>Clients may not instantiate this API class.</li>
+  <li>Clients may not subclass this API class.</li>
+  <li>Clients may not implement this API interface. It follows that the client
+    may not extend the interface either.</li>
+</ul>
+<p>Types have members (fields, methods, types). For the present, we make the
+simplifying assumption that all public and protected members of an API type are
+intended to be used by other components.</p>
+<h2>Component description files</h2>
+<p>Each component will be described via a component description file. The file
+format is XML-based; the DTD follows (complete <a href="http://dev.eclipse.org/viewcvs/index.cgi/working/apitools/component.xsd?cvsroot=WebTools_Project">XML
+scheme</a>):</p>
+<pre>&lt;!ELEMENT component (plugin* package* component-depends)&gt;
+&lt;!ATTLIST component 
+  name               CDATA #REQUIRED
+&gt;</pre>
+The &lt;component&gt; element provides information about a component.
+Attributes:
+<ul>
+  <li><b>name</b> - the component name; &quot;Eclipse Platform Generic
+    Workbench&quot;; note that this name is used to refer to the component and
+    distinguish it from other components (but otherwise has no official status
+    in Eclipse ontology)</li>
+</ul>
+<p>Child elements or the &lt;component&gt; element describe the set of plug-ins
+and fragments making up the component, provide information about the Java
+packages and types in the component's code, and include a list of other
+components on which this component may depend.</p>
+<p>Each &lt;plugin&gt; element must identify a distinct plug-in or fragment. The
+list of plug-ins must be complete; that is, a component contains a plug-in (or
+fragment) if and only if a &lt;plugin&gt; element occurs as a child of the
+&lt;component&gt; element.</p>
+<pre>&lt;!ELEMENT plugin EMPTY&gt; 
+&lt;!ATTLIST plugin 
+  id                 CDATA #REQUIRED
+  fragment           (&quot;true&quot; | &quot;false&quot;) &quot;false&quot;
+&gt;</pre>
+The &lt;plugin&gt; element identifies a plug-in or plug-in fragment that is part
+of the component. Attributes:
+<ul>
+  <li><b>id</b> - the plug-in id or plug-in fragment id; e.g., &quot;org.eclipse.core.resources&quot;;
+    note that in the case of a fragment, this is the id of fragment itself</li>
+  <li><b>fragment</b> - whether this is a plug-in fragment as opposed to a
+    plug-in (default: plug-in)</li>
+</ul>
+<p>Each &lt;plugin&gt; element must identify a distinct plug-in or fragment. The
+list of plug-ins must be complete; that is, a component contains a plug-in (or
+fragment) if and only if a &lt;plugin&gt; element occurs as a child of the
+&lt;component&gt; element.</p>
+<pre>&lt;!ELEMENT package (type*)&gt;
+&lt;!ATTLIST package 
+  name               CDATA #REQUIRED
+  exclusive          (&quot;true&quot; | &quot;false&quot;) &quot;true&quot;
+  api                (&quot;true&quot; | &quot;false&quot;) &quot;true&quot;
+&gt;</pre>
+The &lt;package&gt; element provides information about a package as used by the
+component. Attributes:
+<ul>
+  <li><b>name</b> - Java package name; e.g., &quot;javax.swing&quot;, &quot;org.eclipse.ui&quot;</li>
+  <li><b>api</b> - whether top-level types in this package are API types by
+    default (default: true). It's good practice for all public classes API
+    top-level types in a package to be considered API. Specify &quot;false&quot;
+    in order to explicitly list API types found in the package.</li>
+  <li><b>exclusive</b> - whether this package is reserved for exclusive use by
+    this component (default: true); specify &quot;false&quot; in (rare) cases
+    where a multiple components declared types in the same package. Package
+    sharing is only by mutual consent; all components involved must explicitly
+    declare the package as exclusive=&quot;false&quot; (even if it has no API
+    types).</li>
+</ul>
+<p>Each &lt;package&gt; element must identify a distinct package relative to
+that component. If the unusual case where a package is shared with other
+components, the &lt;package&gt; element is understood to apply only to the types
+the component actually declares, and has no bearing on the types declared in the
+same package in any other component. The list of packages may be incomplete; if
+the component contains code in a package not mentioned in the list, the package
+is considered to be internal (equivalent to being explicitly described as
+&lt;package name=&quot;...&quot; api=&quot;false&quot; /&gt;). The children of
+the &lt;package&gt; element provide information about specific types in the
+package.</p>
+<pre>&lt;!ELEMENT type EMPTY&gt; 
+&lt;!ATTLIST type 
+  name               CDATA #REQUIRED
+  reference          (&quot;true&quot; | &quot;false&quot;) &quot;true&quot;
+  implement          (&quot;true&quot; | &quot;false&quot;) &quot;true&quot;
+  subclass           (&quot;true&quot; | &quot;false&quot;) &quot;true&quot;
+  instantiate        (&quot;true&quot; | &quot;false&quot;) &quot;true&quot;
+&gt;</pre>
+The &lt;type&gt; element provides information about a top-level type in a
+package. Attributes:
+<ul>
+  <li><b>name</b> - simple name of a top-level Java class, interface,
+    enumeration, or annotation type; e.g., &quot;String&quot;, &quot;IResource&quot;</li>
+  <li><b>reference</b> - whether other components are expected to reference this
+    type by name (default: true); specify &quot;false&quot; to indicate that the
+    type is internal</li>
+  <li><b>implement</b> - whether other components are expected to declare a
+    class that implements this interface (default: true); specify
+    &quot;false&quot; for an interface that other components are not supposed to
+    implement directly; this attribute is ignored for classes, enumerations, and
+    annotation types, none of which can be meaningfully implemented</li>
+  <li><b>subclass</b> - whether other components are expected to declare a class
+    that directly subclasses this class (default: true); specify
+    &quot;false&quot; for a class that other components are not supposed to
+    subclass directly; this attribute is ignored for interfaces, enumerations,
+    and annotation types, none of which can be meaningfully subclassed</li>
+  <li><b>instantiate</b> - whether other components are expected to create
+    instances of this class or annotation type (default: true); specify
+    &quot;false&quot; for a type that other components are not supposed to
+    instantiate directly; this attribute is ignored for interfaces and
+    enumerations, neither of which can be meaningfully instantiated; this
+    attribute is moot for classes that are declared final (or ones with no
+    generally accessible constructors), since the Java compiler and JRE will
+    block outside attempts to instantiate</li>
+</ul>
+<p>(Note: We could extend the schema in the future to allow &lt;type&gt;
+elements to provide analogous information about their members. We could also
+extend the &lt;component&gt; element to allow aspects other than code API to be
+described.)</p>
+<pre>&lt;!ELEMENT component-depends (component-ref*)&gt;
+&lt;!ATTLIST component-depends 
+  unrestricted       (&quot;true&quot; | &quot;false&quot;) &quot;false&quot;
+&gt;
+&lt;!ELEMENT component-ref EMPTY&gt;
+&lt;!ATTLIST component-ref 
+  name               CDATA #REQUIRED
+&gt;</pre>
+The &lt;component-depends&gt; element identifies other components on which this
+component is allowed to depend. Attributes:
+<ul>
+  <li><b>unrestricted</b> - whether this component is allowed to depend on
+    arbitrary other components, or just the ones explicitly named by the
+    &lt;component-ref&gt; children</li>
+</ul>
+If a component specifies &lt;component-depends
+unrestricted=&quot;true&quot;&gt;, then it is allowed to depend on any component
+(and the children, if any, are ignored). Otherwise, the &lt;component-ref&gt;
+elements give the names of the component on which this component may depend. The
+&lt;component-ref&gt; element identifies a component by name. Attributes:
+<ul>
+  <li><b>name</b> - the name of the referenced component; e.g., &quot;Eclipse
+    Platform Generic Workbench&quot;</li>
+</ul>
+<h3>Example</h3>
+<p>A component description of one of the Eclipse Platform components:</p>
+<pre>&lt;component name=&quot;Eclipse Platform Core Resources&quot;&gt;
+ &lt;plugin id=&quot;org.eclipse.core.resources&quot; /&gt;
+ &lt;plugin id=&quot;org.eclipse.core.resources.win32&quot; fragment=&quot;true&quot; /&gt;
+ &lt;plugin id=&quot;org.eclipse.core.resources.linux&quot; fragment=&quot;true&quot; /&gt;
+ &lt;plugin id=&quot;org.eclipse.core.resources.hpux&quot; fragment=&quot;true&quot; /&gt;
+ &lt;plugin id=&quot;org.eclipse.core.resources.macosx&quot; fragment=&quot;true&quot; /&gt;
+ &lt;plugin id=&quot;org.eclipse.core.resources.qnx&quot; fragment=&quot;true&quot; /&gt;
+
+ &lt;package name=&quot;org.eclipse.core.resources&quot;&gt;
+&nbsp;&nbsp; &lt;type name=&quot;ICommand&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IContainer&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IFile&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IFileState&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IFolder&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IMarker&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IMarkerDelta&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IPathVariableChangeEvent&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IPathVariableManager&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IProject&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IProjectDescription&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IProjectNatureDescriptor&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IResource&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IResourceChangeEvent&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IResourceDelta&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IResourceProxy&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IResourceRuleFactory&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IResourceStatus&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;ISaveContext&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;ISavedState&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;ISynchronizer&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IWorkspace&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IWorkspaceDescription&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IWorkspaceRoot&quot; implement=&quot;false&quot; /&gt;
+&nbsp;&nbsp; &lt;type name=&quot;ResourcesPlugin&quot; subclass=&quot;false&quot; instantiate=&quot;false&quot; /&gt;
+ &lt;/package&gt;
+ &lt;package name=&quot;org.eclipse.core.resources.mapping&quot;&gt;
+ &lt;/package&gt;
+ &lt;package name=&quot;org.eclipse.core.resources.refresh&quot;&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IRefreshResult&quot; implement=&quot;false&quot; /&gt;
+ &lt;/package&gt;
+ &lt;package name=&quot;org.eclipse.core.resources.team&quot;&gt;
+&nbsp;&nbsp; &lt;type name=&quot;IResourceTree&quot; implement=&quot;false&quot; /&gt;
+ &lt;/package&gt;
+ &lt;component-depends&gt;
+    &lt;component-ref name=&quot;Eclipse Platform Core Resources&quot; /&gt;
+    &lt;component-ref name=&quot;J2SE&quot; /&gt;
+ &lt;/component-depends&gt;
+&lt;/component&gt;</pre>
+<h2>How component descriptions are used</h2>
+<ul>
+  <li><b>Component package/type map</b> - Given the code for a component and its
+    component description, you can generate a fleshed-out list of the API types
+    declared by the component. (It's considerably harder to properly describe
+    the set of API members, since this involves building the supertype chain and
+    performing inheritance. Since the supertype chain need not be confined to a
+    single component, you also need the code for required plug-ins, etc.)</li>
+  <li><b>Inter-component reference map</b> - Given the code for a component, its
+    component description, and the component descriptions for all other
+    components to which the given component may contain references, you can
+    generate the list of external references from the component to types in some
+    other component (possibly unknown, possibly ambiguous). In particular, you
+    can do this without needing to consult the code for the other components (or
+    even needing the code to be available).</li>
+  <li><b>Fragile usage map</b> - You can go further and classify inter-component
+    usage as fragile. This requires the code for a component, its component
+    description, and the component descriptions for all other components to
+    which the given component may contain references. In the limited case of
+    shared packages between components, the code for these components may be
+    needed to disambiguate external references to types in the shared package. A
+    fragile external reference is any of:
+    <ul>
+      <li>A reference to an internal type in another (possibly unknown)
+        component.</li>
+      <li>A declaration of a subclass of a class C in another component where C
+        is described as subclass=&quot;false&quot;.</li>
+      <li>A declaration of a class implementing an interface I in another
+        component where I is described as implement=&quot;false&quot;.</li>
+      <li>An invocation of a constructor of a class C in another component where
+        C is described as instantiate=&quot;false&quot;.</li>
+      <li>A declaration of a type in a package P that another component
+        describes as exclusive=&quot;true&quot;.</li>
+    </ul>
+  </li>
+</ul>
+<h2>Change history</h2>
+<ul>
+  <li>Dec. 23, 2004 - Initial version</li>
+  <li>Jan. 14, 2005
+    <ul>
+      <li>Added &lt;component-depends&gt; element to allow each component to
+        explicitly specify which other component it may depend on.</li>
+      <li>Added clarification to &quot;api&quot; attribute of &lt;package&gt;
+        element re: this is in line with good practice of making all top-types
+        public types in an API package being considered API.</li>
+    </ul>
+  </li>
+</ul>
+
+</body>
+
+</html>