Thread: [bvalid-codewatch] SF.net SVN: bvalid: [22] trunk/src/doc

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 22
Author:   cwilper
Date:     2006-05-01 09:11:23 -0700 (Mon, 01 May 2006)
ViewCVS:  http://svn.sourceforge.net/bvalid/?rev=22&view=rev

Log Message:
-----------
more docs

Modified Paths:
--------------
    trunk/src/doc/index.html
    trunk/src/java/net/sf/bvalid/ValidatorException.java
Modified: trunk/src/doc/index.html
===================================================================

--- trunk/src/doc/index.html	2006-05-01 12:15:11 UTC (rev 21)
+++ trunk/src/doc/index.html	2006-05-01 16:11:23 UTC (rev 22)
@@ -22,12 +22,16 @@
         
     <ol>
 		<li><a href="#intro">Introduction</a></li>
-		<li><a href="#api">The Java API</a></li>
-		<li><a href="#cmdline">The Unix/Windows Command-Line Utility</a></li>
+		<li><a href="#inst">Downloading and Installing</a></li>
+		<li><a href="#api">API Documentation</a></li>
+		<li><a href="#cmdline">Command-Line Utility</a></li>
+		<li><a href="#issues">Known Issues</a></li>
     </ol>
     </div>
 </div>
 
+<p>&nbsp;</p>
+
 <div class="sec2">
   <h2><a name="intro">1. Introduction</a></h2>
   <p>
@@ -35,22 +39,163 @@
     It defines and implements several interfaces to make validation flexible
     and consistent across schema languages.
   </p>
-<!--      <div class="code"><pre>C:\fedora-2.1.1&gt;<b> fedora-setup no-ssl-authenticate-apim</b></pre></div> -->
+  <p>
+    Distinguishing features:
+    <ul>
+      <li> Implements a persistent schema file cache</li>
+      <li> Works with pluggable schema resolvers / catalogs</li>
+      <li> Wraps existing, quality validation libraries rather than implementing its own</li>
+    </ul>
+  </p>
 </div>
 
+<p>&nbsp;</p>
+
 <div class="sec2">
-  <h2><a name="api">2. The Java API</a></h2>
+  <h2><a name="api">2. Downloading and Installing</a></h2>
   <p>
-    The main interface you work with is the <code>Validator</code>.
+    The latest distribution (source and binary) can be downloaded from
+    <a href="http://www.sf.net/projects/bvalid">http://www.sf.net/projects/bvalid</a>
   </p>
+  <p>
+    After unzipping the binary distribution, you should be able to use the 
+    <code>bvalid</code> <a href="#cmdline">command-line utility</a> right away.
+  </p>
+  <p>
+    To begin using bvalid in your own projects, you'll need the 
+    following jars (included) in your CLASSPATH:
+    <ul>
+      <li> <b>bvalid.jar</b> - the BValid API</li>
+      <li> lib/<b>commons-httpclient-2.0.1.jar</b> - for resolving schemas via http</li>
+      <li> lib/<b>commons-logging.jar</b> - for logging (required by commons-httpclient)</li>
+      <li> lib/<b>log4j-1.2.8.jar</b> - for logging</li>
+      <li> lib/<b>xercesImpl.jar</b> - for XML parsing and XSD validation</li>
+      <li> lib/<b>xml-apis.jar</b> - for XML parsing</li>
+    </ul>
+  </p>
 </div>
 
+<p>&nbsp;</p>
+
 <div class="sec2">
-  <h2><a name="cmdline">3. The Unix/Windows Command-Line Utility</a></h2>
+  <h2><a name="api">3. API Documentation</a></h2>
   <p>
