releng.wtptools/api/component.xsd

<?xml version="1.0" encoding="UTF-8"?>
<!-- Version: $Id$ -->

<!-- 
	Copyright (c) 2005 IBM Corp.
	All rights reserved. This program and the accompanying materials
	are made available under the terms of the Eclipse Public License v1.0
	which accompanies this distribution, and is available at
	http://www.eclipse.org/legal/epl-v10.html
	
	Contributors:
	Jim des Rivieres <Jim_des_Rivieres@ca.ibm.com>
	Arthur Ryman  <ryman@ca.ibm.com> 
	
	ChangeLog:
	
	2005-01-11: Arthur Ryman <ryman@ca.ibm.com>
	- created from Jim des Rivieres' api-usage-checking-design.html
	
-->

<schema xmlns="http://www.w3.org/2001/XMLSchema"
	targetNamespace="http://eclipse.org/component"
	xmlns:tns="http://eclipse.org/component">
	<annotation>
		<documentation>
			Each component is described via a component description
			file.
		</documentation>
	</annotation>
	<element name="component">
		<annotation>
			<documentation>
				Provides information about a component. Child elements
				of this element describe the set of plug-ins and
				fragments making up the component, and provide
				information about the Java packages and types in the
				component's code.
			</documentation>
		</annotation>
		<complexType>
			<sequence>
				<element ref="tns:plugin" minOccurs="0"
					maxOccurs="unbounded">
				</element>
				<element ref="tns:package" minOccurs="0"
					maxOccurs="unbounded">
				</element>
				<element ref="tns:component-depends" minOccurs="1"
					maxOccurs="1">
				</element>
			</sequence>
			<attribute name="name" type="string" use="required">
				<annotation>
					<documentation>
						The component name; e.g. "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)
					</documentation>
				</annotation>
			</attribute>
		</complexType>
		<unique name="plugin-id">
			<annotation>
				<documentation>
					Each &lt;plugin&gt; element must identify a distinct
					plug-in or fragment.
				</documentation>
			</annotation>
			<selector xpath="plugin" />
			<field xpath="@id"></field>
		</unique>
		<unique name="package-name">
			<annotation>
				<documentation>
					Each &lt;package&gt; element must identify a
					distinct package relative to that component.
				</documentation>
			</annotation>
			<selector xpath="package" />
			<field xpath="@name"></field>
		</unique>
	</element>

	<element name="plugin">
		<annotation>
			<documentation>
				Identifies a plug-in or plug-in fragment that is part of
				the component. 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.
			</documentation>
		</annotation>
		<complexType>
			<attribute name="id" type="string" use="required">
				<annotation>
					<documentation>
						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.
					</documentation>
				</annotation>
			</attribute>
			<attribute name="fragment" type="boolean" default="false">
				<annotation>
					<documentation>
						State whether this is a plug-in fragment as
						opposed to a plug-in (default: plug-in).
					</documentation>
				</annotation>
			</attribute>
		</complexType>
	</element>

	<element name="package">
		<annotation>
			<documentation>
				Provides information about a package as used by the
				component. In 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="..."
				api="false" /&gt;). The children of the &lt;package&gt;
				element provide information about specific types in the
				package.
			</documentation>
		</annotation>
		<complexType>
			<sequence>
				<element ref="tns:type" minOccurs="0"
					maxOccurs="unbounded">
				</element>
			</sequence>
			<attribute name="name" type="string" use="required">
				<annotation>
					<documentation>
						Java package name; e.g., "javax.swing",
						"org.eclipse.ui".
					</documentation>
				</annotation>
			</attribute>
			<attribute name="exclusive" type="boolean" default="true">
				<annotation>
					<documentation>
						States whether top-level types in this package
						are API types by default (default: true);
						specify "false" in order to explicitly list API
						types found in the package.
					</documentation>
				</annotation>
			</attribute>
			<attribute name="api" type="boolean" default="true">
				<annotation>
					<documentation>
						States 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).
					</documentation>
				</annotation>
			</attribute>
		</complexType>
		<unique name="type-name">
			<annotation>
				<documentation>
					Each &lt;type&gt; element must identify a distinct
					name relative to that package.
				</documentation>
			</annotation>
			<selector xpath="type" />
			<field xpath="@name"></field>
		</unique>
	</element>

	<element name="type">
		<annotation>
			<documentation>
				Provides information about a top-level type in a
				package. (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.)
			</documentation>
		</annotation>
		<complexType>
			<attribute name="name" type="string" use="required">
				<annotation>
					<documentation>
						Simple name of a top-level Java class,
						interface, enumeration, or annotation type;
						e.g., "String", "IResource".
					</documentation>
				</annotation>
			</attribute>
			<attribute name="reference" type="boolean" default="true">
				<annotation>
					<documentation>
						States whether other components are expected to
						reference this type by name (default: true);
						specify "false" to indicate that the type is
						internal.
					</documentation>
				</annotation>
			</attribute>
			<attribute name="implement" type="boolean" default="true">
				<annotation>
					<documentation>
						States 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.
					</documentation>
				</annotation>
			</attribute>
			<attribute name="subclass" type="boolean" default="true">
				<annotation>
					<documentation>
						States 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.
					</documentation>
				</annotation>
			</attribute>
			<attribute name="instantiate" type="boolean"
				default="true">
				<annotation>
					<documentation>
						States 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.
					</documentation>
				</annotation>
			</attribute>
		</complexType>
	</element>

	<element name="component-depends">
		<complexType>
			<sequence>
				<element ref="tns:component-ref" minOccurs="0"
					maxOccurs="unbounded" />
			</sequence>
			<attribute name="unrestricted" type="boolean"
				default="false">
				<annotation>
					<documentation>
						States whether this component is allowed to
						depend on arbitrary other components, or just
						the ones explicitly named by the
						&lt;component-ref&gt; children
					</documentation>
				</annotation>
			</attribute>
		</complexType>
	</element>

	<element name="component-ref">
		<complexType>
			<attribute name="name" type="string" use="required">
				<annotation>
					<documentation>
						Name of the referenced component; e.g., "Eclipse
						Platform Generic Workbench"
					</documentation>
				</annotation>
			</attribute>
		</complexType>
	</element>

</schema>