Towards a Declarative SAX Framework : Part 1 - A Simple SAX-to-C#-Mapping

#region Copyright
/*********************************************************************************
 * Copyright (c) 2004 by Martin Friedrich										 *
 * Permission to freely distribute, modify and compile these sources and		 *
 * binaries as long as this copyright notice is included.						 *
 * Use of code on your risk!													 *
 * *******************************************************************************/
#endregion

using System;

namespace SaxParserSupport
{
	/// <summary>
	/// Defines the base API for XML elements.
	/// </summary>
	public interface XMLSimpleElement
	{
		/// <summary>
		/// Sets the value of the given attribute.
		/// </summary>
		/// <param name="name">The name of the attribute to be set as given in the
		/// XML content</param>
		/// <param name="value">The new value of the attribute as given in the XML
		/// content</param>
		/// <remarks>As of now, property names are matched against possible namespace
		/// alias, not the actual namespaces.</remarks>
		void setAttribute( string name, string value );

		/// <summary>
		/// Returns the <tt>XMLElement</tt> instance repesenting the parent XML element,
		/// if any. It is <tt>null</tt> for instances of <tt>XMLDocument</tt> or if a
		/// <tt>XMLSimpleElement</tt> is removed from it's parent.
		/// </summary>
		/// <returns>The <tt>XMLElement</tt> instance that represents the parent XML element
		/// or <tt>null</tt></returns>
		XMLElement getOwner();

		/// <summary>
		/// Sets the <tt>XMLElement</tt> instance that represents the parent XML element
		/// </summary>
		/// <param name="se">The <tt>XMLElement</tt> instance to set as parent</param>
		void setOwner( XMLElement se );

		/// <summary>
		/// Returns the qualified tag name of the XML element represented by this
		/// <tt>XMLSimpleElement</tt> instance.
		/// </summary>
		/// <returns>The qualified tag name</returns>
		string getName();

		/// <summary>
		/// Sets the tag name of the <tt>XMLSimpleElement</tt> instance
		/// </summary>
		/// <param name="n">The qualified tag name</param>
		void setName( string n );

		/// <summary>
		/// Writes this <tt>XMLSimpleElement</tt> instance to a stream.
		/// </summary>
		/// <remarks>
		/// This method may throw any exception related to stream output
		/// </remarks>
		/// <param name="ostr">The stream to be used for output</param>
		void write( System.IO.StreamWriter ostr );

		/// <summary>
		/// Callback to be executed on encountering the end of the element 
		/// represented by this <i>XMLSimpleElement</i> instance
		/// </summary>
		/// <param name="owner">The <tt>XMLElement</tt> instance being the parent
		/// of this instance. For the root XML element <tt>owner</tt> is 
		/// <tt>null</tt></param>
		void onElementEnd( SaxParserSupport.XMLElement owner );

	}
}