Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

burst.xml.XmlDoc Class Reference

List of all members.

Detailed Description

Scoping class to hold static functions related to objects compliant with the XML (non-HTML) DOM.

Such an object has standard DOM methods and properties (such as documentElement, etc.). While W3 does specify createDocument(), string parsing and url loading are not standardized abilities, and so there are other methods here to do those operations.

In this library, we refer to the type of such builtin objects as "DomDocument", even though the W3 specifications use just "Document". We find that overly confusing, because despite what may be intended, a browser Document (the type of window.document ) is neither a superset nor subset of a XML DOM object in capabilities.

Note that this currently is not instantiable. It has some static methods that return a DomDocument, and other functions that take a DomDocument as a first argument.

In addition to the methods here for creating a DomDocument, one may also be created via XMLHTTP, in those browsers that support it. Because of its finer control over errors, it may be preferable over createFromUrl.


Static Public Member Functions

DomDocument createEmpty ()
 Create an empty DomDocument object.

DomDocument createFromUrl (String url, Function handler)
 A convenience which combines createEmpty and loadUrl.

DomDocument createFromString (String str)
 Return a Dom Document initialized from the provided string of serialized XML.

void loadUrl (DomDocument xmldoc, String url, Function handler)
 Initialize the provided DomDocument object from the contents at the specified url.

String getParseError (DomDocument domdoc)
 Retrieve any parse error of a xml document.

String toXmlString (DomDocument domdoc)
 Serializes the DomDocument into a single String.


Static Public Attributes

Array XMLDOM_PROGID = ['Msxml2.DOMDocument.4.0' 'Msxml2.DOMDocument' 'Microsoft.XMLDom']
 ProgID values to try for Internet Explorer XMLDOM.

Member Function Documentation

DomDocument burst.xml.XmlDoc.createEmpty (   )  [static]
 

Create an empty DomDocument object.

The W3 specifies createDocument: http://www.w3.org/TR/DOM-Level-2-Core/core.html

If the environment supports the W3 createDocument, that is used for creation. Otherwise, on IE, an ActiveX DomDocument is created: http://msdn.microsoft.com/library/en-us/xmlsdk30/htm/xmobjpmexmldomdocument.asp

DomDocument burst.xml.XmlDoc.createFromString (  String  str  )  [static]
 

Return a Dom Document initialized from the provided string of serialized XML.

On IE, this is implemented by Document.loadXML(String): http://msdn.microsoft.com/library/en-us/xmlsdk30/htm/xmmthloadxml.asp

On Mozilla, DOMParser is used: http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensIDOMParser.html

The caller should expect the possibility of a thrown exception, and should also check the value of burst.xml.XmlDoc.getParseError(domdoc).

Todo:
For IE, as with load(), is doc.loadXML() false if and only if doc.parseError is set?

DomDocument burst.xml.XmlDoc.createFromUrl (  String  url,
Function  handler
)  [static]
 

A convenience which combines createEmpty and loadUrl.

It returns the DomDocument object (though not much can be done with it until the handler is called).

String burst.xml.XmlDoc.getParseError (  DomDocument  domdoc  )  [static]
 

Retrieve any parse error of a xml document.

When creating a xml document and it is initialized from a xml string or url, the caller needs to expect either a synchronous exception to be thrown (such as argument or security errors), or an error to be recorded in the xml document itself (such as parse errors).

In IE, it has a member variable parseError. In Mozilla, the document structure itself is altered to have a single child with tagName 'parseerror': 


 <parsererror xmlns="http://www.w3.org/1999/xhtml">
    XML Parsing Error: mismatched tag. Expected: </root>. 
    Location: file:///C:/DOCUME~1/Nicholas/MYDOCU~1/MYARTI~1/USINGT~1/Example/Invalid.xml 
    Line Number 3, Column 37:
    <sourcetext>
       <root image="root.gif">My Root</boot>
       ------------------------------------^
    </sourcetext>
</parsererror>

See:

Todo:
Mozilla uses parsererror or ParserError or PARSERERROR?

When will IE throw a synchronous error to load()

Any escaping of the string in case it has xml in it?

Parameters:
domdoc The DomDocument instance that might have an error.
Returns:
a String suitable for presentation of an error message, or undefined if there is no error.

void burst.xml.XmlDoc.loadUrl (  DomDocument  xmldoc,
String  url,
Function  handler
)  [static]
 

Initialize the provided DomDocument object from the contents at the specified url.

