You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by kn...@apache.org on 2002/07/15 16:06:58 UTC
cvs commit: xml-xerces/c/doc program-sax2.xml program-sax.xml program-others.xml program-dom.xml program-deprecateddom.xml migration.xml
knoaman 2002/07/15 07:06:58
Modified: c/doc program-sax2.xml program-sax.xml program-others.xml
program-dom.xml program-deprecateddom.xml
migration.xml
Log:
documentation update.
Revision Changes Path
1.13 +6 -5 xml-xerces/c/doc/program-sax2.xml
Index: program-sax2.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-sax2.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- program-sax2.xml 12 Jul 2002 14:50:29 -0000 1.12
+++ program-sax2.xml 15 Jul 2002 14:06:58 -0000 1.13
@@ -302,10 +302,11 @@
<anchor name="use-cached"/>
<table>
<tr><td colspan="2"><em>http://apache.org/xml/features/validation/use-cachedGrammarInParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td><em>true:</em></td><td>Use cached grammar if it exists in the pool.</td></tr>
+ <tr><td><em>false:</em></td><td>Parse the schema grammar.</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
- <tr><td><em>note:</em></td><td></td></tr>
+ <tr><td><em>note:</em></td><td>If http://apache.org/xml/features/validation/cache-grammarFromParse is enabled,
+ this feature is set to true automatically. Any setting to this feature by the users is a no-op.</td></tr>
<tr><td><em>see:</em></td><td>
<link anchor="cache-grammar">http://apache.org/xml/features/validation/cache-grammarFromParse</link>
</td></tr>
@@ -316,8 +317,8 @@
<anchor name="cache-grammar"/>
<table>
<tr><td colspan="2"><em>http://apache.org/xml/features/validation/cache-grammarFromParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td><em>true:</em></td><td>Cache the grammar in the pool for re-use in subsequent parses.</td></tr>
+ <tr><td><em>false:</em></td><td>Do not cache the grammar in the pool</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
<tr><td><em>note:</em></td><td> If set to true, the http://apache.org/xml/features/validation/use-cachedGrammarInParse
is also set to true automatically.</td></tr>
1.8 +8 -6 xml-xerces/c/doc/program-sax.xml
Index: program-sax.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-sax.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- program-sax.xml 12 Jul 2002 14:50:29 -0000 1.7
+++ program-sax.xml 15 Jul 2002 14:06:58 -0000 1.8
@@ -284,11 +284,13 @@
<anchor name="use-cached"/>
<table>
- <tr><td colspan="2"><em>useCachedGrammarInParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td colspan="2"><em>void useCachedGrammarInParse(const bool)</em></td></tr>
+ <tr><td><em>true:</em></td><td>Use cached grammar if it exists in the pool.</td></tr>
+ <tr><td><em>false:</em></td><td>Parse the schema grammar.</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
<tr><td><em>note:</em></td><td>The getter function for this method is called isUsingCachedGrammarInParse</td></tr>
+ <tr><td><em>note:</em></td><td>If the grammar caching option is enabled, this option is set to true automatically.
+ Any setting to this option by the users is a no-op.</td></tr>
<tr><td><em>see:</em></td><td>
<link anchor="cache-grammar">cacheGrammarFromParse</link>
</td></tr>
@@ -298,9 +300,9 @@
<anchor name="cache-grammar"/>
<table>
- <tr><td colspan="2"><em>cacheGrammarFromParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td colspan="2"><em>void cacheGrammarFromParse(const bool)</em></td></tr>
+ <tr><td><em>true:</em></td><td>Cache the grammar in the pool for re-use in subsequent parses.</td></tr>
+ <tr><td><em>false:</em></td><td>Do not cache the grammar in the pool</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
<tr><td><em>note:</em></td><td>The getter function for this method is called isCachingGrammarFromParse</td></tr>
<tr><td><em>note:</em></td><td> If set to true, the useCachedGrammarInParse
1.4 +80 -5 xml-xerces/c/doc/program-others.xml
Index: program-others.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-others.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- program-others.xml 12 Jul 2002 14:50:29 -0000 1.3
+++ program-others.xml 15 Jul 2002 14:06:58 -0000 1.4
@@ -92,24 +92,99 @@
<s2 title="Preparsing Grammar and Grammar Caching">
<p>&XercesCName; &XercesCVersion; provides a new function to pre-parse the grammar so that users
can check for any syntax or error before using the grammar. Users can also optionally
- cached these pre-parsed grammars for later use during actual parsing.
+ cache these pre-parsed grammars for later use during actual parsing.
</p>
<p>Here is an example:</p>
<source>
+XercesDOMParser parser;
+
+// enbale schema processing
+parser.setDoSchema(true);
+parser.setDONamespaces(true);
+
+// Let's preparse the schema grammar (.xsd) and cache it.
+Grammar* grammar = parser.loadGrammar(xmlFile, Grammar::SchemaGrammarType, true);
</source>
- <p>Besides caching the pre-parsed grammar, users can also cache any grammars encountered
- during parse.
+ <p>Besides caching pre-parsed schema grammars, users can also cache any
+ grammars encountered during an xml document parse.
</p>
<p>Here is an example:</p>
<source>
+SAXParser parser;
+
+// Enable grammar caching by setting cacheGrammarFromParse to true.
+// The parser will cache any encountered grammars if it does not
+// exist in the pool.
+// If the grammar is DTD, no internal subset is allowed.
+parser.cacheGrammarFromParse(true);
+
+// Let's parse our xml file (DTD grammar)
+parser.parse(xmlFile);
+
+// We can get the grammar where the root element was declared
+// by calling the parser's method getRootGrammar;
+// Note: The parser owns the grammar, and the user should not delete it.
+Grammar* grammar = parser.getRootGrammar();
</source>
- <p>Here is an example how to use these cached grammars:
+ <p>We can use any previously cached grammars when parsing new xml
+ documents. Here are some examples on how to use those cached grammars:
</p>
<source>
+/**
+ * Caching and reusing XML Schema (.xsd) grammar
+ * Parse an XML document and cache its grammar set. Then, use the cached
+ * grammar set in subsequent parses.
+ */
+
+XercesDOMParser parser;
+
+// Enable schema processing
+parser.setDoSchema(true);
+parser.setDoNamespaces(true);
+
+// Enable grammar caching
+parser.cacheGrammarFromParsing(true);
+
+// Let's parse the XML document. The parser will cache any grammars encounterd.
+parser.parse(xmlFile);
+
+// No need to enable re-use by setting useCachedGrammarInParse to true. It is
+// automatically enabled with grammar caching.
+for (int i=0; i< 3; i++)
+ parser.parse(xmlFile);
+
+// This will flush the grammar pool
+parser.resetCachedGrammarPool();
+</source>
+
+<source>
+/**
+ * Caching and reusing DTD grammar
+ * Preparse a grammar and cache it in the pool. Then, we use the cached grammar
+ * when parsing XML documents.
+ */
+
+SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
+
+// Load grammar and cache it
+parser->loadGrammar(dtdFile, Grammar::DTDGrammarType, true);
+
+// enable grammar reuse
+parser->setFeature(XMLUni::fgXercesUseCachedGrammarInParse, true);
+
+// Parse xml files
+parser->parse(xmlFile1);
+parser->parse(xmlFile2);
</source>
<p>There are some limitations about caching and using cached grammars:</p>
<ul>
- <li></li>
+ <li>When caching/reusing DTD grammars, no internal subset is allowed.</li>
+ <li>When preparsing grammars with caching option enabled, if a grammar, in the
+ result set, already exists in the pool (same NS for schema or same system
+ id for DTD), the entire set will not be cached.</li>
+ <li>When parsing an XML document with the grammar caching option enabled, the
+ reuse option is also automatically enabled. We will only parse a grammar if it
+ does not exist in the pool.</li>
</ul>
</s2>
1.16 +16 -13 xml-xerces/c/doc/program-dom.xml
Index: program-dom.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-dom.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- program-dom.xml 12 Jul 2002 14:50:29 -0000 1.15
+++ program-dom.xml 15 Jul 2002 14:06:58 -0000 1.16
@@ -427,11 +427,13 @@
<anchor name="use-cached"/>
<table>
- <tr><td colspan="2"><em>useCachedGrammarInParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
- <tr><td><em>default:</em></td><td> false </td></tr>
- <tr><td><em>note:</em></td><td>The getter function for this method is called isUsingCachedGrammarInParse</td></tr>
+ <tr><td colspan="2"><em>void useCachedGrammarInParse(const bool)</em></td></tr>
+ <tr><td><em>true:</em></td><td>Use cached grammar if it exists in the pool.</td></tr>
+ <tr><td><em>false:</em></td><td>Parse the schema grammar.</td></tr>
+ <tr><td><em>default:</em></td><td> false </td></tr>
+ <tr><td><em>note:</em></td><td>The getter function for this method is called isUsingCachedGrammarInParse.</td></tr>
+ <tr><td><em>note:</em></td><td>If the grammar caching option is enabled, this option is set to true automatically.
+ Any setting to this option by the users is a no-op.</td></tr>
<tr><td><em>see:</em></td><td>
<link anchor="cache-grammar">cacheGrammarFromParse</link>
</td></tr>
@@ -441,9 +443,9 @@
<anchor name="cache-grammar"/>
<table>
- <tr><td colspan="2"><em>cacheGrammarFromParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td colspan="2"><em>void cacheGrammarFromParse(const bool)</em></td></tr>
+ <tr><td><em>true:</em></td><td>Cache the grammar in the pool for re-use in subsequent parses.</td></tr>
+ <tr><td><em>false:</em></td><td>Do not cache the grammar in the pool</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
<tr><td><em>note:</em></td><td>The getter function for this method is called isCachingGrammarFromParse</td></tr>
<tr><td><em>note:</em></td><td> If set to true, the useCachedGrammarInParse
@@ -966,10 +968,11 @@
<anchor name="builder-use-cached"/>
<table>
<tr><td colspan="2"><em>http://apache.org/xml/features/validation/use-cachedGrammarInParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td><em>true:</em></td><td>Use cached grammar if it exists in the pool.</td></tr>
+ <tr><td><em>false:</em></td><td>Parse the schema grammar.</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
- <tr><td><em>note:</em></td><td></td></tr>
+ <tr><td><em>note:</em></td><td>If http://apache.org/xml/features/validation/cache-grammarFromParse is enabled,
+ this feature is set to true automatically. Any setting to this feature by the users is a no-op.</td></tr>
<tr><td><em>see:</em></td><td>
<link anchor="builder-cache-grammar">http://apache.org/xml/features/validation/cache-grammarFromParse</link>
</td></tr>
@@ -980,8 +983,8 @@
<anchor name="builder-cache-grammar"/>
<table>
<tr><td colspan="2"><em>http://apache.org/xml/features/validation/cache-grammarFromParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td><em>true:</em></td><td>Cache the grammar in the pool for re-use in subsequent parses.</td></tr>
+ <tr><td><em>false:</em></td><td>Do not cache the grammar in the pool</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
<tr><td><em>note:</em></td><td> If set to true, the http://apache.org/xml/features/validation/use-cachedGrammarInParse
is also set to true automatically.</td></tr>
1.5 +8 -6 xml-xerces/c/doc/program-deprecateddom.xml
Index: program-deprecateddom.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-deprecateddom.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- program-deprecateddom.xml 12 Jul 2002 14:50:29 -0000 1.4
+++ program-deprecateddom.xml 15 Jul 2002 14:06:58 -0000 1.5
@@ -509,11 +509,13 @@
<anchor name="use-cached"/>
<table>
- <tr><td colspan="2"><em>useCachedGrammarInParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td colspan="2"><em>void useCachedGrammarInParse(const bool)</em></td></tr>
+ <tr><td><em>true:</em></td><td>Use cached grammar if it exists in the pool.</td></tr>
+ <tr><td><em>false:</em></td><td>Parse the schema grammar.</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
<tr><td><em>note:</em></td><td>The getter function for this method is called isUsingCachedGrammarInParse</td></tr>
+ <tr><td><em>note:</em></td><td>If the grammar caching option is enabled, this option is set to true automatically.
+ Any setting to this option by the users is a no-op.</td></tr>
<tr><td><em>see:</em></td><td>
<link anchor="cache-grammar">cacheGrammarFromParse</link>
</td></tr>
@@ -523,9 +525,9 @@
<anchor name="cache-grammar"/>
<table>
- <tr><td colspan="2"><em>cacheGrammarFromParse</em></td></tr>
- <tr><td><em>true:</em></td><td></td></tr>
- <tr><td><em>false:</em></td><td></td></tr>
+ <tr><td colspan="2"><em>void cacheGrammarFromParse(const bool)</em></td></tr>
+ <tr><td><em>true:</em></td><td>cache the grammar in the pool for re-use in subsequent parses.</td></tr>
+ <tr><td><em>false:</em></td><td>Do not cache the grammar in the pool</td></tr>
<tr><td><em>default:</em></td><td> false </td></tr>
<tr><td><em>note:</em></td><td>The getter function for this method is called isCachingGrammarFromParse</td></tr>
<tr><td><em>note:</em></td><td> If set to true, the useCachedGrammarInParse
1.26 +12 -2 xml-xerces/c/doc/migration.xml
Index: migration.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/migration.xml,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- migration.xml 12 Jul 2002 14:50:50 -0000 1.25
+++ migration.xml 15 Jul 2002 14:06:58 -0000 1.26
@@ -262,7 +262,16 @@
</ul>
<li>To support Preparsing Grammar and Grammar Caching, the following are added:</li>
<ul>
- <li></li>
+ <li>XercesDOMParser/DOMParser/SAXParser functions loadGrammar, resetCachedGrammarPool,
+ cacheGrammarFromParse, isCachingGrammarFromParse, useCachedGrammarInParse,
+ isUsingCachedGrammarInParse.</li>
+ <li>SAX2XMLReader functions loadGrammar, resetCachedGrammarPool, and will recognize the features
+ http://apache.org/xml/features/validation/cache-grammarFromParse and
+ http://apache.org/xml/features/validation/use-cachedGrammarInParse.</li>
+ </ul>
+ <li>To support access to Grammar info, the following are added:</li>
+ <ul>
+ <li>XercesDOMParser/DOMParser/SAXParser/SAX2XMLReader functions getRootGrammar, getGrammar, getURIText.</li>
</ul>
</ul>
</s4>
@@ -279,10 +288,11 @@
Users should now use the "Grammar Caching" feature as described in
<link anchor="Reuse">Reuse Grammar becomes Grammar Caching</link>.</li>
<ul>
- <li>(in SAXParser, DOMParser, and XercesDOMParser) </li>
+ <li>(in Parser, SAXParser, DOMParser, and XercesDOMParser) </li>
<li>parse(const InputSource& source, const bool reuseGrammar = false);</li>
<li>parse(const XMLCh* const systemId, const bool reuseGrammar = false);</li>
<li>parse(const char* const systemId, const bool reuseGrammar = false);</li>
+ <li>(in SAXParser, DOMParser, and XercesDOMParser) </li>
<li>parseFirst(const InputSource& source, XMLPScanToken& toFill, const bool reuseGrammar = false);</li>
<li>parseFirst(const XMLCh* const systemId, XMLPScanToken& toFill, const bool reuseGrammar = false);</li>
<li>parseFirst(const char* const systemId, XMLPScanToken& toFill, const bool reuseGrammar = false);</li>
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org