Menu
▾
▴
[mvp-xml-cvs] Common/v2/src/Xsl XslReader.cs,1.4,1.5
|
From: Oleg T. <he...@us...> - 2005-11-14 16:57:38
|
Update of /cvsroot/mvp-xml/Common/v2/src/Xsl In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv5218/v2/src/Xsl Modified Files: XslReader.cs Log Message: Index: XslReader.cs =================================================================== RCS file: /cvsroot/mvp-xml/Common/v2/src/Xsl/XslReader.cs,v retrieving revision 1.4 retrieving revision 1.5 diff -u -d -r1.4 -r1.5 --- XslReader.cs 13 Nov 2005 22:10:31 -0000 1.4 +++ XslReader.cs 14 Nov 2005 16:57:30 -0000 1.5 @@ -18,18 +18,54 @@ /// architectural and performance reasons the <see cref="XslCompiledTransform"/> /// class doesn't support transforming to an <see cref="XmlReader"/> as obsolete /// <see cref="XslTransform"/> class did and XslReader's goal is to - /// supplement such functionality.</para> + /// supplement such functionality.</para> + /// </summary> + /// <remarks> /// <para>XslReader can work in a singlethreaded (fully buffering) or a - /// multithreaded mode. In a singlethreaded mode XslReader runs an XSL transformation + /// multithreaded mode.</para> + /// <para>In a multithreaded mode XslReader runs an XSL transformation + /// in a separate dedicated thread. XSLT output is being recorded into a buffer + /// and once the buffer is full, transformation thread gets suspended. In a main + /// thread XslReader reads recorded XSLT output from a buffer as a client calls + /// XslReader methods. Whenever the buffer is read, the transformation thread + /// is resumed to produce next portion of an XSLT output.<br/> + /// In effect that means that an XSL transformation happens on demand portion by + /// portion as a client calls XslReader methods. In terms of memory footprint + /// that means that at any time at most buffer size of XSLT output is buffered.</para> + /// <para>In a singlethreaded mode XslReader runs an XSL transformation /// to the end and records full XSLT output into a buffer (using effective - /// binary representation). After that it reads the buffer when a client calls XslReader - /// methods. In effect that means that in this mode before first call to the + /// binary representation though). After that it reads the buffer when a client + /// calls XslReader methods. So in this mode before first call to the /// XslReader.Read() method returns, XSL transformation is over and XSLT output - /// is buffered internally as a whole.<br/> - /// In a multithreaded mode XslReader runs XSL transformation in a separate thread, - /// which + /// is buffered internally as a whole. /// </para> - /// </summary> + /// <para>By default XslReader works in a multithreaded mode. You can choose the mode + /// and the buffer size using <c>multiThread</c> and <c>initialBufferSize</c> arguments + /// when instantiating XslReader object.</para> + /// <para>XslReader designed to be reused. Just provide another inoput XML or XSLT + /// stylesheet, start transformation and read the output. If the <c>StartTransform()</c> + /// method is called when previous + /// transformation isn't over yet, it will be aborted, the buffer cleaned and + /// the XslReader object will be reset to an initial state automatically.</para> + /// <para>XslReader is not thread safe, keep separate instances of the XslReader + /// for each thread.</para> + /// </remarks> + /// <example> + /// <para>Here is an example of using XslReader class. First you need to create + /// an <see cref="XslCompiledTransform"/> object and load XSLT stylesheet you want to + /// execute. Then prepare XML input as <see cref="XmlInput"/> object providing + /// XML source in a form of URI, <see cref="Stream"/>, <see cref="TextReader"/>, + /// <see cref="XmlReader"/> or <see cref="IXPathNavigable"/> along with an optional + /// <see cref="XmlResolver"/> object, which will be used to resolve URIs for + /// the XSLT document() function calls.<br/> + /// After that create XslReader instance optionally choosing multithreaded or + /// singlethreaded mode and initial buffer size.<br/> + /// Finally start transformation by calling <c>StartTransform()</c> method and then + /// read transformation output via XslReader's object, which implements + /// <see cref="XmlReader"/> API. + /// + /// </para> + /// </example> public class XslReader : XmlReader { static string NsXml = "http://www.w3.org/XML/1998/namespace"; static string NsXmlNs = "http://www.w3.org/2000/xmlns/"; @@ -54,6 +90,16 @@ XmlInput defaulDocument; XsltArgumentList args; + /// <summary> + /// Creates new XslReader instance with given <see cref="XslCompiledTransform"/>, + /// mode (multithreaded/singlethreaded) and initial buffer size. The buffer will be + /// expanded if necessary to be able to store any element start tag with all its + /// attributes. + /// </summary> + /// <param name="xslTransform">Loaded <see cref="XslCompiledTransform"/> object</param> + /// <param name="multiThread">Defines in which mode (multithreaded or singlethreaded) + /// this instance of XslReader will operate</param> + /// <param name="initialBufferSize">Initial buffer size</param> public XslReader(XslCompiledTransform xslTransform, bool multiThread, int initialBufferSize) { this.xslCompiledTransform = xslTransform; this.multiThread = multiThread; @@ -66,9 +112,27 @@ SetUndefinedState(ReadState.Initial); } + /// <summary> + /// Creates new XslReader instance with given <see cref="XslCompiledTransform"/>, + /// operating in a multithreaded mode and having default initial buffer size. + /// </summary> + /// <param name="xslTransform">Loaded <see cref="XslCompiledTransform"/> object</param> public XslReader(XslCompiledTransform xslTransform) : this(xslTransform, true, defaultBufferSize) { } - public XmlReader Transform(XmlInput input, XsltArgumentList args) { + /// <summary> + /// Starts XSL transformation of given <see cref="XmlInput"/> object with + /// specified <see cref="XsltArgumentList"/>. After this method returns + /// you can read the transformation output out of XslReader object via + /// standard <see cref="XmleRader"/> methods such as Read() or MoveXXX(). + /// </summary> + /// <remarks>If the <c>StartTransform()</c> method is called when previous + /// transformation isn't over yet, it will be aborted, buffer cleaned and + /// XslReader object reset to an initial state automatically.</remarks> + /// <param name="input">An input XML to be transformed</param> + /// <param name="args">A collection of global parameter values and + /// extension objects.</param> + /// <returns></returns> + public XmlReader StartTransform(XmlInput input, XsltArgumentList args) { this.defaulDocument = input; this.args = args; Start(); @@ -142,11 +206,22 @@ } } + /// <summary> + /// Loaded <see cref="XslCompiledTransform"/> object, which is used + /// to run XSL transformations. You can reuse XslReader for running + /// another transformation by replacing <see cref="XslCompiledTransform"/> + /// object. + /// </summary> public XslCompiledTransform XslCompiledTransform { get { return this.xslCompiledTransform; } set { this.xslCompiledTransform = value; } } + /// <summary> + /// Initial buffer size. The buffer will be + /// expanded if necessary to be able to store any element start tag with + /// all its attributes. + /// </summary> public int InitialBufferSize { get { return initialBufferSize; } set { initialBufferSize = value; } @@ -177,7 +252,10 @@ } return true; } - + + /// <summary> + /// See <see cref="XmlReader.Read()"/>. + /// </summary> public override bool Read() { // Leave Current node switch (nodeType) { @@ -262,25 +340,40 @@ return true; } + /// <summary>See <see cref="XmlReader.AttributeCount"/>.</summary> public override int AttributeCount { get { return attCount; } } // issue: What should be BaseURI in XslReader? xslCompiledTransform.BaseURI ? + /// <summary>See <see cref="XmlReader.BaseURI"/>.</summary> public override string BaseURI { get { return string.Empty; } } + /// <summary>See <see cref="XmlReader.NameTable"/>.</summary> public override XmlNameTable NameTable { get { return nameTable; } } + /// <summary>See <see cref="XmlReader.Depth"/>.</summary> public override int Depth { get { return depth; } } + /// <summary>See <see cref="XmlReader.EOF"/>.</summary> public override bool EOF { get { return ReadState == ReadState.EndOfFile; } } + /// <summary>See <see cref="XmlReader.HasValue"/>.</summary> public override bool HasValue { get { return 0 != (/*HasValueBitmap:*/0x2659C & (1 << (int)nodeType)); } } + /// <summary>See <see cref="XmlReader.NodeType"/>.</summary> public override XmlNodeType NodeType { get { return nodeType; } } // issue: We may want return true if element doesn't have content. Iteresting to know what + /// <summary>See <see cref="XmlReader.IsEmptyElement"/>.</summary> public override bool IsEmptyElement { get { return false; } } + /// <summary>See <see cref="XmlReader.LocalName"/>.</summary> public override string LocalName { get { return qname.Local; } } + /// <summary>See <see cref="XmlReader.NamespaceURI"/>.</summary> public override string NamespaceURI { get { return qname.NsUri; } } + /// <summary>See <see cref="XmlReader.Prefix"/>.</summary> public override string Prefix { get { return qname.Prefix; } } + /// <summary>See <see cref="XmlReader.Value"/>.</summary> public override string Value { get { return value; } } + /// <summary>See <see cref="XmlReader.ReadState"/>.</summary> public override ReadState ReadState { get { return readState; } } + /// <summary>See <see cref="XmlReader.Close()"/>.</summary> public override void Close() { SetUndefinedState(ReadState.Closed); } + /// <summary>See <see cref="XmlReader.GetAttribute(int)"/>.</summary> public override string GetAttribute(int i) { if (IsInsideElement()) { if (0 <= i && i < attCount) { @@ -323,6 +416,7 @@ } return 0; } + /// <summary>See <see cref="XmlReader.GetAttribute(string)"/>.</summary> public override string GetAttribute(string name) { int attNum = FindAttribute(name); if (attNum != 0) { @@ -330,6 +424,7 @@ } return null; } + /// <summary>See <see cref="XmlReader.GetAttribute(string, string)"/>.</summary> public override string GetAttribute(string name, string ns) { if (IsInsideElement()) { for (int i = 1; i <= attCount; i++) { @@ -343,7 +438,9 @@ } return null; } + /// <summary>See <see cref="XmlReader.LookupNamespace(string)"/>.</summary> public override string LookupNamespace(string prefix) { return scope.LookupNamespace(prefix); } + /// <summary>See <see cref="XmlReader.Close()"/>.</summary> public override bool MoveToAttribute(string name) { int attNum = FindAttribute(name); if (attNum != 0) { @@ -352,6 +449,7 @@ } return false; } + /// <summary>See <see cref="XmlReader.MoveToAttribute(int)"/>.</summary> public override void MoveToAttribute(int i) { if (IsInsideElement()) { if (0 <= i && i < attCount) { @@ -364,6 +462,7 @@ } throw new ArgumentOutOfRangeException("i"); } + /// <summary>See <see cref="XmlReader.MoveToAttribute(string, string)"/>.</summary> public override bool MoveToAttribute(string name, string ns) { if (IsInsideElement()) { for (int i = 1; i <= attCount; i ++) { @@ -401,6 +500,7 @@ break; } } + /// <summary>See <see cref="XmlReader.MoveToElement()"/>.</summary> public override bool MoveToElement() { if ( nodeType == XmlNodeType.Attribute || @@ -414,11 +514,13 @@ } return false; } + /// <summary>See <see cref="XmlReader.MoveToFirstAttribute()"/>.</summary> public override bool MoveToFirstAttribute() { ChangeDepthToElement(); attOffset = 0; return MoveToNextAttribute(); } + /// <summary>See <see cref="XmlReader.MoveToNextAttribute()"/>.</summary> public override bool MoveToNextAttribute() { if (attOffset < attCount) { ChangeDepthToElement(); @@ -430,6 +532,7 @@ } return false; } + /// <summary>See <see cref="XmlReader.ReadAttributeValue()"/>.</summary> public override bool ReadAttributeValue() { if (nodeType == XmlNodeType.Attribute) { nodeType = XmlNodeType.Text; @@ -438,9 +541,12 @@ } return false; } + /// <summary>See <see cref="XmlReader.ResolveEntity()"/>.</summary> public override void ResolveEntity() { throw new InvalidOperationException(); } + /// <summary>See <see cref="XmlReader.XmlLang"/>.</summary> public override string XmlLang { get { return scope.Lang; } } + /// <summary>See <see cref="XmlReader.XmlSpace"/>.</summary> public override XmlSpace XmlSpace { get { return scope.Space; } } #endregion // XmlReader Implementation |