There is currently no W3 specification for DomDocument.load(), only for createDocument. (Note that http://www.w3.org/TR/DOM-Level-3-LS is a draft spec for "XML Load and Save".)

For DomDocument.load(), Mozilla attempts to follow Microsoft:

For both Mozilla and IE, by default load() is async. Mozilla only supports async, and we do not expose the ability to ask for synchronous loading.

When the load is complete, the provided handler is called with two arguments: handler(domdoc, url) . Note that this differs from a standard DOM onload event handler, which just takes an event argument.

Mozilla has no support for progress notification. IE has an API (via readystatechange), but in IE6 it is not helpful (it doesn't always call the handler very frequently, and when it does, the object is not in a queriable state). So we do not expose the ability to register a progress handler.

The error handling behavior in these environments is not totally understood. For now, the caller should expect the possibility of a synchronous throw exception, as well as the need to check for a non-null value from getParseError() when the onload_handler is called. Errors could be caused by a security error, an IO error, or a parse error.

There is no useful return value from this function.

This url to be loaded is subject to the usual "same origin" policy with respect to the current document.

For a background on these objects, see:

Todo:
In IE, does a parsing error make load() return false or just IO errors? if false is returned, is parseError always set?

Does mozilla have a useful return value from DomDocument.load()?

What does either IE or Moz do with a "file:" url? Is it still async?

Parameters:
xmldoc The DomDocument object to use for the load.
url The url to load. If it is a file, it should have a "file:" scheme.
handler The handler to call when it is done.

String burst.xml.XmlDoc.toXmlString (  DomDocument  domdoc  )  [static]
 

Serializes the DomDocument into a single String.

If available (IE), uses the 'xml' member. Note that in IE, when it loads an XML document into a window and there is no XSL sheet, it uses a default one and the document that you find by serializing is HTML made from that default XSL. In IE6 for example this default html includes various "contentEditable" elements.

So for IE we also check for domdoc.XMLDocument.xml

Otherwise attempts to use XMLSerializer (in Mozilla, see http://www.mozilla.org/xmlextras/ ).

Otherwise it uses burst.xml.DomUtil.serialize

Member Data Documentation

Array burst.xml.XmlDoc.XMLDOM_PROGID = ['Msxml2.DOMDocument.4.0' 'Msxml2.DOMDocument' 'Microsoft.XMLDom'] [static]
 

ProgID values to try for Internet Explorer XMLDOM.

About ProgID's for Microsoft XML components

First, note that ProgID values are case-insensitive.

Here is a summary of Microsoft MSXML releases: 


version   dll         IE                 Comment
1.0       msxml.dll   IE4
2.0,2.0a  msxml.dll   IE4.01, IE5.0      Microsoft's incompatible WD-xsl
2.5,2.5a  msxml.dll   IE5.01             XPath and SAX2
2.5 SP1   msxml.dll   IE5.01 SP1, IE5.5
2.6       msxml2.dll                     download only
3.0 SP2   msxml3.dll  IE6.0              XSLT added, still supports WD-xsl
4.0       msxml4.dll                     WD-xsl dropped

Some references that were used to create the above table:

Here is a summary of ProgID values for XML DOM: 


"Microsoft.XMLDom"
   Used starting with msxml.dll 1.0.
   Used as a name up until 2.5.
   Not version-independent (if you use the ProgID, you only get msxml.dll).
   For interface "IXMLDOMDocument", which is DOM Level-1

"MSXML.DOMDocument"
   same ProgID value and behavior as "Microsoft.XMLDom", started being used after it.

"Microsoft.FreeThreadedXMLDOM"
   1.0 ProgID for server-side component.

"Msxml2.DOMDocument"
   A different (extended) interface "IXMLDOMDocument2", which has extensions.
   Without a version suffix, will get the most recent version prior to (excluding) 4.0.
   With a suffix of ".2.6", ".3.0", ".4.0" will force MSXML 2.6, MSXML 3.0, or MSXML 4.0

"Msxml2.FreeThreadedDOMDocument"
   With suffix ".3.0" or ".4.0".
   For server-side use.

Here is a summary of ProgID values for XML HTTP Request: 


"Microsoft.XMLHTTP"
   1.0, not version-independent.

"Msxml2.XMLHTTP"
   With ".2.6", ".3.0", or "4.0" suffix ("4.0" mandatory for MSXML 4.0)

"Msxml2.ServerXMLHTTP"
   For use on server-side.

As an extra complication, up until MSXML 4.0, MSXML could be installed in "replace" mode (take over the unversioned ProgID) or "side-by-side" mode (require versioned ProgID).

Starting with MSXML 4.0, version-independent ProgID support (and "replace" mode) was removed. To use 4.0, the programmer must ask for a ProgID with a particular version, such as:

  • "Msxml2.DOMDocument.4.0"
  • "Msxml2.FreeThreadedDOMDocument.4.0"
  • "Msxml2.XMLHTTP.4.0"

(As a point of trivia, MSXML release 4.0 also renamed the SDK as "Microsoft XML Core Services" from "Microsoft XML Parser".)

For the XSLT morass, see http://www.perfectxml.com/articles/xml/XSLTInMSXML.asp

The documentation for this class was generated from the following file:
Generated on Tue Nov 30 04:03:09 2004 for BurstProject by doxygen 1.3.4