saxdotnet-devel — Development and API issues discussed here

Re: [Saxdotnet-devel] Reducing the versioning / eliminating the Ixxx2 interfaces

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

> Jeff Rafter wrote:
> 
> 
> > (1) Some implementations will not support the additional methods. Again, 
> > these extensions are not required by the XML Specification to be 
> > reported to the application. In such a case we will again turn to the 
> > SaxNotSupportedExcpetion. If someone attempts to access isDeclared for 
> > example and it is not supported by the implementation a 
> > SaxNotSupportedException should be thrown.
> 
> 
> Suggestion: drop isDeclared from Attributes/Attributes2 completely and 
> instead define a new "undeclared" value to be returned by getType for 
> undeclared attributes. I suspect this would have been in SAX/Java if 
> anyone had thought of it earlier; but the use cases that led to these 
> methods in Attributes2 weren't uncovered till later.

Hhmm, makes sense.

While we are at it: Why are enumerations reported as NMTOKEN in the Java API"
<quote>
  For an enumerated attribute that is not a notation, 
  the parser will report the type as "NMTOKEN".
</quote>

Why not use the type as it is declared? Or use the the term "ENUMERATION"?

> isSpecified is trickier, but I tend to think you should just add it to 
> the Attributes interface and require parsers to support it.

I guess that is possible, since a parser that does not read the DTD
will just always return true without misleading the user.

Karl

[Saxdotnet-devel] Merging the IXmlReaderControl with IXmlReader

[Jeff R. <je...@je...>]

Karl has proposed merging the IXmlReaderControl functionality into the 
IXmlReader. This would add a "Suspend" and "Resume" function to the core 
XmlReader. For implementations that do not support this behavior 
(AElfred) calling these methods would generate a NotSupportedException.

Additionally, a Status interface level property would be added to 
indicate the current read status. Although taken from the 
IXmlReaderControl interface, it is not optional, since it is easy to 
implement for any IXmlReader - it will just never return a value of 
XmlReaderStatus.Suspended for some IXmlReaders.

As the implementer of AElfred I see no problem with this...

Jeff Rafter

Re: [Saxdotnet-devel] Changing Exceptions in the API

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

> Currently in the .NET API there is redundancy wrt to exceptions:
> 
> (1) SaxNotSupportedException and NotSupportedException
> (2) SaxArgumentException and ArgumentException
> 
> Should these be removed in favor of the .NET equivalents?

I think there is actually no SAXArgumentException in the JAVA API.
So we can remove it without much discussion.

Mostly, .NET approaches exception handling differently.
There are no checked exceptions, the "best practice"
is to use the built-in exceptions, and only define
your own if you cannot find an existing exception
class that has adequate semantics.
A good explanation (vs. checked exceptions) is in this article:
http://www.artima.com/intv/handcuffs.html


In our case here one can argue that the built-in
NotSupportedException is meant to be used when
a method is not implemented, whereas the SAXNotSupportedException
is meant to be used for unsupported features and properties.

For symmetry with the SAXNotRecognizedException we
could therefore leave it in, but then we have the problem
that unsupported extension methods (like IAttribute.IsDeclared)
should rather throw a NotSupportedException.

Tough choice, since having both could be confusing.

Karl 

Re: [Saxdotnet-devel] StartElement, when URI is not present

[Elliotte H. <el...@me...>]

Jeff Rafter wrote:

> We have been discussing the various possibilities of enforcing a rule 
> about what to do when a URI is not present. For example consider this:
> 
> <foo></foo>
> 
> What should the StartElement call consist of?
> 
> QName : "foo"
> LocalName : "foo"
> Uri : null or string.Empty?


This really, really, really needs to be the empty string, unless null 
works very differently in C# than in Java. It's just incredibly useful 
to be able to assume the namespace URI (and other arguments to this 
method) are never null. I see this again and again in my SAX work. API 
quality wise, null should be avoided here.

