releng.wtptools/api/api-usage-checking-design.html - gerrit/webtools/webtools.releng - Git at Google


            
            <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>
	<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  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 "final"). 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><!ELEMENT component (plugin* package* component-depends)>
	<!ATTLIST component
	name CDATA #REQUIRED
	></pre>
	The <component> element provides information about a component.
	Attributes:
	<ul>
	<li><b>name</b> - the component name; "Eclipse Platform Generic
	Workbench"; 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 <component> 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 <plugin> 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 <plugin> element occurs as a child of the
	<component> element.</p>
	<pre><!ELEMENT plugin EMPTY>
	<!ATTLIST plugin
	id CDATA #REQUIRED
	fragment ("true" \| "false") "false"
	></pre>
	The <plugin> 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., "org.eclipse.core.resources";
	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 <plugin> 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 <plugin> element occurs as a child of the
	<component> element.</p>
	<pre><!ELEMENT package (type*)>
	<!ATTLIST package
	name CDATA #REQUIRED
	exclusive ("true" \| "false") "true"
	api ("true" \| "false") "true"
	></pre>
	The <package> element provides information about a package as used by the
	component. Attributes:
	<ul>
	<li><b>name</b> - Java package name; e.g., "javax.swing", "org.eclipse.ui"</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 "false"
	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 "false" 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="false" (even if it has no API
	types).</li>
	</ul>
	<p>Each <package> element must identify a distinct package relative to
	that component. If the unusual case where a package is shared with other
	components, the <package> 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
	<package name="..." api="false" />). The children of
	the <package> element provide information about specific types in the
	package.</p>
	<pre><!ELEMENT type EMPTY>
	<!ATTLIST type
	name CDATA #REQUIRED
	reference ("true" \| "false") "true"
	implement ("true" \| "false") "true"
	subclass ("true" \| "false") "true"
	instantiate ("true" \| "false") "true"
	></pre>
	The <type> 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., "String", "IResource"</li>
	<li><b>reference</b> - whether other components are expected to reference this
	type by name (default: true); specify "false" 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
	"false" 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
	"false" 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
	"false" 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 <type>
	elements to provide analogous information about their members. We could also
	extend the <component> element to allow aspects other than code API to be
	described.)</p>
	<pre><!ELEMENT component-depends (component-ref*)>
	<!ATTLIST component-depends
	unrestricted ("true" \| "false") "false"
	>
	<!ELEMENT component-ref EMPTY>
	<!ATTLIST component-ref
	name CDATA #REQUIRED
	></pre>
	The <component-depends> 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
	<component-ref> children</li>
	</ul>
	If a component specifies <component-depends
	unrestricted="true">, then it is allowed to depend on any component
	(and the children, if any, are ignored). Otherwise, the <component-ref>
	elements give the names of the component on which this component may depend. The
	<component-ref> element identifies a component by name. Attributes:
	<ul>
	<li><b>name</b> - the name of the referenced component; e.g., "Eclipse
	Platform Generic Workbench"</li>
	</ul>
	<h3>Example</h3>
	<p>A component description of one of the Eclipse Platform components:</p>
	<pre><component name="Eclipse Platform Core Resources">
	<plugin id="org.eclipse.core.resources" />
	<plugin id="org.eclipse.core.resources.win32" fragment="true" />
	<plugin id="org.eclipse.core.resources.linux" fragment="true" />
	<plugin id="org.eclipse.core.resources.hpux" fragment="true" />
	<plugin id="org.eclipse.core.resources.macosx" fragment="true" />
	<plugin id="org.eclipse.core.resources.qnx" fragment="true" />

	<package name="org.eclipse.core.resources">
	<type name="ICommand" implement="false" />
	<type name="IContainer" implement="false" />
	<type name="IFile" implement="false" />
	<type name="IFileState" implement="false" />
	<type name="IFolder" implement="false" />
	<type name="IMarker" implement="false" />
	<type name="IMarkerDelta" implement="false" />
	<type name="IPathVariableChangeEvent" implement="false" />
	<type name="IPathVariableManager" implement="false" />
	<type name="IProject" implement="false" />
	<type name="IProjectDescription" implement="false" />
	<type name="IProjectNatureDescriptor" implement="false" />
	<type name="IResource" implement="false" />
	<type name="IResourceChangeEvent" implement="false" />
	<type name="IResourceDelta" implement="false" />
	<type name="IResourceProxy" implement="false" />
	<type name="IResourceRuleFactory" implement="false" />
	<type name="IResourceStatus" implement="false" />
	<type name="ISaveContext" implement="false" />
	<type name="ISavedState" implement="false" />
	<type name="ISynchronizer" implement="false" />
	<type name="IWorkspace" implement="false" />
	<type name="IWorkspaceDescription" implement="false" />
	<type name="IWorkspaceRoot" implement="false" />
	<type name="ResourcesPlugin" subclass="false" instantiate="false" />
	</package>
	<package name="org.eclipse.core.resources.mapping">
	</package>
	<package name="org.eclipse.core.resources.refresh">
	<type name="IRefreshResult" implement="false" />
	</package>
	<package name="org.eclipse.core.resources.team">
	<type name="IResourceTree" implement="false" />
	</package>
	<component-depends>
	<component-ref name="Eclipse Platform Core Resources" />
	<component-ref name="J2SE" />
	</component-depends>
	</component></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="false".</li>
	<li>A declaration of a class implementing an interface I in another
	component where I is described as implement="false".</li>
	<li>An invocation of a constructor of a class C in another component where
	C is described as instantiate="false".</li>
	<li>A declaration of a type in a package P that another component
	describes as exclusive="true".</li>
	</ul>
	</li>
	</ul>
	<h2>Change history</h2>
	<ul>
	<li>Dec. 23, 2004 - Initial version</li>
	<li>Jan. 14, 2005
	<ul>
	<li>Added <component-depends> element to allow each component to
	explicitly specify which other component it may depend on.</li>
	<li>Added clarification to "api" attribute of <package>
	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>