[saxdotnet-devel] Discussion Status 2

[Karl W. <ka...@wa...>]

Another review of the current status for the various threads:
(only 3 participants so far)
When I mark an item/solution as accepted, please speak up
if you have objections.

  A) "Unifying" the core and extension interfaces:

  No opposition, seems accepted.

  B) Changing Exceptions in the API

  SaxNotSupportedException and SaxNotRecognizedException have been
  removed in favour of the built-in .NET exceptions ArgumentException
  and NotSupportedException. I assume this is accepted.

  C) Reducing the versioning / eliminating the Ixxx2 interfaces

  When unifying IAttributes and IAttributes2, the IsDeclared()
  methods have been removed in favour of an additional return value
  for GetType(). This value is UNDECLARED.

  Also, GetType() differentiates between NMTOKEN and ENUMERATION,
  adding the latter as another new return value .

  I assume this is accepted as well.

  D) Requiring EndDocument

  For the purpose of enabling content handler chains
  (filter pipelines), we should require that EndDocument()
  is always called when StartDocument() was called.
  However, this can be guaranteed only for in-process call-backs.
  Documentation has been updated, and I assume this is accepted.

  E) StartElement, when URI is not present

  We decided to follow what the standard NET libraries expect
  as an input for an URI, if the URI is supposed to be absent.
  It was found that many of them expect an empty string and not null.
  So, the solution proposed is to follow the Java API and require
  that a namespace URI has the value "" when a qualified name
  is not in any namespace. This applies to IAttributes.GetUri()
  and the URI arguments passed to Start/EndElement().
  As a similar consequence we require that the prefix argument
  passed to Start/EndPrefixMapping is "" for the default namespace.
  For the rest of the API, absence of a string parameter will still
  be indicated through a null reference. This is especially necessary
  for IDeclhandler.AttributeDecl(), where the value parameter has
  a defined meaning for "".
  Assuming acceptance.

  F) Merging the IXmlReaderControl with IXmlReader

  Some opposition from Elliotte, that is, 2:1 in favour of  adding
  Suspend/Resume/Abort() to IXmlReader. I propose we go with the merge
  and make these methods optional (allowed to throw NotSupportedException).
  However, the IXmlReader.Status property will be non-optional,
  as it is easy to implement. Still open, but I hope acceptance is not far.

  G) SAX holes

  - Max string length: String.Length is defined as int,
     not much we can do here.
  - Skipped entities in attribute values: possibility of
     marking spot in attribute value (at user option).
  I suggest we do nothing for this release, as the API
  changes might be invasive. Assuming acceptance.

  H) Replace is-standalone feature with ILocator member

  The is-standalone feature was removed and a new property was added
  to ILocator called EntityType. It is an enumeration of this type:

   public enum ParsedEntityType
   {
     /// <summary>Document entity without specified value for the standalone flag.</summary>
     Document,
     /// <summary>Document entity with standalone="no".</summary>
     NotStandalone,
     /// <summary>Document entity with standalone="yes".</summary>
     Standalone,
     /// <summary>External general entity.</summary>
     General,
     /// <summary>External parameter entity.</summary>
     Parameter
   }

   No discussion yet (but off-list agreement between Jeff and Karl).
   We might want to add a value of "Other" or "Unknown" for those
   cases where we are not actually parsing an XML document.

  I) Re-define what "parsing" means in SAX.

  This is a new issue that came up while discussing the fact that
  certain API members and/or names only make sense when parsing an actual
  XML document (ParseError, SaxParseException, IXmlReader.Parse(),
  ILocator.PublicId, ...). This puts unnecessary limitations on SAX event
  generation not based on parsing a document. We have two choices, rename
  and re-design  part of the SAX API, or re-define the meaning of parsing.
  Luckily, it seems that those API members that force a document interpretation
  allow for "optional" argument or return values.

  So, as a starting point this was proposed:

    "For the purpose of the SAX API we define "parsing" as
    generating a sequence of call-backs on SAX handler interfaces
    that represent a well-formed XML document. This applies even
    if no actual XML document is being processed."

  Jeff thinks it needs some refinement, and I asked him to refine ...
  I also think we should add this:

    Whenever the term "document" is used in SAX, it should be
    interpreted more generally as "source of well-formed SAX events".

  This would for instance make it unnecessary to add a new member
  (see above) to ParsedEntityType.

  SUMMARY

  So, we have F, H and I as open issues, but I think we are getting close.
  If anyone sees new issues, please come forward.


Karl