mcs/class/Commons.Xml.Relaxng/README

   1 * Commons.Xml.Relaxng.dll\r
   2 \r
   3 ** Commons.Xml.Relaxng\r
   4 \r
   5 *** Introduction\r
   6 \r
   7   RelaxngValidatingReader is an implementation to validate XML with RELAX NG\r
   8   grammar. You can use full standard grammar components with it.\r
   9 \r
  10   Currently it supports both xml syntax and compact syntax.\r
  11 \r
  12   It supports RELAX NG predefined datatypes and XML Schema datatypes (its\r
  13   DatatypeLibrary is http://www.w3.org/2001/XMLSchema-datatypes ).\r
  14 \r
  15   All classes which is expected to use are in namespace Commons.Xml.Relaxng,\r
  16   except for Commons.Xml.Relaxng.Rnc.RncParser class (which is used to parse\r
  17   compact syntax).\r
  18   There is another namespace Commons.Xml.Relaxng.Derivative which is not\r
  19   expected to be used in users custom classes, though the classes are public\r
  20   as yet.\r
  21 \r
  22 \r
  23 *** Grammar Object Model\r
  24 \r
  25   RELAX NG grammar structure is represented in abstract RelaxngPattern class\r
  26   and its derivations. The easiest way to get this instance is to use\r
  27   static Read() method of RelaxngPattern class:\r
  28 \r
  29         RelaxngPattern pattern = RelaxngPattern.Read (\r
  30                 new XmlTextReader ("relaxng.rng");\r
  31 \r
  32   You can also use RelaxngPattern class to reuse grammar instance, as\r
  33   already described (see Grammar Object Model).\r
  34 \r
  35   And also, RelaxngGrammar and its contents can be created with managed code\r
  36   like System.Xml.Schema.XmlSchema.\r
  37 \r
  38 \r
  39 *** Compact Syntax Support\r
  40 \r
  41   Commons.Xml.Relaxng.dll also supports RELAX NG Compact Syntax. To parse\r
  42   compact syntax file, use Commons.Xml.Relaxng.Rnc.RncParser class:\r
  43 \r
  44         RncParser parser = new RncParser (new NameTable ());\r
  45         TextReader source = new StreamReader ("relaxng.rnc");\r
  46         RelaxngGrammar grammar = parser.Parse (source);\r
  47 \r
  48 \r
  49 *** Validating Reader usage\r
  50 \r
  51   RelaxngValidatingReader is used to validate XML document with RELAX NG\r
  52   grammar. The usage is simple:\r
  53 \r
  54         XmlReader instance = new XmlTextReader ("instance.xml");\r
  55         XmlReader grammar = new XmlTextReader ("my.rng");\r
  56         RelaxngValidatingReader reader = \r
  57                 new RelaxngValidatingReader (instance, grammar);\r
  58 \r
  59   Then Read() method (and other reading methods such as ReadElementString())\r
  60   reads the instance, validating with the supplied grammar.\r
  61 \r
  62 \r
  63 *** Datatype support\r
  64 \r
  65   Commons.Xml.Relaxng now supports custom datatype library. There are two \r
  66   classes from which you have to write classes derived.\r
  67 \r
  68   <ul>\r
  69         * RelaxngDatatype: it represents the actual data type\r
  70 \r
  71         * RelaxngDatatypeProvider: it provides the way to get RelaxngDatatype from QName and parameters\r
  72   </ul>\r
  73 \r
  74   RelaxngDatatype class has Parse() method which is used for validation.\r
  75   Basically RelaxngValidatingReader is only aware of that if the typed\r
  76   elements or attributes are parsable (you can override IsValid() method\r
  77   to change this behavior) using Parse() method for each datatype.\r
  78 \r
  79   To enable custom datatype support, first you have to implement concrete\r
  80   RelaxngDatatype implementations (it only requires to override Parse(), \r
  81   Name and NamespaceURI) and then RelaxngDatatypeProvider implementations\r
  82   (only GetDatatype() is required) to return the datatypes you implemented\r
  83   as above.\r
  84 \r
  85   Basically RelaxngDatatypeProvider is designed to allow to contain \r
  86   datatypes in different namespaces (e.g. supporting both XML schema\r
  87   datatypes and default namespace types). You can also use \r
  88   RelaxngMergedProvider class to combine existing two or more datatype\r
  89   providers. However, for ease of datatype search, it is indexed by the\r
  90   namespace URI (if you want to mix namespace-overrapped providers, you can\r
  91   implement your own merging provider). \r
  92 \r
  93 \r
  94 *** Known bugs\r
  95 \r
  96   RELAX NG implementation should mostly work fine. A known problem is:\r
  97 \r
  98         - URI string check is not strictly done; especially it does not check\r
  99           things described in XLink section 5.4.\r
 100 \r
 101 ** NvdlValidatingReader\r
 102 \r
 103 *** NVDL\r
 104 \r
 105         NvdlValidatingReader is an implementation of ISO DSDL Part 4\r
 106         Namespace-based Validation Dispatching Language (NVDL) which is\r
 107         now FDIS.\r
 108         http://www.jtc1sc34.org/repository/0694c.htm\r
 109 \r
 110         NOTE: It is still "untested" implementation and may have limitations\r
 111         and problems.\r
 112 \r
 113         By default, NvdlValidatingReader supports RELAX NG, RELAX NG Compact\r
 114         syntax, W3C XML Schema and built-in NVDL validations.\r
 115 \r
 116 *** Usage\r
 117 \r
 118         1) Using built-in RELAX NG support.\r
 119 \r
 120         NvdlRules rules = NvdlReader.Read (\r
 121                 new XmlTextReader ("xhtml2-xforms.nvdl"));\r
 122         XmlReader vr = new NvdlValidatingReader (\r
 123                 new XmlTextReader ("index.html"), rules);\r
 124 \r
 125         static NvdlReader.Read() method reads argument XmlReader and return\r
 126         NvdlRules instance.\r
 127 \r
 128         NvdlValidatingReader is instantiated from a) XmlReader to be validated,\r
 129         and b) NvdlRules as validating NVDL script.\r
 130 \r
 131         2) custom validation support\r
 132 \r
 133         NvdlConfig config = new NvdlConfig ();\r
 134         config.AddProvider (myOwnSchematronProvider); // [*1]\r
 135         config.AddProvider (myOwnExamplotronProvider);\r
 136         NvdlRules rules = NvdlReader.Read (\r
 137                 new XmlTextReader ("myscript.nvdl"));\r
 138         XmlReader vr = new NvdlValidatingReader (\r
 139                 new XmlTextReader ("myinstance.xml"), rules, config);\r
 140 \r
 141         NvdlConfig is here used to support "custom validation provider". In\r
 142         NVDL script, there could be any schema language referenced. I'll\r
 143         describe what validation provider is immediately later.\r
 144 \r
 145         [*1] Of course Schematron should receive its input as XPathNavigator\r
 146         or IXPathNavigable, but we could still use ReadSubtree() in .NET 2.0.\r
 147         Our XPathNavigatorReader (implementation of ReadSubtree()) can be\r
 148         easily modified and used in 1.x code base.\r
 149 \r
 150 *** NvdlValidationProvider\r
 151 \r
 152         To support your own validation language, you have to design your\r
 153         own extension to NvdlValidationProdiver type.\r
 154 \r
 155         Abstract NvdlValidationProvider should implement at least one of\r
 156         the virtual methods below:\r
 157 \r
 158                 - CreateValidatorGenerator (NvdlValidate validate,\r
 159                         string schemaType,\r
 160                         NvdlConfig config)\r
 161                 - CreateValidatorGenerator (XmlReader schema,\r
 162                         NvdlConfig config)\r
 163 \r
 164         Each of them returns NvdlValidatorGenerator implementation (will\r
 165         describe later).\r
 166 \r
 167         The first one receives MIME type (schemaType) and "validate" NVDL\r
 168         element. If you don't override it, it treats only "*/*-xml" and thus\r
 169         creates XmlReader from either schema attribute or schema element\r
 170         and passes it to another CreateValidatorGenerator() overload.\r
 171         If this (possibly overriden) method returns null, then this validation\r
 172         provider does not support the MIME type or the schema document.\r
 173 \r
 174         The second one is a shorthand method to handle "*/*-xml". By default\r
 175         it just returns null.\r
 176         \r
 177         Most of validation providers will only have to override the second\r
 178         overload. Few providers such as RELAX NG Compact Syntax support will\r
 179         have to overide the first overload.\r
 180 \r
 181 *** NvdlValidatorGenerator\r
 182 \r
 183         Abstract NvdlValidatorGenerator.CreateValidator() method is designed\r
 184         to create XmlReader from input XmlReader.\r
 185 \r
 186         For example, we have NvdlXsdValidatorGenerator class. It internally\r
 187         uses XmlValidatingReader which takes XmlReader as its constructor\r
 188         parameter.\r
 189 \r
 190         An instance of NvdlValidatorGenerator will be created for each \r
 191         "validate" element in the NVDL script. When the validate element\r
 192         applies (for a PlanElem), it creates validator XmlReader.\r