This chapter describes the optional DOM Level 3 Abstract
Schema (AS) feature. This module provides a
representation for XML abstract schemas, e.g., DTDs and XML
Schemas, together with operations on the abstract schemas, and how
such information within the abstract schemas could be applied to
XML documents used in both the document-editing and AS-editing
worlds. It also provides additional tests for well-formedness of
XML documents, including Namespace well-formedness. A DOM
application can use the hasFeature method of
theDOMImplementation interface to determine whether a
given DOM supports these capabilities or not. One feature string
for the AS-editing interfaces listed in this section is "AS-EDIT"
and another feature string for document-editing interfaces is
"AS-DOC".
This chapter interacts strongly with the Load and Save chapter, which is also under development in DOM Level 3. Not only will that code serialize/deserialize abstract schemas, but it may also wind up defining its well-formedness and validity checks in terms of what is defined in this chapter. In addition, the AS and Load/Save functional areas will share a common error-reporting mechanism allowing user-registered error callbacks. Note that this may not imply that the parser actually calls the DOM's validation code -- it may be able to achieve better performance via its own -- but the appearance to the user should probably be "as if" the DOM has been asked to validate the document, and parsers should probably be able to validate newly loaded documents in terms of a previously loaded DOM AS.
Finally, this chapter will have separate sections to address the needs of the document-editing and AS-editing worlds, along with a section that details overlapping areas such as validation. In this manner, the document-editing world's focuses on editing aspects and usage of information in the AS are made distinct from the AS-editing world's focuses on defining and manipulating the information in the AS.
In the October 9, 1997 DOM requirements document, the following appeared: "There will be a way to determine the presence of a DTD. There will be a way to add, remove, and change declarations in the underlying DTD (if available). There will be a way to test conformance of all or part of the given document against a DTD (if available)." In later discussions, the following was added, "There will be a way to query element/attribute (and maybe other) declarations in the underlying DTD (if available)," supplementing the primitive support for these in Level 1.
That work was deferred past Level 2, in the hope that XML Schemas would be addressed as well. It is anticipated that lowest common denominator general APIs generated in this chapter can support both DTDs and XML Schemas, and other XML abstract schemas down the road.
The kinds of information that an Abstract Schema must make available are mostly self-evident from the definitions of Infoset, DTDs, and XML Schemas. Note that some kinds of information on which the DOM already relies, e.g., default values for attributes, will finally be given a visible representation here, however.
The abstract schema referenced in these use cases/requirements is an abstraction and does not refer solely to DTDs or XML Schemas.
For the AS-editing and document-editing worlds, the following use cases and requirements are common to both and could be labeled as the "Validation and Other Common Functionality" section:
Use Cases:
Requirements:
Specific to the AS-editing world, the following are use cases and requirements and could be labeled as the "AS-editing" section:
Use Cases:
Requirements:
Specific to the document-editing world, the following are use cases and requirements and could be labeled as the "Document-editing" section:
Use Cases:
Requirements:
General Issues:
QName, e.g.,
foo:bar, whereas the latter will report its namespace
and local name, e.g., {http://my.namespace}bar. We
have added the isNamespaceAware attribute to the
generic AS object to help applications determine which of these
fields are important, but we are still analyzing this
challenge.A list of the proposed Abstract Schema data structures and functions follow, starting off with the data structures and "AS-editing" methods.
ASModel is an abstract object that could map to a
DTD, an XML Schema, a database schema, etc. It's a generalized
abstract schema object, that has both an internal and external
subset. The internal subset would always exist, even if empty, with
the external subset (if present) being represented as by an
"active" ASExternalModel.
Many ASExternalModels
could exist, but only one can be specified as "active"; it is also
possible that none are "active". The issue of multiple abstract
schemas is misleading since in this architecture, only one
ASModel exists, with an internal subset that
references the external subset. If the external subset changes to
another "acitve" ASExternalModel,
the internal subset is "fixed up." The ASModel also contains the
factory methods needed to create a various types of ASNodes like ASElementDeclaration,
ASAttributeDeclaration, etc.
interface ASModel : ASNode {
readonly attribute boolean isNamespaceAware;
attribute ASElementDeclaration rootElementDecl;
attribute DOMString systemId;
attribute DOMString publicId;
ASNodeList getASNodes();
boolean removeNode(in ASNode node);
boolean insertBefore(in ASNode newNode,
in ASNode refNode);
boolean validate();
ASElementDeclaration createASElementDeclaration(inout DOMString namespaceURI,
in DOMString qualifiedElementName)
raises(DOMException);
ASAttributeDeclaration createASAttributeDeclaration(inout DOMString namespaceURI,
in DOMString qualifiedName)
raises(DOMException);
ASNotationDeclaration createASNotationDeclaration(inout DOMString namespaceURI,
in DOMString qualifiedElementName,
in DOMString systemIdentifier,
inout DOMString publicIdentifier)
raises(DOMException);
ASEntityDeclaration createASEntityDeclaration(in DOMString name)
raises(DOMException);
ASChildren createASChildren(in unsigned long minOccurs,
in unsigned long maxOccurs,
inout unsigned short operator)
raises(DOMException);
};
isNamespaceAware
of type boolean, readonlyQNames.publicId of type
DOMStringrootElementDecl of type ASElementDeclarationsystemId of type
DOMStringcreateASAttributeDeclarationnamespaceURI of type
DOMStringqualifiedName of type
DOMString|
A new ASAttributeDeclaration object with
|
|
|
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. |
createASChildrenminOccurs of type
unsigned longmaxOccurs of type
unsigned longoperator of type
unsigned short|
A new ASChildren object. |
|
|
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. |
createASElementDeclarationnamespaceURI of type
DOMStringqualifiedElementName of
type DOMString|
A new ASElementDeclaration object with |
|
|
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. DUPLICATE_NAME_ERR:Raised if an element declaration already exists with the same name for a given ASModel. |
createASEntityDeclarationname of type
DOMString|
A new ASNotationDeclaration object with |
|
|
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. |
createASNotationDeclarationnamespaceURI of type
DOMStringqualifiedElementName of
type DOMStringsystemIdentifier of type
DOMStringpublicIdentifier of type
DOMString|
A new ASNotationDeclaration object with
|
|
|
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. DUPLICATE_NAME_ERR:Raised if a notation declaration already exists with the same name for a given ASModel. |
getASNodesinsertBeforeASNode
in front of a reference node. If the referenced node is
null the new node is inserted in the back of the list
of nodes maintaoned by the ASModel.
|
|
|
removeNodevalidate|
|
Is the AS valid? |
ASExternalModel is an abstract object that could
map to a DTD, an XML Schema, a database schema, etc. It's a
generalized abstract schema object that is not bound to a
particular XML document.
interface ASExternalModel : ASModel {
};
ASNodeis analogous to a Node in the
Core DOM, e.g., an element declaration. This can exist for both ASExternalModel
and ASModel.
It must be able to handle constructs such as comments and
processing instructions.
Opaque.
interface ASNode {
const unsigned short AS_ELEMENT_DECLARATION = 1;
const unsigned short AS_ATTRIBUTE_DECLARATION = 2;
const unsigned short AS_NOTATION_DECLARATION = 3;
const unsigned short AS_ENTITY_DECLARATION = 4;
const unsigned short AS_CHILDREN = 5;
const unsigned short AS_MODEL = 6;
const unsigned short AS_EXTERNALMODEL = 7;
readonly attribute unsigned short cmNodeType;
attribute ASModel ownerASModel;
attribute DOMString nodeName;
attribute DOMString prefix;
attribute DOMString localName;
attribute DOMString namespaceURI;
ASNode cloneASNode();
};
ASElementDeclaration.ASAttributeDeclaration.ASNotationDeclaration.
ASEntityDeclaration.ASChildren.ASModel.ASExternalModel.cmNodeType of type unsigned
short, readonlylocalName of type
DOMStringqualified name of
this ASNode.namespaceURI of type
DOMStringnodeName of type
DOMStringqualified name of this ASNode depending on the
ASNode type.ownerASModel of type ASModelASModel
object associated with this ASNode. For a node of type
AS_MODEL, this is null.prefix of type
DOMStringASNodeList is the AS analogue to
NodeList; the document order is meaningful, as opposed
to ASNamedNodeMap.
ASNodeList objects in the DOM AS are live.
interface ASNodeList {
readonly attribute int length;
ASNode item(in int index);
};
length of type
int, readonlylength-1 inclusive.itemindexth item in the
collection. The index starts at 0. If index is greater
than or equal to the number of nodes in the list, this returns
null.
index of type
int|
The ASNode at the |
ASDOMStringList represents a collection of
DOMStrings.
interface ASDOMStringList {
readonly attribute int length;
DOMString item(in int index);
};
length of type
int, readonlylength-1
inclusive.itemindexth DOMString in
the collection. The index starts at 0. If index is
greater than or equal to the number of nodes in the list, this
returns null.
index of type
int|
|
The DOMString at the |
ASNamedNodeMap is the AS analogue to
NamedNodeMap. The order is not meaningful. Although
the contents of an ASNamedNodeMap is accessible through an ordinal,
it does not imply that DOM AS specifies an order on these
ASNodes.
interface ASNamedNodeMap {
readonly attribute int length;
ASNode getNamedItem(inout DOMString name);
ASNode getNamedItemNS(in DOMString namespaceURI,
inout DOMString localName);
ASNode item(in int index);
ASNode removeNamedItem(in DOMString name);
ASNode removeNamedItemNS(in DOMString namespaceURI,
in DOMString localName);
ASNode setNamedItem(inout ASNode newASNode)
raises(DOMASException);
ASNode setNamedItemNS(inout ASNode newASNode)
raises(DOMASException);
};
length of type
int, readonlylength-1 inclusive.getNamedItemgetNamedItemNSnamespaceURI of type
DOMStringlocalName of type
DOMString|
A ASNode (of any type) with the specified local name and namespace URI, or null if they do not identify any ASNode in this map. |
itemindexth item in the
map. The index starts at 0. If index is greater than
or equal to the number of nodes in the list, this returns
null.
index of type
int|
The ASNode at the |
removeNamedItemname of type
DOMString|
The ASNode removed from this map if an ASNode with such a name exists. |
removeNamedItemNSnamespaceURI of type
DOMStringlocalName of type
DOMString|
The ASNode removed from this map if an ASNode with such a local name and namespace URI exists. |
setNamedItemnewASNode of type ASNode|
If the new node replaces an existing one, the replaced node is
returned, otherwise |
|
|
setNamedItemNSnamespaceURI and localName attributes. If
an ASNode with the same namespaceURI and localName is already
present in this map, it is replaced by the new one.
newASNode of type ASNode|
If the new node replaces an existing one, the replaced node is
returned, otherwise |
|
|
The only primitive datatype supported by base DOM AS
implementation is string type.
interface ASDataType {
const short STRING_DATATYPE = 1;
short getASPrimitiveType();
};
string data type as defined
in XML
Schema Datatypes.getASPrimitiveType|
|
code representing the primitive type of the attached data item. |
The primitive types supported by optional DOM AS implementations. A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether this interface is supported or not. The feature string for all the interfaces listed in this section is "AS-PTYPES" and the version is "3.0".
interface ASPrimitiveType : ASDataType {
const short BOOLEAN_DATATYPE = 2;
const short FLOAT_DATATYPE = 3;
const short DOUBLE_DATATYPE = 4;
const short DECIMAL_DATATYPE = 5;
const short HEXBINARY_DATATYPE = 6;
const short BASE64BINARY_DATATYPE = 7;
const short ANYURI_DATATYPE = 8;
const short QNAME_DATATYPE = 9;
const short DURATION_DATATYPE = 10;
const short DATETIME_DATATYPE = 11;
const short DATE_DATATYPE = 12;
const short TIME_DATATYPE = 13;
const short YEARMONTH_DATATYPE = 14;
const short YEAR_DATATYPE = 15;
const short MONTHDAY_DATATYPE = 16;
const short DAY_DATATYPE = 17;
const short MONTH_DATATYPE = 18;
const short NOTATION_DATATYPE = 19;
attribute decimal lowValue;
attribute decimal highValue;
};
boolean data type as defined
in XML
Schema Datatypes.float data type as defined
in XML
Schema Datatypes.double data type as defined
in XML
Schema Datatypes.decimal data type as defined
in XML
Schema Datatypes.hexbinary data type as defined
in XML
Schema Datatypes.base64binary data type as
defined in XML Schema
Datatypes.uri reference data type as
defined in XML Schema Datatypes.
Note: @@uriReference is no longer part of the XML Schema PR draft.
XML qualified name data type
as defined in XML
Schema Datatypes.duration data type as defined
in XML
Schema Datatypes.datetime data type as defined
in XML
Schema Datatypes.date data type as defined in XML Schema
Datatypes.time data type as defined in
XML
Schema Datatypes.yearmonth data type as defined
in XML
Schema Datatypes.year data type as defined in
XML
Schema Datatypes.monthday data type as defined
in XML
Schema Datatypes.day data type as defined in XML Schema
Datatypes.month data type as defined in
XML
Schema Datatypes.NOTATIONdata type as defined in
XML
Schema Datatypes.The element name along with the content specification in the
context of an ASNode.
interface ASElementDeclaration : ASNode {
const short EMPTY_CONTENTTYPE = 1;
const short ANY_CONTENTTYPE = 2;
const short MIXED_CONTENTTYPE = 3;
const short ELEMENTS_CONTENTTYPE = 4;
attribute boolean strictMixedContent;
attribute ASDataType elementType;
attribute boolean isPCDataOnly;
attribute short contentType;
attribute DOMString tagName;
ASChildren getASChildren();
void setASChildren(inout ASChildren elementContent)
raises(DOMASException);
ASNamedNodeMap getASAttributeDecls();
void setASAttributeDecls(inout ASNamedNodeMap attributes);
void addASAttributeDecl(in ASAttributeDeclaration attributeDecl);
ASAttributeDeclaration removeASAttributeDecl(in ASAttributeDeclaration attributeDecl);
};
contentType
of type shortelementType
of type
ASDataTypeisPCDataOnly
of type booleanstrictMixedContent
of type booleantagName of type
DOMStringaddASAttributeDeclASAttributeDeclaration for the element being
declared.
attributeDecl of type
ASAttributeDeclarationgetASAttributeDeclsASNamedNodeMap
containing
ASAttributeDeclarations for all the attributes
that can appear on this type of element.
|
Attributes list for this |
getASChildren|
Content model of this element. |
removeASAttributeDeclASAttributeDeclaration from the element being
declared.
attributeDecl of type
ASAttributeDeclaration|
|
setASAttributeDeclsASNamedNodeMap
containing
ASAttributeDeclarations for all the attributes
that can appear on this type of element.
attributes of type ASNamedNodeMapsetASChildrenelementContent of type ASChildren|
|
Raises exception AS_NO_CHILD_ALLOWED_ERR if the element is defined to be of EMPTY_CONTENTTYPE. |
The content model of a declared element.
interface ASChildren : ASNode {
const unsigned long UNBOUNDED = MAX_LONG;
const unsigned short NONE = 0;
const unsigned short SEQUENCE = 1;
const unsigned short CHOICE = 2;
attribute unsigned short listOperator;
attribute unsigned long minOccurs;
attribute unsigned long maxOccurs;
attribute ASNodeList subModels;
ASNode removeASNode(in unsigned long nodeIndex);
int insertASNode(in unsigned long nodeIndex,
in ASNode newNode);
int appendASNode(in ASNode newNode);
};
subModels. This is
usually the case where the subModels contain a single element
declaration.listOperator
of type unsigned shortsubModels. For example,
if the list operator is CHOICE and the components in subModels are
a, b and c then the abstract schema for the element being declared
is (a|b|c)maxOccurs
of type unsigned longminOccurs
of type unsigned longsubModels
of type ASNodeListASNodes
in which the element can be defined.appendASNodesubModels.
newNode of type ASNode|
|
the length of the |
insertASNodenodeIndex of type
unsigned longnewNode of type ASNode|
|
The index value at which it is inserted. If the nodeIndex is
outside the bound of the |
removeASNodenodeIndex of type
unsigned long|
The node removed is returned as a result of this method call.
The method returns |
An attribute declaration in the context of a ASNode.
interface ASAttributeDeclaration : ASNode {
const short NO_VALUE_CONSTRAINT = 0;
const short DEFAULT_VALUE_CONSTRAINT = 1;
const short FIXED_VALUE_CONSTRAINT = 2;
attribute DOMString attrName;
attribute ASDataType attrType;
attribute DOMString attributeValue;
attribute DOMString enumAttr;
attribute ASNodeList ownerElement;
attribute short constraintType;
};
attrName of type
DOMStringattrType of type
ASDataTypeattributeValue of
type DOMStringconstraintType of
type shortenumAttr of type
DOMStringownerElement of type
ASNodeListModels a general entity declaration in an abstract schema.
interface ASEntityDeclaration : ASNode {
const short INTERNAL_ENTITY = 1;
const short EXTERNAL_ENTITY = 2;
attribute short entityType;
attribute DOMString entityName;
attribute DOMString entityValue;
attribute DOMString systemId;
attribute DOMString publicId;
attribute DOMString notationName;
};
entityName
of type DOMStringentityType
of type shortentityValue
of type DOMStringnull.notationName
of type DOMStringnull.publicId of
type DOMStringnull.systemId of
type DOMStringnull.This interface represents a notation declaration.
interface ASNotationDeclaration : ASNode {
attribute DOMString notationName;
attribute DOMString systemId;
attribute DOMString publicId;
};
notationName
of type DOMStringpublicId of
type DOMStringsystemId of
type DOMStringThis section contains "Validation and Other" methods common to
both the document-editing and AS-editing worlds (includes Document,
DOMImplementation, and DOMErrorHandler
methods).
The setErrorHandler method is off of the
Document interface.
interface Document {
void setErrorHandler(in DOMErrorHandler handler);
};
setErrorHandlerhandler of type DOMErrorHandlerThis interface extends the Document
interface with additional methods for both document and AS
editing.
interface DocumentAS : Document {
attribute boolean continuousValidityChecking;
int numASs();
ASModel getInternalAS();
ASNodeList getASs();
ASModel getActiveAS();
void addAS(in ASModel cm);
void removeAS(in ASModel cm);
boolean activateAS(in ASModel cm);
};
continuousValidityChecking
of type booleanactivateASASModel
active. Note that if a user wants to activate one AS to get default
attribute values and then activate another to do validation, a user
can do that; however, only one AS is active at a time. If an
attribute is declared in an internal subset and the corresponding
ownerElement points to a ASElementDeclaration
defined in an external subset, changing the active AS will cause
the ownerElement to be recomputed. If the owner element is not
defined in the newly active AS, the ownerElement will
be an empty node list.
cm of type ASModelASModel
points to a list of ASExternalModels;
with this call, only the specified AS will be active.|
|
True if the |
addASASModel
with a document. Can be invoked multiple times to result in a list
of ASExternalModels.
Note that only one internal ASModel
is associated with the document, however, and that only one of the
possible list of ASExternalModels
is active at any one time.
cm of type ASModelgetASsASNodes
of type AS_EXTERNAL_MODELs associated with the
document. The addAS method associates a model with a
document.
|
A list of |
getActiveASASExternalModel
for a document.
|
|
getInternalASnumASsASExternalModels
associated with the document. Only one ASModel
can be associated with the document, but it may point to a list of
ASExternalModels.
|
|
Non-negative number of external AS objects. |
removeASASExternalModel
associated with a document. Can be invoked multiple times to remove
a number of these in the list of ASExternalModels.
cm of type ASModelThis interface extends the DOMImplementation
interface with additional methods.
interface DOMImplementationAS : DOMImplementation {
ASModel createAS();
ASExternalModel createExternalAS();
};
createAS|
A NULL return indicates failure. |
createExternalAS|
A NULL return indicates failure. |
This section contains "Document-editing" methods (includes
Node, Element, Text and Document
methods).
This interface extends the Node interface with
additional methods for guided document editing.
interface NodeAS : Node {
const short WF_CHECK = 1;
const short NS_WF_CHECK = 2;
const short PARTIAL_VALIDITY_CHECK = 3;
const short STRICT_VALIDITY_CHECK = 4;
attribute short wfValidityCheckLevel;
boolean canInsertBefore(in Node newChild,
in Node refChild)
raises(DOMException);
boolean canRemoveChild(in Node oldChild)
raises(DOMException);
boolean canReplaceChild(in Node newChild,
in Node oldChild)
raises(DOMException);
boolean canAppendChild(in Node newChild)
raises(DOMException);
boolean isValid(in boolean deep)
raises(DOMException);
};
wfValidityCheckLevel of
type shortisValid method.
Default value for this attribute is
STRICT_VALIDITY_CHECKcanAppendChildAppendChild.
newChild of type
NodeNode to be appended.|
|
A boolean that is true if the |
|
|
DOMException. |
canInsertBeforeNode::InsertBefore operation would make this document
invalid with respect to the currently active AS. ISSUE: Describe
"valid" when referring to partially completed documents.
newChild of type
NodeNode to be inserted.refChild of type
NodeNode.|
|
A boolean that is true if the |
|
|
DOMException. |
canRemoveChildRemoveChild.
oldChild of type
NodeNode to be removed.|
|
A boolean that is true if the |
|
|
DOMException. |
canReplaceChildReplaceChild.
newChild of type
NodeNode.oldChild of type
NodeNode to be replaced.|
|
A boolean that is true if the |
|
|
DOMException. |
isValiddeep of type
booleandeep flag
on, causes isValid method to check for the whole subtree of the
current node for validity. Setting it to false only checks the
current node and its immediate child nodes against the grammar
corresponding to that element declaration .|
|
|
|
|
NO_AS_AVAILABLE: Exception is raised if the DocumentAS related to this node does not have any activeAS and wfValidityCheckLevel is set to PARTIAL or STRICT_VALIDITY_CHECK. |
This interface extends the Element interface with
additional methods for guided document editing. An object
implmenting this interface must also implement NodeAS
interface.
interface ElementAS : Element {
short contentType();
ASElementDeclaration getElementDeclaration()
raises(DOMException);
boolean canSetAttribute(in DOMString attrname,
in DOMString attrval);
boolean canSetAttributeNode(in Node node);
boolean canSetAttributeNodeNS(in Node node);
boolean canSetAttributeNS(in DOMString attrname,
in DOMString attrval,
in DOMString namespaceURI,
in DOMString localName);
boolean canRemoveAttribute(in DOMString attrname);
boolean canRemoveAttributeNS(in DOMString attrname,
inout DOMString namespaceURI);
boolean canRemoveAttributeNode(in Node node);
ASDOMStringList getChildElements();
ASDOMStringList getParentElements();
ASDOMStringList getAttributeList();
};
canRemoveAttributeattrname of type
DOMString|
|
true or false. |
canRemoveAttributeNSattrname of type
DOMStringnamespaceURI of type
DOMString|
|
true or false. |
canRemoveAttributeNodenode of type
NodeAttr node to remove from the attribute
list.|
|
true or false. |
canSetAttributeattrname of type
DOMStringattrval of type
DOMString|
|
true or false. |
canSetAttributeNSsetAttributeNS.
attrname of type
DOMStringattrval of type
DOMStringnamespaceURI of type
DOMStringnamespaceURI of namespace.localName of type
DOMStringlocalName of namespace.|
|
Success or failure. |
canSetAttributeNodenode of type
NodeNode in which the attribute can possibly be
set.|
|
Success or failure. |
canSetAttributeNodeNSnode of type
NodeAttr to be added to the attribute list.|
|
Success or failure. |
contentType|
|
Constant for mixed, empty, any, etc. |
getAttributeListASDOMStringList
containing all the possible Attrs that can appear with
this type of element.
|
List of possible attributes of this element. |
getChildElementsASDOMStringList
containing the possible Element names that can appear
as children of this type of element.
|
List of possible children element types of this element. |
getElementDeclaration|
ASElementDeclaration object if the implementation supports AS-EDIT feature. Otherwise null. |
|
|
If no abstract schema is present, raises this exception |
getParentElementsASDOMStringList
containing the possible Element names that can appear
as a parent of this type of element.
|
List of possible parent element types of this element. |
This interface extends the CharacterData interface
with additional methods for document editing. An object implmenting
this interface must also implement NodeAS interface.
interface CharacterDataAS : CharacterData {
boolean isWhitespaceOnly();
boolean canSetData(in unsigned long offset,
in DOMString arg)
raises(DOMException);
boolean canAppendData(in DOMString arg)
raises(DOMException);
boolean canReplaceData(in unsigned long offset,
in unsigned long count,
in DOMString arg)
raises(DOMException);
boolean canInsertData(in unsigned long offset,
in DOMString arg)
raises(DOMException);
boolean canDeleteData(in unsigned long offset,
in DOMString arg)
raises(DOMException);
};
canAppendDataarg of type
DOMString|
|
Success or failure. |
|
|
DOMException. |
canDeleteDataoffset of type
unsigned longarg of type
DOMString|
|
Success or failure. |
|
|
DOMException. |
canInsertDataoffset of type
unsigned longarg of type
DOMString|
|
Success or failure. |
|
|
DOMException. |
canReplaceDataoffset of type
unsigned longcount of type
unsigned longarg of type
DOMString|
|
Success or failure. |
|
|
DOMException. |
canSetDataoffset of type
unsigned longarg of type
DOMString|
|
Success or failure. |
|
|
DOMException. |
isWhitespaceOnly|
|
True if content only whitespace; false for non-whitespace if it is a text node in element content. |
This interface extends the DocumentType interface
with additional methods for document editing. An object implmenting
this interface must also implement NodeAS interface.
interface DocumentTypeAS : DocumentType {
readonly attribute ASDOMStringList definedElementTypes;
boolean isElementDefined(in DOMString elemTypeName);
boolean isElementDefinedNS(in DOMString elemTypeName,
in DOMString namespaceURI,
in DOMString localName);
boolean isAttributeDefined(in DOMString elemTypeName,
in DOMString attrName);
boolean isAttributeDefinedNS(in DOMString elemTypeName,
in DOMString attrName,
in DOMString namespaceURI,
in DOMString localName);
boolean isEntityDefined(in DOMString entName);
};
definedElementTypes
of type ASDOMStringList,
readonlyisAttributeDefinedelemTypeName of type
DOMStringattrName of type
DOMString|
|
A boolean that is true if the attribute is defined, false otherwise. |
isAttributeDefinedNSelemTypeName of type
DOMStringattrName of type
DOMStringnamespaceURI of type
DOMStringnamespaceURI of namespace.localName of type
DOMStringlocalName of namespace.|
|
A boolean that is true if the attribute with is defined, false otherwise. |
isElementDefinedelemTypeName of type
DOMString|
|
A boolean that is true if the element is defined, false otherwise. |
isElementDefinedNSelemTypeName of type
DOMStringnamespaceURI of type
DOMStringnamespaceURI of namespace.localName of type
DOMStringlocalName of namespace.|
|
A boolean that is true if the element is defined, false otherwise. |
isEntityDefinedentName of type
DOMString|
|
A boolean that is true if the entity is defined, false otherwise. |
This interface extends Attr to provide guided
editing of an XML document. An object implmenting this interface
must also implement NodeAS interface.
interface AttributeAS : Attr {
ASAttributeDeclaration getAttributeDeclaration();
ASNotationDeclaration getNotation()
raises(DOMException);
};
getAttributeDeclaration|
The attribute declaration corresponding to this attribute |
getNotation|
Returns the notation declaration for this attribute if the type is of notation type, null otherwise. |
|
|
DOMException |
This section contains DOM error handling interfaces.
Basic interface for DOM error handlers. If an application needs
to implement customized error handling for DOM such as AS or
Load/Save, it must implement this interface and then register an
instance using the setErrorHandler method. All errors
and warnings will then be reported through this interface.
Application writers can override the methods in a subclass to take
user-specified actions.
interface DOMErrorHandler {
void warning(in DOMLocator where,
in DOMString how,
in DOMString why)
raises(DOMSystemException);
void fatalError(in DOMLocator where,
in DOMString how,
in DOMString why)
raises(DOMSystemException);
void error(in DOMLocator where,
in DOMString how,
in DOMString why)
raises(DOMSystemException);
};
errorwhere of type DOMLocatorhow of type
DOMStringwhy of type
DOMString|
|
A subclass of DOMException. |
fatalErrorwhere of type DOMLocatorhow of type
DOMStringwhy of type
DOMString|
|
A subclass of DOMException. |
warningwhere of type DOMLocatorhow of type
DOMStringwhy of type
DOMString|
|
A subclass of DOMException. |
This interface provides document location information and is similar to a SAX locator object.
interface DOMLocator {
int getColumnNumber();
int getLineNumber();
DOMString getPublicID();
DOMString getSystemID();
Node getNode();
};
getColumnNumber|
|
The column number, or -1 if none is available. |
getLineNumber|
|
The line number, or -1 if none is available. |
getNode|
|
The NODE, or null if none is available. |
getPublicID|
|
A string containing the public identifier, or null if none is available. |
getSystemID|
|
A string containing the system identifier, or null if none is available. |
Editing and generating an abstract schema falls in the AS-editing world. The most obvious requirement for this set of requirements is for tools that author abstract schemas, either under user control, i.e., explicitly designed document types, or generated from other representations. The latter class includes transcoding tools, e.g., synthesizing an XML representation to match a database schema.
It's important to note here that a DTD's "internal subset" is part of the Abstract Schema, yet is loaded, stored, and maintained as part of the individual document instance. This implies that even tools which do not want to let users change the definition of the Document Type may need to support editing operations upon this portion of the AS. It also means that our representation of the AS must be aware of where each portion of its content resides, so that when the serializer processes this document it can write out just the internal subset. A similar issue may arise with external parsed entities, or if schemas introduce the ability to reference other schemas. Finally, the internal-subset case suggests that we may want at least a two-level representation of abstract schemas, so a single DOM representation of a DTD can be shared among several documents, each potentially also having its own internal subset; it's possible that entity layering may be represented the same way.
The API for altering the abstract schema may also be the AS's official interface with parsers. One of the ongoing problems in the DOM is that there is some information which must currently be created via completely undocumented mechanisms, which limits the ability to mix and match DOMs and parsers. Given that specialized DOMs are going to become more common (sub-classed, or wrappers around other kinds of storage, or optimized for specific tasks), we must avoid that situation and provide a "builder" API. Particular pairs of DOMs and parsers may bypass it, but it's required as a portability mechanism.
Note that several of these applications require that an AS be able to be created, loaded, and manipulated without/before being bound to a specific Document. A related issue is that we'd want to be able to share a single representation of an AS among several documents, both for storage efficiency and so that changes in the AS can quickly be tested by validating it against a set of known-good documents. Similarly, there is a known problem in DOM Level 2 where we assume that the DocumentType will be created before the Document, which is fine for newly-constructed documents but not a good match for the order in which an XML parser encounters this data; being able to "rebind" a Document to a new AS, after it has been created may be desirable.
As noted earlier, questions about whether one can alter the content of the AS via its syntax, via higher-level abstractions, or both, exist. It's also worth noting that many of the editing concepts from the Document tree still apply; users should probably be able to clone part of an AS, remove and re-insert parts, and so on.
In addition to using the abstract schema to validate a document instance, applications would like to be able to use it to guide construction and editing of documents, which falls into the document-editing world. Examples of this sort of guided editing already exist, and are becoming more common. The necessary queries can be phrased in several ways, the most useful of which may be a combination of "what does the DTD allow me to insert here" and "if I insert this here, will the document still be valid". The former is better suited to presentation to humans via a user interface, and when taken together with sub-tree validation may subsume the latter.
It has been proposed that in addition to asking questions about specific parts of the abstract schema, there should be a reasonable way to obtain a list of all the defined symbols of a given type (element, attribute, entity) independent of whether they're valid in a given location; that might be useful in building a list in a user-interface, which could then be updated to reflect which of these are relevant for the program's current state.
Remember that namespaces also weigh in on this issue, in the case of attributes, a "can-this-go-there" may prompt a namespace-well-formedness check and warn you if you're about to conflict with or overwrite another attribute with the same namespaceURI/localName but different prefix, or same nodeName but different namespaceURI.
We have to deal with the fact that "the shortest distance between two valid documents may be through an invalid one". Users may want to know several levels of detail (all the possible children, those which would be valid given what precedes this point, those which would be valid given both preceding and following siblings). Also, once XML Schemas introduce context sensitive validity, we may have to consider the effect of children as well as the individual node being inserted.
The most obvious use for an abstract schema (DTD or XML Schema or any Abstract Schema) is to use it to validate that a given XML document is in fact a properly constructed instance of the document type described by this AS. This again falls into the document-editing world. The XML spec only discusses performing this test at the time the document is loaded into the "processor", which most of us have taken to mean that this check should be performed at parse time. But it is obviously desirable to be able to validate again a document -- or selected subtrees -- at other times. One such case would be validating an edited or newly constructed document before serializing it or otherwise passing it to other users. This issue also arises if the "internal subset" is altered -- or if the whole Abstract Schema changes.
In the past, the DOM has allowed users to create invalid
documents, and assumed the serializer would accept the task of
detecting problems and announcing/repairing them when the document
was written out in XML syntax... or that they would be checked for
validity when read back in. We considered adding validity checks to
the DOM's existing editing operations to prevent creation of
invalid documents, but are currently inclined against this for
several reasons. First, it would impose a significant amount of
computational overhead to the DOM, which might be unnecessary in
many situations, e.g., if the change is occurring in a context
where we know the result will be valid. Second, "the shortest
distance between two good documents may be through a bad document".
Preventing a document from becoming temporarily invalid may impose
a considerable amount of additional work on higher-level code and
users Hence our current plan is to continue to permit editing to
produce invalid DOMs, but provide operations which permit a user to
check the validity of a node on demand. If needed one can use
continuousValidityChecking flag to ensure that the DOM
remains valid during the editing process.
Note that validation includes checking that ID attributes are unique, and that IDREFs point to IDs which actually exist.
XML defined the "well-formed" (WF) state for documents which are parsed without reference to their DTDs. Knowing that a document is well-formed may be useful by itself even when a DTD is available. For example, users may wish to deliberately save an invalid document, perhaps as a checkpoint before further editing. Hence, the AS feature will permit both full validity checking (see previous section) and "lightweight" WF checking, as requested by the caller, as well as processing entity declarations in the AS even if validation is not turned on. This falls within the document-editing world.
While the DOM inherently enforces some of XML's well-formedness conditions (proper nesting of elements, constraints on which children may be placed within each node), there are some checks that are not yet performed. These include:
In addition, Namespaces introduce their own concepts of well-formedness. Specifically:
namespaceNormalize operation, which would
create the implied declarations and reconcile conflicts in some
reasonably standardized manner. This may be a major undertaking,
since some DOMs may be using the namespace to direct subclassing of
the nodes or similar special treatment; as with the existing
normalize method, you may be left with a
different-but-equivalent set of node objects.In the past, the DOM has allowed users to create documents which violate these rules, and assumed the serializer would accept the task of detecting problems and announcing/repairing them when the document was written out in XML syntax. We considered adding WF checks to the DOM's existing editing operations to prevent WF violations from arising, but are currently inclined against this for two reasons. First, it would impose a significant amount of computational overhead to the DOM, which might be unnecessary in many situations (for example, if the change is occurring in a context where we know the illegal characters have already been prevented from arising). Second, "the shortest distance between two good documents may be through a bad document" -- preventing a document from becoming temporarily ill-formed may impose a considerable amount of additional work on higher-level code and users. (Note possible issue for Serialization: In some applications, being able to save and reload marginally poorly-formed DOMs might be useful -- editor checkpoint files, for example.) Hence our current plan is to continue to permit editing to produce ill-formed DOMs, but provide operations which permit a user to check the well-formedness of a node on demand, and possibly provide some of the primitive (e.g., string-checking) functions directly.