OverviewSingleDeprecated

jsx3.xml

class Document

Object
->jsx3.lang.Object
  ->jsx3.xml.Entity
    ->jsx3.xml.Document

All Implemented Interfaces:

jsx3.util.EventDispatcher

Direct Known Subclasses:

jsx3.xml.CDF.Document, jsx3.xml.XslDocument

class Document
extends jsx3.xml.Entity
Wrapper of the native browser XML document class. Developers wishing to create/modify XML documents should use this class to access common XML parser methods (adding attributes and nodes, transformations, etc).

When querying an instance of this class (with e.g. selectSingleNode, selectNodes, getChildNodes, etc.), the node context will always be the root node (documentElement) and not the parser instance (ownerDocument). Therefore, all queries are assumed to begin at the root, meaning querying an instance of this class for the root node (assuming its name is "Price") would require a query such as "." or "/Price", not "Price".

Note that several methods of this class fail quietly when an error occurs with the wrapped native browser XML classes. Methods that are documented as failing quietly should always be followed by a call to hasError() to ensure that no error has occurred.

See Also:


Field Summary
static String
ON_ERROR
Event type published when an error occurs during the asynchronous loading of a document.
static String
ON_RESPONSE
Event type published when an asynchronous load operation has completed successfully.
static String
ON_TIMEOUT
Event type published when an asynchronous load times out before loading.
static String
SEARCHABLE_NAMESPACE
Namespace to use when querying against the namespace axis in firefox
static String
SEARCHABLE_PREFIX
Prefix to use when querying against the namespace axis in firefox
Constructor Summary
void
init(objDoc : Object)
The instance initializer.
Method Summary
jsx3.xml.Document
Creates a new node that is an exact clone of this node; returns the newly cloned node wrapped in a jsx3.xml.Entity instance
jsx3.xml.Entity
createDocumentElement(strNodeName : String, strNSURI : String)
Creates a new root node on an empty document.
String
The Firefox implementation of the XSLT specification does not implement a searchable namespace axis.
void
createProcessingInstruction(strTarget : String, strData : String)
Creates a processing instruction node that containing the target and data information.
boolean
getAsync(strName : ?)
Returns whether this document loads asynchronously.
Object
Returns a map of all implemented namespaces in the following format: {some_uri:"jsx1",some_other_uri,"jsx2",another_uri:"jsx3"}.
Object
Returns the native XML parser
boolean
Deprecated. IE-only.
String
Deprecated. This method is only implemented on Internet Explorer. XPath is the only supported value.
String
getSelectionNamespaces(strName : ?)
Gets a list of namespace prefixes and their associated URIs.
String
boolean
Deprecated. IE-only.
static String
Deprecated.
String
boolean
String
jsx3.xml.Document
load(strURL : String | jsx3.net.URI, intTimeout : int)
Loads an XML document at the URL specified by the strURL parameter.
jsx3.xml.Document
loadXML(strXML : String)
Loads an XML document from a string containing the XML source.
void
serialize(strVersion : boolean | String, strEncoding : boolean | String, bStandalone : boolean)
jsx3.xml.Document
setAsync(bAsync : boolean)
Sets whether this document loads asynchronously.
void
Deprecated. IE-only.
jsx3.xml.Document
setSelectionLanguage(strLanguage : String)
Deprecated. This method is only implemented on Internet Explorer. XPath is the only supported value.
jsx3.xml.Document
Sets a list of namespace prefixes and their associated URIs.
void
Deprecated. IE-only.
Methods Inherited From jsx3.util.EventDispatcher
publish, subscribe, unsubscribe, unsubscribeAll
Methods Inherited From jsx3.xml.Entity
appendChild, cloneNode, createNode, equals, getAttribute, getAttributeNames, getAttributeNode, getAttributes, getBaseName, getChildIterator, getChildNodes, getError, getFirstChild, getLastChild, getNamespaceURI, getNative, getNextSibling, getNodeName, getNodeType, getOwnerDocument, getParent, getPrefix, getPreviousSibling, getRootNode, getValue, getXML, hasError, insertBefore, removeAttribute, removeAttributeNode, removeChild, removeChildren, replaceNode, selectNodeIterator, selectNodes, selectSingleNode, setAttribute, setAttributeNode, setValue, toString, transformNode
Methods Inherited From jsx3.lang.Object
clone, eval, getClass, getInstanceOf, getInstanceOfClass, getInstanceOfPackage, instanceOf, isInstanceOf, isSubclassOf, jsxmix, jsxsuper, jsxsupermix, setInstanceOf
Field Detail

ON_ERROR

static final String ON_ERROR
Event type published when an error occurs during the asynchronous loading of a document.

ON_RESPONSE

static final String ON_RESPONSE
Event type published when an asynchronous load operation has completed successfully.

ON_TIMEOUT

static final String ON_TIMEOUT
Event type published when an asynchronous load times out before loading.

