| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><HTML> | |
| <HEAD> | |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > | |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> | |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> | |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> | |
| <title>Extension point schema</title> | |
| </head> | |
| <BODY BGCOLOR="#ffffff"> | |
| <h1>Extension point schema</h1> | |
| <p>Extensions are the key mechanism that a plug-in uses to add new features to the platform. Extensions cannot be arbitrarily | |
| created. They are declared using a clear specification defined by an | |
| extension point.</p> | |
| <p>Each extension must conform to the | |
| specification of the extension point that it is extending Each extension | |
| point defines attributes and expected values that must be declared by an | |
| extension. This information is maintained in the platform plug-in | |
| registry. Extension point providers query these values from the registry, | |
| so it's important to ensure that your plug-in has provided the expected | |
| information.</p> | |
| <p>In the most rudimentary form, an extension point declaration is very simple. | |
| It defines the id and name of the extension point. Any other information | |
| expected by the extension point is specific to that extension point and is | |
| documented elsewhere. (See the <a href="../../org.eclipse.platform.doc.isv/reference/extension-points/index.html">Platform | |
| Extension Point Reference</a> for the platform extension point definitions.)</p> | |
| <p>Reference documentation is useful, but it does not enable any programmatic | |
| help for validating the specification of an extension. For this reason, PDE introduces | |
| an extension point schema that describes extension points in a format fit for | |
| automated processing.</p> | |
| <p>Extension point schema is a valid XML schema as defined by W3C specification. | |
| However, the full XML schema specification is very complex and mostly unnecessary for this particular use. For this reason, PDE uses only a | |
| subset of XML schema features. Each extension point schema is a valid | |
| XML schema, but PDE does not use all the available features.</p> | |
| <h2>The benefits of extension point schemas</h2> | |
| <p>There are many benefits to describing your extension point using the PDE | |
| extension point XML schema:</p> | |
| <ol> | |
| <li>Extension point grammar allows elements, attributes, and types to be | |
| expressed formally. This | |
| information can be used by tools to validate extensions or offer assistance | |
| during creation of the extension.</li> | |
| <li> XML schema provides for documentation | |
| annotation that is similar to Javadoc in Java source. This mechanism ties | |
| short text for valid elements and attributes to the declaration of | |
| these elements and attributes. It is much easier to keep the documentation | |
| in sync because removal of an attribute will also remove documentation for | |
| the attribute. There is no need to update the reference document.</li> | |
| <li>Reference documentation can be generated. PDE provides a tool that tracks changes in extension point | |
| schemas and updates reference documentation on the fly.</li> | |
| <li>You can provide additional metadata about the extension point that can be | |
| used by tools that process the schema. PDE uses this | |
| mechanism to add additional information about elements and attributes. For | |
| example, if an attribute is marked as "Java," PDE can provide assistance | |
| while setting the value of this attribute by interacting with Java platform | |
| features.</li> | |
| </ol> | |
| <h2>Limitations of PDE XML Schema support</h2> | |
| <p>PDE uses a small subset of XML schema. Using the full XML schema | |
| features set would be | |
| an overkill in this particular case. The subset allows | |
| almost 1->1 mapping from DTDs to schemas, but without DTD limitations. The | |
| following are the main limitations of the PDE extension point schema:</p> | |
| <ol> | |
| <li>Only global element declarations are allowed.</li> | |
| <li>Only local attribute declarations are allowed. Global attributes cannot be | |
| declared.</li> | |
| <li>The following compositors are supported: <b>all</b>, <b>sequence</b>, <b>choice</b> | |
| and <b>group</b>.</li> | |
| <li>There is no global type support. Types must be declared and immediately used.</li> | |
| <li>Attributes can only have <b>string</b> and <b>boolean</b> types.</li> | |
| <li>If an attribute is<b> </b> of type <b>string</b>, only | |
| the <b>enumeration</b> restriction is | |
| supported.</li> | |
| </ol> | |
| <p>If you write an XML schema using these restrictions, you will | |
| notice that the resulting file looks strikingly similar to an equivalent DTD | |
| that defines the same grammar. The advantage of schema is in annotations (both | |
| documentation and metadata). An additional advantage is that the XML schema is itself | |
| written in XML, which makes its processing and reading much easier.</p> | |
| <p>The list above is for reference only. You are most likely to | |
| define an XML schema using the PDE schema editor that will take care of generating the correct file.</p> | |
| </body> | |
| </html> |