Comments on DOM Load and Save

Interface DOMImplementationLS

Method createDOMBuilder: 

If MODE_SYNCHRONOUS and MODE_ASYNCHRONOUS are the only anticipated values, then a boolean parameter would be preferred.  If it stays a unsigned short, then there needs to be a exception for unrecognized values.

Method createDOMInputSource:

The description of the return value mentions the type parameter, however the method has no parameters.  I'll discuss this one later.

Method createDOMWriter:

Being able to create an asynchronous writer would be desirable.  I'd add a mode parameter to parallel createDOMBuilder.

-------------------------
Interface DOMBuilder:

The description of whitespace-in-element-content feature probably should describe the interaction between validation.  

errorHandler: Passing "the node closest to where the error occurred" is really vague.  Especially if the problem is a well-formedness or other fatal error.  An character offset and/or text fragment would be more useful for error diagnosis.  Passing null if the closest node could not be determined would be cleaner than passing the document.

parse and parseURI Method:

Returning null for asynchrous DOMBuilder's would make it difficult to express DocumentLS.load in terms of DOMBuilder.parse.  Since DocumentLS appears to be a convienience interface, everything should be expressable in terms of the more general interfaces.

parseURI Method:

Specifying a behavior for URI's containing fragment identifier would seem desirable.  I'd suggest ignoring the fragment identifier, but throwing an exception would be better than leaving it unspecified.

parseWithContext:

Should throw DOMSystemExceptions.  Should throw NO_MODIFICATION_ALLOWED_ERR if context node (or parent) is read-only.   Returning the created node would be desirable.

How does parseWithContext interact with any event listeners registered on the context node or its ancestors?

setFeature:

Several features force other features to specific values, but there is no defined behavior if you try to override the forced value, for example, setting external-parameter-entities to false after setting validation to true.  I would suggest throwing an exception.

----------------
DOMWriter Interface:

encoding attribute:

The second bullet should describe how Document.encoding or Document.actualEncoding are used to determine the encoding.

Should throw an exception on setting if the encoding in not supported.

There should be a list of required encodings (at minimum UTF-8 and UTF-16)

lastEncoding attribute:

I'd prefer a method where I'd pass in a Node and get the encoding that would be used.  Don't like the statefulness of the attribute.

errorHandler attribute:

Might be more general than just errors, could be reporting progress or other details (such as the selected encoding) or participating in filtering.

newLine attribute:

Should probably be a unsigned short with constants for the supported values like other enumerations in the spec.

setFeature method:

Should have an defined exception for inconsistent features, like turning pretty-printing on after setting format-canonical to true.

writeNode method:

Writing a Document or Entity node... well formed XML.  Why would writing an entity node be well formed XML?

writeToString method:

How is this affected by encoding?  It will be represented internally as UTF-16 on most binding, but users who have set encoding to ISO-8859-1 or US-ASCII might expect no code points higher than 255 or 127 respectively so they can naively write out the string to a file later.

-----------------------------

DOMInputSource Interface:

I don't like the multiple personalities of this interface.  Instead of creating a DOMInputSource and then customizing it by setting attributes, I'd prefer multiple create (createSourceFromURI, createSourceFromString, etc),  methods on DOMImplementationLS and only the minimum read-only attributes on DOMInputSource.


--------------

DOMEntityResolver Interface:

"for applications that use URI types other than URIs"  Did you mean URL's.


------------------

DOMBuilderFilter Interface:

endNode and startNode methods

If the return value was a Node, then a Filter could:

1) return the passed enode to have the element inserted.
2) return null to have the element rejected
3) return a DocumentFragment for SKIP

but also:

substitute a replacement element created with Document.createElement[NS]

It should be possible to throw an exception in endNode and startNode to stop the parse.

----------------

DocumentLS interface:

An isLoaded or ReadyState attribute would be strongly desirable to determine that an async document was loaded without registering an event listener.

load method:

Should an exception be raised if you attempt to start a second async load when one is already in progress?

loadXML method:

How would any XML declaration specifying an encoding be handled.


-----------------

DOMErrorHandler Interface:

Referenced in DOMBuilder, but not defined in spec.  Called functions should be able to throw some type of exception or return an object to stop the parse and raise an exception to the caller of parse.  Those exceptions would need to be added to the list of potential exceptions on the parse calls.



--------------
Misspellings: garantee for guarantee, epcified for specified