docs/core/nativeAPI.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
	<meta http-equiv="CONTENT-TYPE" content="text/html; charset=iso-8859-1">
	<title>MSV: Design & Native API</title>
	<!-- $Id$ -->
<style type="text/css">
<!--
pre {  background-color: #eeeeee; color: #000099}
code {  color: #000099}
h1 {  color: #000099}
h2 {  color: #000099; font-style: italic}
h3 {  font-style: italic; color: #000099; text-decoration: underline}
h4 {  font-style: italic; color: #000099}
-->
</style>
</head>
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#dddddd">
   <tr>
      <td align="center" valign="middle">
         <table width="100%" border="1" cellspacing="3" cellpadding="3">
            <tr>
               <td valign="top" bgcolor="#FFFFFF">
                  <h1>Multi-Schema XML Validator (MSV)</h1>
               </td>
            </tr>
            <tr>
               <td align="left" valign="top" bgcolor="#FFFFFF">
                  <h2><em>Design & Native API</em></h2>
               </td>
            </tr>
         </table>
      </td>
   </tr>
</table>

<blockquote>
<p>This document describes the design and how you can use the native API of MSV to drive it to the limit.</p>
</blockquote>

<hr>
<h2>Contents</h2>
<ol>
  <li><a href="#overview">Design Overview</a></li>
  <li><a href="#load">Loading Schemata</a></li>
  <li><a href="#agm">Playing with AGM</a>
    <ul>
      <li><a href="#agm_dep">Schema Language Dependency</a></li>
      <li><a href="#agm_exps">Expression and ExpressionPool</a></li>
      <li><a href="#agm_create">Creating AGM from scratch</a></li>
      <li><a href="#agm_access">Accessing AGM</a></li>
      <li><a href="#agm_modify">Manipulating AGM</a></li>
    </ul>
  </li>
  <li><a href="#controller">Controlling Parsing of Schemata</a></li>
  <li><a href="#validate">Validating Documents</a>
    <ul>
      <li><a href="#vgm">VGM</a></li>
      <li><a href="#thread">Multithread Environment</a></li>
      <li><a href="#daemon">Daemon Process</a></li>
    </ul>
  </li>
  <li><a href="#type">Type Assignment</a>
    <ul>
      <li><a href="#trexext">TREX extension</a></li>
    </ul>
  </li>
</ol>


<hr>
<a name="overview"></a>
<h2>Design Overview</h2>

<blockquote>
<p>MSV comprises six components.</p>

<table width="85%" border="1" cellpadding="3" cellspacing="0" bgcolor="#ffffff">
	<tr valign="top">
		<th nowrap bgcolor="#000099"><font color="#ffffcc"><em>Component</em></font></th>
		<th nowrap bgcolor="#000099"><font color="#ffffcc"><em>Description</em></font></th>
	</tr>
	<tr valign="top">
		<th align="right" bgcolor="#e8fcff">Abstract grammar model (AGM)</th>
		<td align="left">Schema-independent grammar model. All supported schemata are parsed into this internal representation. This model, coupled with the grammar reader, may be useful for other applications.</td>
	</tr>
	<tr valign="top">
		<th align="right" bgcolor="#e8fcff">Grammar reader</th>
		<td align="left">Component used to parse schemata by using SAX to construct AGMs.</td>
	</tr>
	<tr valign="top">
		<th align="right" bgcolor="#e8fcff">Verification grammar model (VGM)</th>
		<td align="left">Bridge between AGM and Validator. It works as an abstraction layer between them, thereby makeing non-automaton-based algorithms possible.</td>
	</tr>
	<tr valign="top">
		<th align="right" bgcolor="#e8fcff">Validator</th>
		<td align="left">Component to validate an XML instance with a VGM by using SAX.</td>
	</tr>
	<tr valign="top">
		<th align="right" bgcolor="#e8fcff">Datatype validator</th>
		<td align="left">Component separately available as the Sun XML Datatypes Library.</td>
	</tr>
	<tr valign="top">
		<th align="right" bgcolor="#e8fcff">RELAX Namespace ("divide&amp;validate" framework)</th>
		<td align="left">Component that allows multiple schema languages to cooperatively validate one instance. <em>The mplementation of this component is likely to change substantially in the future.</em></td>
	</tr>
</table>
</blockquote>

<hr>
<a name="load"></a>
<h2>Loading Schemata</h2>
<blockquote>
<p>If you need finer control, then you may want to control MSV directly instead of using the generic JARV interface. This section and following sections will focus on the direct use of MSV.</p>
<p>The easiest way to load a grammar is to use the <code>loadSchema</code> method of <code>com.sun.msv.reader.util.GrammarLoader</code>.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
Grammar loadGrammar( String schemaFileNameOrURL )
{
  SAXParserFactory factory = new javax.xml.parsers.SAXParserFactory();
  // or you can use different parser like Xerces-J by
  // <b>new org.apache.xerces.parsers.jaxp.SAXParserFactoryImpl();</b>

  factory.setNamespaceAware(true);

  return GrammarLoader.loadSchema(
                        schemaFileNameOrURL,
                        new com.sun.msv.reader.util.IgnoreController(),
                        factory );
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p><code>GrammarLoader</code> automatically detects the type of schema (RELAX Core/TREX/RELAX Namespace/RELAX NG/W3C) and handles it appropriately.</p>

<p>The second parameter specifies a <code>controller</code> object that receives notifications and controls the loading behavior. <code>IgnoreController</code> does nothing, but by providing a different object, you can control the parsing process.</p>

<p>The third parameter specifies <code>SAXParserFactory</code> to be used. Factory has to be configured as namespace-aware.</p>
<p>Alternatively, to load a specific language:</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
import com.sun.msv.grammar.Grammar;
import com.sun.msv.reader.trex.ng.RELAXNGReader;
import javax.xml.parsers.SAXParserFactory;

TREXGrammar loadRELAXNG( String schemaFileNameOrURL )
{
  SAXParserFactory factory = new javax.xml.parsers.SAXParserFactory();
  factory.setNamespaceAware(true);

  return RELAXNGReader.parse(
                        schemaFileNameOrURL,
                        factory,
                        new com.sun.msv.reader.util.IgnoreController() );
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p>The parse method also accepts several other forms of arguments (e.g., <code>InputSource</code>). If loading fails, the parse method returns null.</p>
<p>Grammar readers implements <code>ContentHandler</code>, so you can also parse a grammar by the following way:</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
TREXGrammar loadRELAXNG( String schemaFileNameOrURL )
{
  RELAXNGReader reader = new RELAXNGReader( factory, new IgnoreController() );

  XMLReader xmlParser = new YourFavoriteXMLReader();

  xmlParser.setContentHandler(reader);
  xmlParser.parse(schemaFileNameOrURL);  // parse

  // this method returns null if loading fails.
  return reader.getResult();
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p>In these ways, you can parse the XML representation of the specific language into MSV's AGM.</p>
<p>Since XML DTDs are not written in XML format, they have to be parsed differently. To parse an XML DTD, do as follows</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
Grammar loadDTD( String schemaFileNameOrURL )
{
  return DTDReader.parse(
    new InputSource(schemaFileNameOrURL),
    new com.sun.msv.reader.util.IgnoreController() );
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p>The first parameter specifies the <code>InputSource</code> object from which the DTD is read. The second paramter controls the parsing behavior. Currently, MSV cannot parse an internal DTD subset.</p>
</blockquote>

<hr>
<a name="agm"></a>
<h2>Playing with AGM</h2>
<blockquote>
<p>The AGM is the internal representation of a schema used by MSV. It is a binarized regular expression commonly seen in many validating processors.</p>
</blockquote>
<a name="agm_dep"></a>
<h3>Schema Language Dependency</h3>
<blockquote>
<p>The AGM consists of two parts.</p>

<ol>
	<li><p><strong>Core:</strong> common part of various languages. e.g., <code>ChoiceExp</code>, <code>SequenceExp</code>, <code>MixedExp</code>, and more. Also contains several abstract classes (<code>ReferenceExp</code> and <code>ElementExp</code>).</p></li>
	<li><p><strong>Language-specific stubs:</strong> concrete implementations of abstract classes and composite expressions of the specific language.</p></li>
</ol>
<p>Several primitives in the core set (concur, list, and interleave) are not used by some languages. Those primitives are still placed in the core set, but the application may want to refuse to process such primitives. For example, AGMs from RELAX Core never contain <code>ConcurExp</code> or <code>InterleaveExp</code>. So an application that only processes RELAX Core can safely skip implementing concur related operations.</p>
<p>You should also note that the AGM is designed to handle differences between schema languages.</p>
<ul>
	<li><p><strong>Reference to another part of the grammar</strong> -- Most of the schema languages have a mechanism to name declarations and refer to them by name from other locations. TREX has only one mechanism (<code>&lt;ref&gt;&amp;&lt;define&gt;</code>), whereas RELAX has four separate definitions/references (<code>&lt;tag&gt;</code>, <code>&lt;attPool&gt;</code>, <code>&lt;hedgeRule&gt;</code>, <code>&lt;elementRule&gt;</code> and <code>&lt;ref&gt;</code>, and <code>&lt;hedgeRef&gt;</code>). W3C XML Schema has six distinct mechanisms. To handle the difference, the core part provides an abstract <code>ReferenceExp</code> class, which is used as the base class that represents the referencable declaration. Language stubs then derive <code>ReferenceExp</code> and provide concrete implementations.</p></li>
	<li><p><strong>Constraint of tag name</strong> -- RELAX constrains tag name by a <code>&lt;tag&gt;</code> declaration, which is in turn referenced by an <code>&lt;elementRule&gt;</code> declaration. TREX constrains tag name by element declaration itself. So RELAX has one more abstraction layer between constraint over element and that over tag name. To handle such difference, the core part provides abstract <code>ElementExp</code> class, and stubs provide concrete implementations respectively.</p></li>
</ul>
<p>Generally speaking, you may want to avoid dependency on the stub parts. If your code only depends on the core part, then your code will work with AGMs created from any language. <code> com.sun.msv.verifier.regexp </code> is one of such code that works with any AGM.</p>
<p><code>InterleaveExp</code> is used only by RELAX NG, TREX, and W3C XML Schema Part1. <code>ConcurExp</code> is used solely by TREX. Application may reject those primitives if your target schema language does not use them.</p>
</blockquote>

<a name="agm_exps"></a>
<h3>Expression and ExpressionPool</h3>
<blockquote>
<p>Expression and most of the derived classes are immutable, and they have to be created through ExpressionPool. Internally, every Expression is memorized by ExpressionPool so that sub expressions can be shared and reused.</p>
<p>Mixing two expressions created from two different pools is possible, but not recommended. If you are going to use MSV in a multithreaded environment, or you are going to use it in a daemon process, see <a href="#thread">"Multithreaded Environment"</a> and <a href="#daemon">"Daemon Process"</a> respectively.</p>
</blockquote>

<a name="agm_create"></a>
<h3>Creating AGM From Scratch</h3>
<blockquote>
<p><code>RELAXCoreReader</code>/<code>TREXGrammarReader</code>/<code>RELAXNSReader</code>/<code>XMLSchemaReader</code>/<code>DTDReader</code> is just one way to create an AGM. Alternatively, you can create it from scratch.</p>

<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
import com.sun.msv.grammar.trex.*;
import com.sun.msv.grammar.*;

TREXGrammar create()
{
  ExpressionPool pool = new ExpressionPool();
  TREXGrammar g = new TREXGrammar(pool); // create an empty grammar

  g.start = new ElementPattern(
    // name class that constrains tag name
    new SimpleNameClass("http://namespace.uri/","tagname"),
    // content model
      pool.createMixed(
        pool.createSequence(
          new ElementPattern(
            new SimpleNameClass("http://namespace.uri/","tagname2"),
            pool.createEpsilon() // empty
          ),
          pool.createAttribute(
            new SimpleNameClass("","attr"),
            pool.createAnyString()
          )
        )
      )
    );
  // ElementPatterns are created outside ExpressionPool

  return g;
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p>The AGM created by the above example is equivalent to the following TREX grammar.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
&lt;element name="tagname" ns="http://namespace.uri/"&gt;
  &lt;mixed&gt;
    &lt;group&gt;
      &lt;element name="tagname2"&gt;
        &lt;empty /&gt;
      &lt;/element&gt;
      &lt;attribute name="attr" /&gt;
    &lt;/group&gt;
  &lt;/mixed&gt;
&lt;/element&gt;
</pre>
		</td>
	</tr>
</table>
<hr>
<p>As you see, you have to use the <code>ExpressionPool</code> to create a tree of <code>Expression</code>. All the primitive operators are immutable.</p>
<p>Also, all associative operators like choice and sequence are binary (they can only have two operands): to create an expression of <code>(A|B|C)</code>, create <code>(A|(B|C))</code> or <code>((A|B)|C)</code>. For more, see the JavaDoc for <code>ExpressionPool</code>.</p>
<p>A named expression can be created as follows:</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
{
  ExpressionPool pool = new ExpressionPool();
  TREXGrammar g = new TREXGrammar(pool); // create an empty grammar

  g.start = pool.createZeroOrMore( g.namedPatterns.getOrCreate("label") );

  g.namedPatterns.getOrCreate("label").exp =
      pool.createChoice( ... ); // whatever expression you like
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p>You can refer to the named expression before the actual definition is provided. It is the responsibility of the application to ensure that every named expression has a definition. The grammar created by this example is equivalent to the following TREX pattern:</p>

<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
&lt;xmp&gt;
&lt;grammar&gt;
  &lt;start&gt;
    &lt;zeroormore&gt;
      &lt;ref name="label" /&gt;
    &lt;/zeroormore&gt;
  &lt;/start&gt;
  &lt;define name="label"&gt;
    &lt;choice&gt;
      ...
    &lt;/choice&gt;
  &lt;/define&gt;
&lt;/grammar&gt;
&lt;/xmp&gt;
</pre>
		</td>
	</tr>
</table>
<hr>
<p>To create a RELAX AGM, use <code>RELAXGrammar</code> and <code>RELAXModule</code> as a starting point.</p>

</blockquote>
<a name="agm_access"></a>
<h3>Accessing AGM</h3>
<blockquote>
<p>One feature that you may find useful is the "visitor" design pattern support. You
can write your own visitor by implementing <code>ExpressionVisitor</code>. See the JavaDoc for <code>ExpressionVisitor</code> for details.</p>
<p>Usually, this is the easiest way to access AGMs</p>
</blockquote>

<a name="agm_modify"></a>
<h3>Manipulating AGM</h3>
<blockquote>
<p>Due to the immutability of the AGM, you cannot "modify" an AGM. Instead, you
create a modified AGM. To do this, use <code>ExpressionCloner</code>. The following example
creates a new AGM that changes <code>ChoiceExp</code> to <code>SequenceExp</code> and <code>SequenceExp</code> to <code>ChoiceExp</code>.
</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
class SwitchChoiceAndSequence extends com.sun.msv.grammar.ExpressionCloner {

  private ExpressionPool pool;

  public Expression onSequence( SequenceExp exp ) {
    return pool.createChoice( exp.exp1, exp.exp2 );
  }
  public Expression onChoice( ChoiceExp exp ) {
    return pool.createSequence( exp.exp1, exp.exp2 );
  }
}

// usage
Expression modifiedExp = originalExp.visit( new SwitchChoiceAndSequence() );
</pre>
		</td>
	</tr>
</table>
<hr>
<p>See javadoc of ExpressionCloner for details.</p>
</blockquote>

<hr>
<a name="controller"></a>
<h2>Controlling Parsing of Schemata</h2>
<blockquote>
<p>Any application can use <code>GrammarReaderController</code> to control how a grammar is parsed. For example, it can:</p>
<ul>
  <li>Receive errors and warnings encountered during the parsing</li>
  <li>Prohibit inclusions</li>
  <li>Resolve inclusion to a different source.</li>
</ul>

<p>See <code>GrammarReaderController</code> and <code>IgnoreController</code> for details.</p>
</blockquote>

<hr>
<a name="validate"></a>
<h2>Validating Documents</h2>

<a name="vgm"></a>
<h3>Validation Grammar Model (VGM)</h3>
<blockquote>
<p>To validate documents with a AGM, you have to "wrap" it in a VGM. The VGM can be understood as an abstraction of an AGM for the validator.</p>
<p>The VGM is a simple model which consists of two interfaces only: <code>Acceptor</code> and <code>DocumentDeclaration</code>. Any VGM implementation can be used as long as it implements them.</p>
<p>Currently, only one VGM implementation is available, which is placed under the <code>com.sun.msv.verifier.regexp</code> package.</p>
<p>The following example creates a RegExp VGM from a <code>Grammar</code> object. <code>Grammar</code> is an interface implemented by <code>RELAXGrammar</code>, <code>RELAXModule</code>, <code>TREXGrammar</code>, and <code>XMLSchemaGrammar</code>.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
import com.sun.msv.verifier.regexp.REDocumentDeclaration;
import com.sun.msv.grammar.Grammar;

DocumentDeclaration createVGM( Grammar g ) {
  return new REDocumentDeclaration(g);
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p>Alternatively, you can pass an arbitrary expression as the first parameter and a newly created pool as the second parameter.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
DocumentDeclaration createVGM( Expression exp ) {
  return new REDocumentDeclaration( exp, new ExpressionPool() );
}
</pre>
		</td>
	</tr>
</table>
<hr>
<p>Then VGM can be passed to the constructor of <code>Verifier</code> class to actually perform a validation.</p>
</blockquote>

<a name="thread"></a>
<h3>Multithreaded Environment</h3>
<blockquote>
<p>AGMs are thread-safe because they are immutable. A thread can safely use an AGM parsed by a different thread; or two threads can safely share the same AGM. <code>ExpressionPool</code> is also thread-safe. Multiple threads can share the same pool, which is created by another thread.</p>
<p>VGM, on the other hand, is not thread-safe. Each thread has to create its own VGM and use its own. You should never share a VGM between threads. Verifier is another thread-<b>un</b>safe component. Also, it's not reentrant, so you can only use one object to validate one document at a time.</p>
<p>When a new expression is found, it is stored to the pool. To do this, a thread has to acquire a lock. And the pool is very frequently called during validation. So you might think that sharing a pool might cause a performance bottleneck.</p>
<p>However, a casual experiment shows that this is not always the case. Yes, a thread has to acquire a lock to modify the pool, but this update can be done concurrently while other threads read the pool. And update is far less frequent than retrieval. So please benchmark by yourself if you need to achieve the optimal performance.</p>
</blockquote>

<a name="daemon"></a>
<h3>Daemon Process</h3>
<blockquote>
<p>Generally, it's a good practice to keep re-using the same <code>ExpressionPool</code>. Using the same pool makes it bigger, and a bigger pool contains more expressions, which in turn results in faster validation.</p>
<p>If you keep using the same <code>ExpressionPool</code>, it gradually expands. Its expansion is like a square-root function. It grows rapidly at first, but its growth becomes slower and slower as time goes by.</p>
<p>Its size will eventually reach a certain limit, and the growth stops there. If your schema is DTD, RELAX, TREX without <code>&lt;interleave&gt;</code>, or W3C XML Schema without <code>&lt;all&gt;</code>, then this size limit is mostly moderate, so you can keep using the same pool forever.</p>
<p>However, if a grammar is TREX with <code>&lt;interleave&gt;</code> patterns, or W3C XML Schema with <code>&lt;all&gt;</code>s, then the upper bound of a pool could be exponential to the size of the grammar (especially if interleave/all contains large patterns). If this is the case, and your application runs 24/7 as a daemon process, then you should occasionally throw away the pool to prevent its size from expanding indefinitely.</p>
<p>Note that pool expansion is slow; the size of a pool is proportional to the number of validated documents even in the worst case. So usually it takes quite a long time to make a pool explode.</p>
<p>To throw away <code>ExpressionPool</code>, simply create a new VGM with a brand-new pool, like this.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
DocumentDeclaration vgm = new REDocumentDeclaration( grammar.getTopLevel(), new ExpressionPool() );
</pre>
		</td>
	</tr>
</table>
<hr>
</blockquote>

<hr>
<a name="type"></a>
<h2>Type Assignment</h2>
<blockquote>
<p>MSV can report the element declaration which is applied to the current element, and what datatype is applied to text. This information is useful for deciding what to do with the reported element.</p>
<p>To retrieve these information, call the <code>getCurrentElementType</code> method of the <code>Verifier</code> class. This method returns the correct value only when called immediately after it processed the <code>startElement</code> method. If you are using <code>com.sun.msv.verifier.VerifierFilter</code>, then you can call this method only in your handler's <code>startElement</code> method.</p>
<p>The following code illustrates how to retrieve RELAX "label" from your own <code>ContentHandler</code>.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
void startElement( .... )
{// SAX startElement event

  ElementRule er = (ElementRule)currentVerifier.getCurrentElementType();
  if( er==null )
    // this may happen when the schema is complex.
    // MSV is unable to determine label/role at this moment.
  else
  {
    // er holds a reference to ElementRule object which is applied to this element.

    if(er.getParent()==null )
      // this element is declared by inline &lt;element&gt; declaration.
      // so it doesn't have any role/label
    else
    {
      final String label = er.getParent().name; // obtain label name
      final String role = er.clause.name; // obtain role name

      ....
    }
  }

  ...
}
</pre>
		</td>
	</tr>
</table>
<hr>
</blockquote>

<a name="trexext"></a>
<h3>TREX extension</h3>
<blockquote>
<p>TREX doesn't have a mechanism to name the <code>&lt;element&gt;</code> pattern. Therefore, MSV introduces a proprietary extension to TREX that provides this naming mechanism.</p>
<p>Annotation is done by adding a "label" attribute to the <code>&lt;element&gt;</code> pattern. The "label" attribute has to be in the "<code>http://www.sun.com/xml/msv/trex-type</code>" namespace. These attributes will be ignored by other TREX validating processors.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
&lt;xmp&gt;
&lt;grammar xmlns:ext="http://www.sun.com/xml/msv/trex-type"&gt;
  &lt;start&gt;
    &lt;element ext:label="rootLabel" name="root"&gt;
      ...
      &lt;element name="child"&gt; &lt;!-- label attribute is optional --&gt;
        ...
      &lt;/element&gt;
    &lt;/element&gt;
  &lt;/start&gt;
&lt;/grammar&gt;
&lt;/xmp&gt;
</pre>
		</td>
	</tr>
</table>
<hr>

<p>The following example illustrates how to load an annotated TREX pattern.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
TREXGrammarReader reader = new TREXGrammarReader(
    myGrammarReaderControllerObject,
    saxParserFactory,
    new com.sun.msv.reader.trex.typed.TypedTREXGrammarInterceptor(),
    new ExpressionPool() );
((XMLReader)reader).parse(schemaFileName);

// obtain parsed grammar object. it returns null in case of error
TREXGrammar grammar = reader.getResult();
</pre>
		</td>
	</tr>
</table>
<hr>
<p>The following example shows how to access TREX "label" information from your ContentHandler.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
	<tr>
		<td bgcolor="#eeeeee">
<pre>
import com.sun.msv.grammar.trex.typed.TypedElementPattern;

void startElement( .... )
{// SAX startElement event

  Object o = currentVerifier.getCurrentElementType();
  if( o==null )
    // this may happen when the schema is complex.
    // MSV is unable to determine label/role at this moment.
  else
  if( o instanceod TypedElementPattern )
  {
    // the current element declaration has label attribute.

    final String label = ((TypedElementPattern)o).label;

    ....
  }
  else
    // the current element declaration has no label attribute.

  ...
}
</pre>
		</td>
	</tr>
</table>
<hr>
</blockquote>
</body>
</html>