> I am not saying that I am against String.Empty, but from
> a programming point of view it is simply a weaker choice.
> 
> - null indicates absence better than picking a special value.
> - what if an empty string ever got a special meaning for URIs?

It already has a special meaning for URIs and namespace URIs. There's 
approximately zero chance of this changing.

XML-wise these two elements are equivalent:

<data />
<data xmlns="" />

Unless you're prepared to use null for both of them, which I think would 
be harder for implementers, you need to pick the empty string here. 
Unlike SQL, XML namespaces do not distinguish between the empty string 
and no value. Namespaces in XML says, "The default namespace can be set 
to the empty string. This has the same effect, within the scope of the 
declaration, of there being no default namespace."

-- 
Elliotte Rusty Harold  el...@me...
XML in a Nutshell 3rd Edition Just Published!
http://www.cafeconleche.org/books/xian3/
http://www.amazon.com/exec/obidos/ISBN=0596007647/cafeaulaitA/ref=nosim

Re: [Saxdotnet-devel] StartElement, when URI is not present

[Jeff R. <li...@je...>]

I wanted to add that the outcome of this discussion will also affect the 
StartPrefixMapping calls. In the event of:

   <foo xmlns="http://www.example.org">

The "prefix" in the callback can either be null or string.empty.

Jeff

[Saxdotnet-devel] Changing Exceptions in the API

[Jeff R. <li...@je...>]

Currently in the .NET API there is redundancy wrt to exceptions:

(1) SaxNotSupportedException and NotSupportedException
(2) SaxArgumentException and ArgumentException

Should these be removed in favor of the .NET equivalents?

Thanks,
Jeff Rafter

Re: [Saxdotnet-devel] Reducing the versioning / eliminating the Ixxx2 interfaces

[Elliotte H. <el...@me...>]

Jeff Rafter wrote:


> (1) Some implementations will not support the additional methods. Again, 
> these extensions are not required by the XML Specification to be 
> reported to the application. In such a case we will again turn to the 
> SaxNotSupportedExcpetion. If someone attempts to access isDeclared for 
> example and it is not supported by the implementation a 
> SaxNotSupportedException should be thrown.


Suggestion: drop isDeclared from Attributes/Attributes2 completely and 
instead define a new "undeclared" value to be returned by getType for 
undeclared attributes. I suspect this would have been in SAX/Java if 
anyone had thought of it earlier; but the use cases that led to these 
methods in Attributes2 weren't uncovered till later.

isSpecified is trickier, but I tend to think you should just add it to 
the Attributes interface and require parsers to support it.

-- 
Elliotte Rusty Harold  el...@me...
XML in a Nutshell 3rd Edition Just Published!
http://www.cafeconleche.org/books/xian3/
http://www.amazon.com/exec/obidos/ISBN=0596007647/cafeaulaitA/ref=nosim

Re: [Saxdotnet-devel] "Unifying" the core and extension interfaces

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

> Jeff Rafter wrote:
> 
> 
> > What we do what to change is the clumsy mechanism for connecting 
> > extension interfaces to an IXmlReader. Currently this is done through 
> > the setproperty/getproperty mechanism. We propose to add new interface 
> > level property for LexicalHandler and DeclHandler (that will behave in 
> > the same way ContentHandler, ErrorHandler, etc, work).
> > 
> 
> By "interface level property" do you mean adding 
> setLexicalHandler/getLexicalHandler and setDeclHandler/getDeclHandler 
> methods?
> 
> Sorry if this is obvious to the .NET folks. I'm just not fully 
> conversant with the lingo yet.

Sort of. In C#, the get/set pair of accessors is replaced
by the syntactical construct of a "property":

public interface IXmlReader
{
  ...
  IContentHandler ContentHandler { get; set; }
  IDtdHandler DtdHandler { get; set; }
  ILexicalHandler LexicalHandler { get; set; }
  IDeclHandler DeclHandler { get; set; }
  ...
}