SEARCHABLE_NAMESPACE

static final String SEARCHABLE_NAMESPACE
Namespace to use when querying against the namespace axis in firefox

SEARCHABLE_PREFIX

static final String SEARCHABLE_PREFIX
Prefix to use when querying against the namespace axis in firefox
Constructor Detail

init

void init(objDoc : Object)
The instance initializer. If an error occurs while instantiating the native browser XML document class, this method sets the error property of this document and returns quietly.

Parameters:

objDocthe native browser document object (optional).
Method Detail

cloneDocument

jsx3.xml.Document cloneDocument()
Creates a new node that is an exact clone of this node; returns the newly cloned node wrapped in a jsx3.xml.Entity instance

Returns:

newly cloned MSXML Node object wrapped in a jsx3.xml.Document instance  

createDocumentElement

jsx3.xml.Entity createDocumentElement(strNodeName : String, strNSURI : String)
Creates a new root node on an empty document.

Usage:

var objDoc = new jsx3.xml.Document();
objDoc.createDocumentElement("myRoot");

Parameters:

strNodeNamenode name for the root node
strNSURInamespace (optional). For example, "http:/someURN.com/". Note that if this parameter is used, @strNodeName can be optionally prefixed (i.e., abc:myRoot) to create an explicit namespace prefix.

Returns:

reference to the new node wrapped in a jsx3.xml.Entity instance  

createNamespaceAxis

