[saxdotnet-devel] Discussion Status 2
Brought to you by:
jeffrafter,
kwaclaw
From: Karl W. <ka...@wa...> - 2005-01-14 17:11:49
|
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 |