Websydian DOM - Parts (DomInterfaces Function Suite)

Introduction    Installation    Other Uses    Parts

• DomAbstract Function Suite

• DomInterfaces Function Suite

• DomServices Function Suite

• XmlParsers Function Suite

• XPath Function Suite

The DomInterfaces function suite is the main suite in Websydian DOM. 

The DOM standard defines a number of interfaces each containing various methods and attributes. This structure of the DOM standard is reflected in the DomInterfaces function suite, that scopes one function per interface in the DOM standard. Each of these interface functions scope DOM functions representing methods and attributes contained in the corresponding DOM interfaces:

Interfaces

The DomInterfaces function suite scopes one function for each of the interfaces defined by the DOM standard:

Attr
CharacterData
Comment
Document
DocumentFragment
DocumentType
DomImplementation
Element
Entity
EntityReference
NamedNodeMap
Node
Nodelist
Notation
ProcessingInstruction
Text

Each interface function scopes one function for each method/attribute belonging to the interface. 

Each of the functions scoped to an interface function inherits from one of the two abstract functions DomLevel1 or DomLevel2 depending on whether the function implements a DOM Level 1 method/attribute or one belonging to the DOM Level 2.

DOM Functions

Each interface in the DOM standard describes an object with methods and attributes associated to it. In Websydian DOM the methods and attributes are implemented as CA Plex functions (called Websydian DOM functions). The DOM functions access the DOM object to which the method or attribute belongs through calls to parser specific API source code. 

All DOM functions have at least three parameters ObjectStoreReference, ObjectReference, and ExceptionCode.

ObjectStoreReference
The object store requires this field that holds a reference to the object store containing all references for a specific DOM document. Whenever a new document is created a new ObjectStoreReference will be created.

ObjectReference 
This field contains a reference to the DOM object the function should access. E.g. when calling the function Node.appendChild the ObjectReference should contain a reference to a DOM Node object.

The reference parameters are passed as input to the DOM functions.

ExceptionCode
ExceptionCode is used as an output parameter and contains the exception code of any exception raised in the execution of the API source code associated to the DOM function. Additional information on the exception is available by popping an element from the error stack.  

Other Parameters

Apart from the three parameters ObjectStoreReference, ObjectReference, and ExceptionCode, each DOM function has additional parameters. The DOM function has one input parameter for each parameter in the corresponding DOM method, and one output parameter for each return value in the DOM method. 

Example

The DOM Interface Document describes methods and attributes belonging to the Document object. One of the methods described is createAttribute, which creates an Attr object. The createAttribute method has as input the parameter name and returns the Attr object just created. This method is implemented in WSYDOM by the function createAttribute:

Parameters in createAttribute	input/output
ObjectStoreReference	input
ObjectReference	input
name	input
ExceptionCode	output
ObjectAttr	output

The reference ObjectAttr (which is a DomObjectReference field) obtained when calling createAttribute can be used in subsequent calls to the DOM functions that requires an Attr object.

Methods

A DOM Interface consists of a number of methods each of which performs an operation on the object it belongs to. In WSYDOM each DOM method is implemented as an CA Plex function with specified parameters as described above. 

Attributes

A DOM interface consists of a number of attributes, some of which are read-only.

In WSYDOM, these attributes can be accessed through functions scoped to the relevant interface.

• For each attribute a _get function is available.
• For each of the read/write attributes, a _set function is available.

Examples:

The Node interface contains the read/write attribute nodeValue. The value of this attribute is read using the function nodeValue_get, and the attribute's value is set using the function nodeValue_set. 

DOM Interface Inheritance Hierarchy

Some DOM interfaces inherit from other DOM interfaces. The inheritance diagram for DOM can be seen in the figure below.

A specific interface can always be used instead of an interface higher up in the inheritance hierarchy. E.g. a reference to an Element object can be used as input to the ObjectReference field in all the functions scoped to the DomInterfaces.Node function suite, because an Element object also is a Node object.

This explains why some of the implemented interfaces in DomInterface do not scope any functions. E.g. the DomInterfaces.Comment interface is empty because the Comment interface inherits all its methods from CharacterData and Node.