usage:
 
  IXmlReader reader;
  reader.ContentHandler = new MyContentHandler();
  reader.LexicalHandler = new MyLexicalHandler();

Karl

Re: [Saxdotnet-devel] "Unifying" the core and extension interfaces

[Jeff R. <li...@je...>]

> By "interface level property" do you mean adding 
> setLexicalHandler/getLexicalHandler and setDeclHandler/getDeclHandler 
> methods?

Yes. Except in the .NET version this is actually a class property so you 
would do something like:

IXmlReader xr;
ILexicalHadler myLexHandler;
xr.LexicalHandler = myLexHandler;

> Sorry if this is obvious to the .NET folks. I'm just not fully 
> conversant with the lingo yet.

I struggled over how to word "class level property" so that it didn't 
cause confusion... looks like a missed it by a hair.

Thanks,
Jeff Rafter

[Saxdotnet-devel] StartElement, when URI is not present

[Jeff R. <li...@je...>]

We have been discussing the various possibilities of enforcing a rule 
about what to do when a URI is not present. For example consider this:

<foo></foo>

What should the StartElement call consist of?

QName : "foo"
LocalName : "foo"
Uri : null or string.Empty?

The Java SAX API claims that string.Empty should be used:

   "The Namespace URI, or the empty string if the element has no
   Namespace URI or if Namespace processing is not being performed."
   (pointed out by Elliotte Harold)

but this is problemetized by additional wording which is not so clear:

   Code using element names would normally match first for a null URI,
   and if it's null then use qName otherwise use localName

   http://www.saxproject.org/?selected=namespaces

and further down:

   If the URI were the emtpy string, you would normally use the qName
   to identify attributes. So code looking at those attributes would
   normally match first for a null URI, and if it's null then use
   qName otherwise use the localName.

   (both pointed out by Karl)

In any event the SAX for .NET API needs to take a clear position and run 
with it. Currently it appears that Karl is leading the charge for going 
with null as the default value and I am pushing string.Empty. Here are 
some of our arguments:

Karl:
=====

I am not saying that I am against String.Empty, but from
a programming point of view it is simply a weaker choice.

- null indicates absence better than picking a special value.
- what if an empty string ever got a special meaning for URIs?

If we pick the emtpy string, then we do it for reasons
other than API quality. So, the way I see it, we have to
clarify how important Java compatibility is.

Jeff:
=====
All of the proposed changes pretty high level and fully backwards 
compatabile (with the exception of entityResolver)... the 
null/string.empty will require making changes to actual handler 
internals-- the guts of filters that people have written-- and it will 
be very very easy to miss when converting. If you don't port the 
entityReolver code you have from Java correctly you will get a compile 
time error, if you forget that Java mandated string.empty and the .NET 
version mandates null you will get a runtime error.


So to summarize: Karl is arguing for using null because it is a better 
API choice. Jeff is arguing for string.Empty because it is more 
compatabile with the Java version (though as Karl has argued, there is a 
high degree of incompatibility as it is already).

Thanks,
Jeff Rafter

Re: [Saxdotnet-devel] "Unifying" the core and extension interfaces

[Elliotte H. <el...@me...>]

Jeff Rafter wrote:


> What we do what to change is the clumsy mechanism for connecting 
> extension interfaces to an IXmlReader. Currently this is done through 
> the setproperty/getproperty mechanism. We propose to add new interface 
> level property for LexicalHandler and DeclHandler (that will behave in 
> the same way ContentHandler, ErrorHandler, etc, work).
> 

By "interface level property" do you mean adding 
setLexicalHandler/getLexicalHandler and setDeclHandler/getDeclHandler 
methods?

Sorry if this is obvious to the .NET folks. I'm just not fully 
conversant with the lingo yet.

-- 
Elliotte Rusty Harold  el...@me...
XML in a Nutshell 3rd Edition Just Published!
http://www.cafeconleche.org/books/xian3/
http://www.amazon.com/exec/obidos/ISBN=0596007647/cafeaulaitA/ref=nosim