String createNamespaceAxis()
The Firefox implementation of the XSLT specification does not implement a searchable namespace axis. To overcome this limitation, this method can be called to create a searchable equivalent that is part of the attribute axis. After XML content has been loaded, call this method before calling any other methods on the Document instance in order to ensure proper functioning of subsequent calls. The document can then be queried, using valid XPath syntax to discover the declared namespaces. However, instead of using namespace::xsd, the relevant query would be attribute::jsx_xmlns:xsd, where jsx_xmlns:xsd would resolve to the universal name, {http://xsd.tns.tibco.com/gi/cxf/2006}:xsd. Following this call with getDeclaredNamespaces is useful to resolve the prefix actually used, providing a reverse-lookup to resolve the actual prefix being used. For example, assume objMap is the return object when calling getDeclaredNamespaces. In such a case, the following query can be used to locate the URI for a given namespace prefix, even though Firefox does not support such a construct:

var objMap = someDoc.getDeclaredNamespaces();
var myXpathQuery = "ancestor-or-self::*[attribute::" +
  objMap[jsx3.xml.Document.SEARCHABLE_NAMESPACE] +  ":xsd]/attribute::" +
  objMap[jsx3.xml.Document.SEARCHABLE_NAMESPACE] + ":xsd";
var objNode = someNode.selectSingleNode(myXpathQuery,objMap);

Returns:

prefix used to represent the xmlns. By default the return will be jsx_xmlns. However, if this prefix is already being used by the document instance (i.e., xmlns:jsx_xmlns="?"), the prefix will be incremented as follows: jsx_xmlns0, jsx_xmlns1, jsx_xmlns2, etc, until a unique prefix is found. 

See Also:


createProcessingInstruction

void createProcessingInstruction(strTarget : String, strData : String)
Creates a processing instruction node that containing the target and data information. Note that you cannot specify a namespace with this method.

Usage:

[document].createProcessingInstruction("xml","version=\"1.0\" encoding=\"UTF-8\"");
[document].createDocumentElement("myRoot");

Parameters:

strTargetString that specifies the target part of the processing instruction. This supplies the nodeName property of the new object.
strDataString that specifies the rest of the processing instruction preceding the closing ?> characters. This supplies the nodeValue property for the new object.

getAsync

boolean getAsync(strName : ?)
Returns whether this document loads asynchronously.

Parameters:

strName

Returns:

 

getDeclaredNamespaces

Object getDeclaredNamespaces(objMap : Object)
Returns a map of all implemented namespaces in the following format: {some_uri:"jsx1",some_other_uri,"jsx2",another_uri:"jsx3"}.
The returned object map can then be used to resolve the qualified name (QName) for the nodes in a given query via a reverse lookup. For example:
//open an XML Document (just use one of the sample prototypes that ships with Builder)
var objXML = new jsx3.xml.Document();
objXML.load("GI_Builder/prototypes/Block/Text.xml");
//get an object map of all known selection namespaces
var objMap = objXML.getDeclaredNamespaces();
//construct a qualified query (Note that all nodes in a GI serialization file belong to the namespace, 'urn:tibco.com/v3.0')
var myQualifiedQuery = "//" + objMap["urn:tibco.com/v3.0"] + ":object";
//query the document for the given node.
var objNode = objXML.selectSingleNode(myQualifiedQuery,objMap);
//alert the return
alert(objNode);

Parameters:

objMapOptional. should follow the format {prefix1:1,prefix2:1}. If passed, the returned Object will resolve to any matched prefix, while using arbitrary sequential prefixes (jsx1, jsx2, etc) for all other uris.

Returns:

 

getNativeDocument

Object getNativeDocument()
Returns the native XML parser

Returns:

 

getResolveExternals

boolean getResolveExternals()
Deprecated. IE-only.
Returns whether or not the parser should resolve externally referenced entities. The default setting is false;

Returns:

 

Since:

3.2

getSelectionLanguage

String getSelectionLanguage()
Deprecated. This method is only implemented on Internet Explorer. XPath is the only supported value.
Gets the selection language to use for selection queries (i.e., selectSingleNode/selectNodes); The default is XSLPattern;

Returns:

 

getSelectionNamespaces

String getSelectionNamespaces(strName : ?)
Gets a list of namespace prefixes and their associated URIs. This allows any code to generically prefix name-space qualified nodes and still get the correct selection result

Parameters:

strName

Returns:

 

getSourceURL

String getSourceURL()

Returns:

 

Since:

3.2

getValidateOnParse

boolean getValidateOnParse()
Deprecated. IE-only.
Returns whether or not the parser should validate the XML content during the initial parse. The default setting is false;

Returns:

 

Since:

3.2

getVersion

static String getVersion()
Deprecated.
gets the release/build for the class (i.e., "2.2.00")

Returns:

 

getXmlEncoding

String getXmlEncoding()

Returns:

 

getXmlStandalone

boolean getXmlStandalone()

Returns:

 

getXmlVersion

String getXmlVersion()

Returns:

 

load

jsx3.xml.Document load(strURL : String | jsx3.net.URI, intTimeout : int)
Loads an XML document at the URL specified by the strURL parameter. If an error occurs while loading the XML document, this method sets the error property of this document and returns quietly. If this document loads synchronously, the results of the load will be available immediately after the call to this method. Otherwise, this document publishes events through the EventDispatcher interface to notify the client that loading has completed.

Parameters:

strURLeither a relative or absolute URL pointing to an XML document to load.
intTimeoutthe number of milliseconds to wait before timing out. This parameter is only relevant if this document is loading XML asynchronously. A zero or null value will cause this operation to wait forever.

Returns:

this object. 

See Also:

jsx3.util.EventDispatcher

loadXML

jsx3.xml.Document loadXML(strXML : String)
Loads an XML document from a string containing the XML source. If an error occurs while loading the XML document, this method sets the error property of this document and returns quietly. Loading an XML document from a string always happens synchronously regardless of the value of the async property of this document.

Parameters:

strXMLan XML document as string. Note that if this document contains an encoding attribute in its initial declaration (such as encoding="UTF-8") it must correspond to the encoding of the actual string, strXML. If, for example, strXML is in unicode format, explicitly passing the UTF-8 encoding attribute will cause the load to fail, as the byte order will cause the parser to look for the UTF-16 attribute.

Returns:

this object.  

serialize

void serialize(strVersion : boolean | String, strEncoding : boolean | String, bStandalone : boolean)

Parameters:

strVersion
strEncoding
bStandalone

setAsync

jsx3.xml.Document setAsync(bAsync : boolean)
Sets whether this document loads asynchronously. The default is to load synchronously. If this document loads asynchronously, it publishes the events ON_RESPONSE, ON_ERROR, and ON_TIMEOUT to notify the client that loading has finished.

Parameters:

bAsyncif true the document loads asynchronously.

Returns:

this object. 

See Also:

ON_RESPONSE, ON_ERROR, ON_TIMEOUT

setResolveExternals

void setResolveExternals(bResolve : boolean)
Deprecated. IE-only.
Sets whether or not the parser should resolve externally referenced entities.

Parameters:

bResolve

Since:

3.2

setSelectionLanguage

jsx3.xml.Document setSelectionLanguage(strLanguage : String)
Deprecated. This method is only implemented on Internet Explorer. XPath is the only supported value.
Sets the selection language to use for selection queries (i.e., selectSingleNode/selectNodes); The default is XSLPattern;

Parameters:

strLanguageone of the strings: XSLPattern, XPath

Returns:

reference to this 

setSelectionNamespaces

jsx3.xml.Document setSelectionNamespaces(declaration : Object | String)
Sets a list of namespace prefixes and their associated URIs. This allows any code to generically prefix name-space qualified nodes and still get the correct selection result

Parameters:

declarationRelevant selection namespace(s) in Object format. For example: {some_uri:"jsx1",some_other_uri,"jsx2"} or in String format. For example: "xmlns:jsx1='some_uri' xmlns:jsx2='some_other_uri'"

Returns:

reference to this  

setValidateOnParse

void setValidateOnParse(bValidate : boolean)
Deprecated. IE-only.
Sets whether or not the parser should validate the XML content during the initial parse.

Parameters:

bValidate

Since:

3.2