[115886] Updated WST ISV plugin.
diff --git a/docs/org.eclipse.wst.doc.isv/html/scanner_req.html b/docs/org.eclipse.wst.doc.isv/html/scanner_req.html
new file mode 100644
index 0000000..771a98b
--- /dev/null
+++ b/docs/org.eclipse.wst.doc.isv/html/scanner_req.html
@@ -0,0 +1,169 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+<html>
+
+<head>
+<title>Checking for internal references Requirements</title>
+<link
+ rel="stylesheet"
+ type="text/css"
+ href="sources/formate.css">
+
+</head>
+
+<body>
+
+<p class="ueberschrift">Requirements for A Tool for Checking API Usage
+in Eclipse-based Components</p>
+<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>
+<p class="ueberschrift">1. The Problem</p>
+<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>
+<p class="ueberschrift">2. General Requirements</p>
+<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>
+<p class="ueberschrift">References</p>
+<ul>
+ <li><a href="how_to_use_api.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</a><br>
+ 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>