[Saxdotnet-devel] Reducing the versioning / eliminating the Ixxx2 interfaces

[Jeff R. <li...@je...>]

Reducing the versioning / eliminating the Ixxx2 interfaces:
===========================================================

We are considering eliminating the versioning that exists in the API. As 
we are still early in the game and both implementations (Expat and 
AElfred) are active making such a change now seems plausible. We propose 
to eliminate the versioning by merging the Ixxx2 interfaces with the 
existing interfaces. This means, for example, merging the behavior of 
IAttributes2 with IAttributes and so on.

There are several problems that are created by doing this.

(1) Some implementations will not support the additional methods. Again, 
these extensions are not required by the XML Specification to be 
reported to the application. In such a case we will again turn to the 
SaxNotSupportedExcpetion. If someone attempts to access isDeclared for 
example and it is not supported by the implementation a 
SaxNotSupportedException should be thrown.

(2) In the case of IEntityResolver / IEntityResolver2, the resolveEntity 
function is duplicated. Because the implementation needs to know which 
function should be called (or worse both...) it is determined that the 
original resolveEntity signature be eliminated in favor of the newer 
signature from IEntityResolver2. So there will still be only one 
resolveEntity function and it would look like:

     InputSource ResolveEntity(string name,
                               string publicId,
                               string baseURI,
                               string systemId);


This will of course cause existing applications to fail. But, because 
this would be a compile time error the problem is mitigated.

(3) Modification to existing feature names for the Ixxx2 interfaces. 
Because the interfaces would no longer exist the feature names would 
become confusing. So we would change the feature names to:

    UseAttributes2Feature      --> AttributeDeclaredFeature
    UseLocator2Feature         --> XmlDeclFeature
    UseEntityResolver2Feature  --> UseExternalSubsetFeature

When the features are false the various extension callbacks (with the 
exception of the modified resolveEntity) would not be performed.

Thanks,
Jeff Rafter

[Saxdotnet-devel] "Unifying" the core and extension interfaces

[Jeff R. <li...@je...>]

"Unifying" the extensions and core interfaces:
==============================================
Currently, there are several interfaces marked as extension interfaces. 
The primary examples are ILexicalHandler and IDeclHandler. These 
interfaces provide access to data that is not required to be reported by 
the XML Specification. Hence all of the information is considered 
"extension" and not "core". That's fine. We don't want to change that.

What we do what to change is the clumsy mechanism for connecting 
extension interfaces to an IXmlReader. Currently this is done through 
the setproperty/getproperty mechanism. We propose to add new interface 
level property for LexicalHandler and DeclHandler (that will behave in 
the same way ContentHandler, ErrorHandler, etc, work).

The only difference will be when a parser/implementation does not 
support the reporting of "extension" data. In such a case, when the 
property is set the parser can throw a SaxNotSupportedException (or 
NotSupportedException depending on the outcome of the proposal to change 
some of the exception design in the API).

For those of us that use these interfaces on a regular basis it should 
simplify a lot of code. Especially when you know about 
parser/implementation level support a priori.

Thanks,
Jeff Rafter

[Saxdotnet-devel] Changes to the SAX for .NET API

[Jeff R. <li...@je...>]

Over the past few weeks Karl and I have been arguing off-list about a 
series of changes that we are considering for the SAX for .NET API. Some 
of these changes include backwards compatibility breaks-- most of these 
are very manageable, though. However we still want user input. I am 
going to be starting a number of new threads each of which will 
hopefully track a separate issue. Please jump in with *any* comments or 
questions-- we would love to know about how this will impact users, 
break compatibility, or just be silly-- before we do it.

Thanks,
Jeff Rafter

[Saxdotnet-devel] Welcome to saxdotnet-devel

[Jeff R. <li...@je...>]

Welcome