+    The main interface you work with is the <a href="api/net/sf/bvalid/Validator.html">Validator</a>.  Once you have obtained an instance from the <a href="api/net/sf/bvalid/ValidatorFactory.html">ValidatorFactory</a>, you can use it to validate any number of XML documents from any number of concurrent threads.  
+    </p>
+<p>
+  To become familar with the API, see the examples below, 
+  then check out the <a href="api/index.html">API Javadocs</a> 
+  for more detailed information.
+</p>
+  <p>
+    The following example uses a validator without any special configuration.
+  </p>
+  <div class="code"><pre>
+Validator v = ValidatorFactory.getValidator(SchemaLanguage.XSD, null);
+
+try {
+    File doc = new File("mydoc.xml");
+    v.validate(new FileInputStream(doc));
+    System.out.println("Validation SUCCESSFUL!");
+} catch (ValidationException e) {
+    System.out.println("Validation FAILED: " + e.getMessage());
+    if (e.getCause() != null) {
+        e.getCause().printStackTrace();
+    }
+}
+</pre></div>
+  <p>
+    This next example uses a validator that automatically caches
+    schema files to disk, and keeps parsed grammars in memory for re-use.
+  </p>
+  <div class="code"><pre>
+File cacheDir = new File("mySchemaCache");
+cacheDir.mkdirs();
+
+Map opts = new HashMap();
+opts.put(ValidatorOption.CACHE_PARSED_GRAMMARS, "true");
+
+Validator v = ValidatorFactory.getValidator(SchemaLanguage.XSD, 
+                                            cacheDir,
+                                            opts);
+
+try {
+    File doc = new File("mydoc.xml");
+    v.validate(new FileInputStream(doc));
+    System.out.println("Validation SUCCESSFUL!");
+} catch (ValidationException e) {
+    System.out.println("Validation FAILED: " + e.getMessage());
+    if (e.getCause() != null) {
+        e.getCause().printStackTrace();
+    }
+}
+</pre></div>
+  <p>
+    The final example, below, is more advanced.  It demonstrates using a
+    <a href="api/net/sf/bvalid/locator/SchemaLocator.html">SchemaLocator</a> backed 
+    by a pre-populated, memory-based 
+    <a href="api/net/sf/bvalid/catalog/SchemaCatalog.html">SchemaCatalog</a>.
+    It also instructs the validator NOT to fail if the instance document
+    references a schema that isn't in the catalog.
+    This effectively causes the validator to ONLY use our local schema 
+    copies (when referenced), and to skip validation for parts of the 
+    document that point to other schemas.
+  </p>
+  </p>
+  <div class="code"><pre>
+File schema1 = new File("my-schema1.xsd");
+File schema2 = new File("my-schema2.xsd");
+
+SchemaCatalog catalog = new MemorySchemaCatalog();
+catalog.put("http://example.org/schema1.xsd", new FileInputStream(schema1));
+catalog.put("http://example.org/schema2.xsd", new FileInputStream(schema2));
+
+SchemaLocator locator = new CatalogSchemaLocator(catalog);
+
+Map opts = new HashMap();
+opts.put(ValidatorOption.CACHE_PARSED_GRAMMARS, "true");
+opts.put(ValidatorOption.FAIL_ON_MISSING_REFERENCED, "false");
+
+Validator v = ValidatorFactory.getValidator(SchemaLanguage.XSD, 
+                                            locator,
+                                            opts);
+try {
+    File doc = new File("mydoc.xml");
+    v.validate(new FileInputStream(doc));
+    System.out.println("Validation SUCCESSFUL!");
+} catch (ValidationException e) {
+    System.out.println("Validation FAILED: " + e.getMessage());
+    if (e.getCause() != null) {
+        e.getCause().printStackTrace();
+    }
+}
+</pre></div>
+
+    
+</div>
+
+<p>&nbsp;</p>
+
+<div class="sec2">
+  <h2><a name="cmdline">4. Command-Line Utility</a></h2>
+  <p>
     The <code>bvalid</code> command-line utility is a simple application of the API that
-    can be used for validating a single XML document at a time.
+    can be used to validate a single XML document at a time.
   </p>
+  <p>
+    To use it, 
+    change to the directory where the BValid binary distribution has been installed,
+    and type <code><b>bvalid</b></code>.  If you want to run it from any
+    directory, set the <code>BVALID_HOME</code> environment variable to the installation
+    directory, then add it to your <code>PATH</code>.
+  </p>
+  <p>
+    Note: In Unix, you will need to make the bvalid script executable before running
+    it.  This can be done with <code><b>chmod 755 bvalid</b></code>
+  </p>
+  <p>
+    Running <code><b>bvalid -h</b></code> displays the following usage information.
+  </p>
   <div class="code"><pre>Usage: bvalid [OPTIONS] LANG XMLFILE
    Or: bvalid --version
    Or: bvalid --help
@@ -71,6 +216,22 @@
   -h, --help             Print help and exit (exclusive option)</pre></div>
 </div>
 
+<p>&nbsp;</p>
+
+<div class="sec2">
+  <h2><a name="issues">5. Known Issues</a></h2>
+  <ul>
+  <li>
+    The present version only performs <a href="http://www.w3.org/XML/Schema">W3C Schema</a> validation.  Future
+    versions will also support <a href="http://www.schematron.com/">Schematron</a> 
+    and <a href="http://www.relaxng.org/">Relax NG</a> validation.
+  </li>
+    <li> <code>ValidationException</code> isn't clear about how multiple validation errors are reported.</li>
+    <li> Should the API include more direct support for schema whitelisting?  
+         Currently this is possible by writing your own SchemaLocator.</li>
+  </ul>
+</div>
+
 <div id="footer">
     <div id="copyright">
       Copyright &#xA9; 2006

Modified: trunk/src/java/net/sf/bvalid/ValidatorException.java
===================================================================
--- trunk/src/java/net/sf/bvalid/ValidatorException.java	2006-05-01 12:15:11 UTC (rev 21)
+++ trunk/src/java/net/sf/bvalid/ValidatorException.java	2006-05-01 16:11:23 UTC (rev 22)
@@ -1,7 +1,7 @@
 package net.sf.bvalid;
 
 /**
- * Signals an error not directly related to validation.
+ * Superclass for all BValid-generated exceptions.
  *
  * @author cw...@cs...
  */


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



