Интерфейс DOMConfiguration

Интерфейс DOMConfiguration представляет собой конфигурацию документа и поддерживает таблицу распознанных параметров. Используя конфигурацию, можно изменить поведение Document.normalizeDocument(), например, заменить узлы CDATASection на узлы Text или указать тип схемы, который должен использоваться при запросе валидации Document. Объекты DOMConfiguration также используются в [DOM Level 3 Load and Save] в интерфейсах DOMParser и DOMSerializer.

Имена параметров, используемые объектом DOMConfiguration, определены в спецификациях DOM Level 3. Названия нечувствительны к регистру. Для предотвращения возможных конфликтов, как правило, имена, относящиеся к параметрам, определенным за пределами спецификации DOM, должны быть уникальными. Поскольку параметры представлены как свойства, рекомендуется следовать разделу 5.16 Идентификаторы [Unicode] с добавлением символа «-» (HYPHEN-MINUS), но это не навязывается реализацией DOM. Реализации DOM Level 3 Core обязаны распознавать все параметры, определенные в этой спецификации. Некоторые значения параметров также могут быть обязательными для поддержки реализацией. Обратитесь к определению параметра, чтобы узнать, требуется ли поддержка значения.

Примечание: Параметры аналогичны функциям и свойствам, используемым в SAX2 [SAX].

Следующий список параметров, определенных в DOM:

"canonical-form"

true

[необязательно] Канонизировать документ в соответствии с правилами, указанными в [Canonical XML], например, удаляя узел DocumentType (если таковой есть) из дерева или удаляя избыточные объявления пространств имён из каждого элемента. Обратите внимание, что это ограничено тем, что может быть представлено в DOM; в частности, нет способа указать порядок атрибутов в DOM. Кроме того, установка этого параметра в значение true также установит состояние перечисленных ниже параметров. Позднейшие изменения состояния одного из этих параметров приведут к возврату "canonical-form" к значению false. Параметры, установленные в значение false: "entities", " normalize-characters", "cdata-sections". Параметры, установленные в значение true: "namespaces", "namespace-declarations", "well-formed", "element-content-whitespace". Другие параметры не изменяются, если явно не указано в описании параметров.

false

[обязательно] (по умолчанию)Не канонизировать документ.

"cdata-sections"

true

[обязательно] (по умолчанию)Сохранять узлы CDATASection в документе.

false

[обязательно]Преобразовывать узлы CDATASection в документе в узлы Text. Новый узел Text затем объединяется с любым смежным узлом Text.

"check-character-normalization"

true

[необязательно] Проверить, являются ли символы в документе полностью нормализованными, как определено в приложении B [XML 1.1]. При обнаружении последовательности символов, не прошедшей проверку нормализации, выдаётся ошибка с DOMError.type равным "check-character-normalization-failure".

false

[обязательно] (по умолчанию)Не проверять, нормализованы ли символы.

"comments"

true

[обязательно] (по умолчанию)Сохранять узлы Comment в документе.

false

[обязательно]Удалять узлы Comment из документа.

"datatype-normalization"

true

[необязательно] Выводить нормализованные значения схемы в дереве, такие как нормализованные значения XML Schema в случае XML Schema. Поскольку этому параметру требуется информация о схеме, параметр "validate" также будет установлен в значение true. Включение этого параметра, когда "validate" равен false, не повлияет на результат и нормализация по схеме не произойдёт.

Примечание: Поскольку документ содержит результат обработки XML 1.0, этот параметр не применяется к нормализации значений атрибутов, как определено в разделе 3.3.3 [XML 1.0], и предназначен только для языков схем, отличных от определения типа документа (DTD).

false

[обязательно] (по умолчанию) Не выполнять нормализацию схемы в дереве.

"element-content-whitespace"

true

[обязательно] (по умолчанию)Сохранять все пробелы в документе.

false

[необязательно] Удалять все узлы Text, содержащие пробелы в содержимом элемента, как описано в [пробелы в содержимом элемента]. Реализация должна использовать атрибут Text.isElementContentWhitespace для определения, следует ли удалять узел Text.

"entities"

true

[обязательно] (по умолчанию)Сохранять узлы EntityReference в документе.

false

[обязательно] Удалять все узлы EntityReference из документа, помещая расширения сущностей непосредственно на их место. Узлы Text нормализуются, как определено в Node.normalize. В документе сохраняются только нерасширенные ссылки на сущности.

Примечание: Этот параметр не влияет на узлы Entity.

"error-handler"

[обязательно] Содержит объект DOMErrorHandler. Если в документе обнаружена ошибка, реализация вызовет обработчик DOMErrorHandler, зарегистрированный с помощью этого параметра. Реализация может предоставить объект DOMErrorHandler по умолчанию. При вызове DOMError.relatedData будет содержать ближайший к месту возникновения ошибки узел. Если реализация не может определить узел, где произошла ошибка, DOMError.relatedData будет содержать узел Document.

"infoset"

true

[обязательно] Сохранять в документе информацию, определённую в XML Information Set [XML Information Set]. Это устанавливает следующие параметры в значение false: " validate-if-schema", "entities", "datatype-normalization", "cdata-sections ".Это устанавливает следующие параметры в значение true: " namespace-declarations", "well-formed", "element-content-whitespace", " comments", "namespaces". Другие параметры не изменяются, если явно не указано в описании параметров. Обратите внимание, что запросив этот параметр с getParameter, возвращается значение true только в том случае, если отдельные перечисленные выше параметры установлены соответствующим образом.

false

Установка infoset в значение false не влияет на результат.

"namespaces"

true

[обязательно] (по умолчанию)Выполнить обработку пространств имён, как определено в.

false

[необязательно]Не выполнять обработку пространств имён.

"namespace-declarations"

Этот параметр не имеет эффекта, если параметр "namespaces" установлен в значение false.

true

[обязательно] (по умолчанию)Включать атрибуты объявления пространств имён, указанные или заданные по умолчанию схемой, в документ. См. также разделы "Declaring Namespaces" в [XML Namespaces] и [XML Namespaces 1.1].

false

[обязательно]Удалить все атрибуты объявления пространств имён. Префиксы пространств имён ( Node.prefix) сохраняются даже если этот параметр установлен в значение false.

"normalize-characters"

true

[необязательно] Полностью нормализовать символы в документе, как определено в приложении B [XML 1.1].

false

[обязательно] (по умолчанию)Не выполнять нормализацию символов.

"schema-location"

[необязательно] Представляет объект DOMString, содержащий список URI, разделённых пробелами (символы, соответствующие нетерминальному производству S, определённому в разделе 2.3 [XML 1.0]), которые представляют схемы, против которых должно произойти валидация, т.е. текущую схему. Типы схем, указанные в этом списке, должны соответствовать типу, указанному с помощью schema-type, в противном случае поведение реализации не определено. Схемы, указанные с помощью этого свойства, имеют приоритет перед информацией о схеме, указанной в самом документе. Для схем, учитывающих пространства имён, если схема, указанная с помощью этого свойства, и схема, указанная в экземпляре документа (т.е. с помощью атрибута schemaLocation), в документе схемы (т.е. с помощью механизмов схемы import ) имеют одинаковое пространство имён, будет использоваться схема, указанная пользователем с помощью этого свойства. Если две схемы, указанные с помощью этого свойства, имеют одинаковое пространство имён или не имеют пространства имён, поведение зависит от реализации. Если ни один адрес не указан, этот параметр null

Примечание: Параметр "schema-location" игнорируется, если значение параметра "schema-type" не задано. Настоятельно рекомендуется установить значение Document.documentURI для успешной обработки любых внешних сущностей, на которые ссылаются.

"schema-type"

[необязательно] Представляет объект DOMString, содержащий абсолютный URI и представляющий тип языка схемы, используемого для валидации документа. Обратите внимание, что лексическая проверка абсолютного URI не выполняется. Если этот параметр не задан, реализация может предоставить значение по умолчанию на основе поддерживаемых языков схем и языка схемы во время загрузки. Если значение не указано, этот параметр null.

Примечание: Для XML Schema [XML Schema Part 1] приложения должны использовать значение "http://www.w3.org/2001/XMLSchema". Для XML DTD [XML 1.0] приложения должны использовать значение "http://www.w3.org/TR/REC-xml". Другие языки схем находятся вне сферы ответственности W3C и поэтому должны рекомендовать абсолютный URI для использования этого метода.

"split-cdata-sections"

true

[обязательно] (по умолчанию)Разделять секции CDATA, содержащие маркер окончания секции CDATA ']]>'. При разделении секции CDATA выдаётся предупреждение, где DOMError.type равно "cdata-sections-splitted", и DOMError.relatedData равно первому узлу CDATASection в порядке документа, полученному в результате разделения.

false

[обязательно]Выдавать ошибку, если узел CDATASection содержит непредставимый символ.

"validate"

true

[необязательно] Требует проверки документа против схемы (например, XML-схемы, DTD или любого другого типа или представления схемы) во время его нормализации, как определено в [XML 1.0]. Если обнаружены ошибки валидации или схема не найдена, об этом уведомляется обработчик ошибок. Нормализованные по схеме значения не будут доступны согласно используемой схеме, если параметр "datatype-normalization" не true. Этот параметр переоценит:

• узлы атрибутов с Attr.specified равным false, как указано в описании интерфейса Attr;
• значение атрибута Text.isElementContentWhitespace для всех узлов Text;
• значение атрибута Attr.isId для всех узлов Attr;
• атрибуты Element.schemaTypeInfo и Attr.schemaTypeInfo.

Примечание: параметры "validate-if-schema" и "validate" взаимно исключают друг друга; установка одного из них в true установит другой в false. Приложения также должны рассмотреть возможность установки параметра "well-formed" в true, что является значением по умолчанию для этого параметра, при проверке документа.

false

[обязательно] (по умолчанию) Не выполнять обработку схемы, включая обработку внутреннего подмножества. Информация о значениях атрибутов по умолчанию сохраняется. Обратите внимание, что валидация всё равно может произойти, если "validate-if-schema" true .

"validate-if-schema"

true

[необязательно] Включить валидацию только в том случае, если в схеме (независимо от того, где она находится, т.е. XML-схема, DTD или любой другой тип или представление схемы) найдено объявление для элемента документа. Если валидация включена, этот параметр ведет себя так же, как параметр "validate", установленный в true.

Примечание: параметры "validate-if-schema" и "validate" взаимно исключают друг друга; установка одного из них в true установит другой в false.

false

[обязательно] (по умолчанию) Обработка схемы не должна выполняться, если у документа есть схема, включая обработку внутреннего подмножества. Информация о значениях атрибутов по умолчанию сохраняется. Обратите внимание, что валидация всё равно должна произойти, если "validate " true.

"well-formed"

true

[обязательно] (по умолчанию) Проверить, являются ли все узлы XML-форматными согласно версии XML, используемой в Document.xmlVersion:

• проверить, содержит ли атрибут Node.nodeName недопустимые символы в соответствии с типом узла и сгенерировать DOMError типа "wf-invalid-character-in-node-name", с DOMError.SEVERITY_ERROR уровнем серьезности, при необходимости;
• проверить, содержит ли текстовое содержимое внутри узлов Attr, Element, Comment, Text, CDATASection недопустимые символы и сгенерировать DOMError типа "wf-invalid-character", с DOMError.SEVERITY_ERROR уровнем серьезности, при необходимости;
• проверить, содержит ли данные внутри узлов ProcessingInstruction недопустимые символы и сгенерировать DOMError типа "wf-invalid-character", с DOMError.SEVERITY_ERROR уровнем серьезности, при необходимости;

false

[необязательно] Не проверять XML-форматность.

Разрешение идентификаторов систем, связанных с сущностями, выполняется с использованием Document.documentURI. Однако, когда функция "LS", определенная в [DOM Level 3 Load and Save], поддерживается реализацией DOM, параметр "resource-resolver" также может использоваться с объектами DOMConfiguration , прикрепленными к узлам Document. Если этот параметр установлен, Document.normalizeDocument() вызовет обработчик ресурсов вместо использования Document.documentURI.

См. также Спецификацию Объектной модели документа (DOM) уровня 3 Core.

Методы

setParameter

void setParameter(String name,
                  Object value)
           throws DOMException

Устанавливает значение параметра.

Параметры:

name - Имя параметра, который нужно установить.

value - Новое значение или null если пользователь хочет сбросить параметр. Хотя тип параметра value определён как DOMUserData, тип объекта должен соответствовать типу, определённому в определении параметра. Например, если параметр "error-handler", значение должно быть типа DOMErrorHandler.

Исключения:

DOMException - NOT_FOUND_ERR: Вызывается, если имя параметра не распознано.
NOT_SUPPORTED_ERR: Вызывается, если имя параметра распознано, но запрошенное значение не может быть установлено.
TYPE_MISMATCH_ERR: Вызывается, если тип значения для данного имени параметра несовместим с ожидаемым типом значения.

getParameter

Object getParameter(String name)
             throws DOMException

Возвращает значение параметра, если оно известно.

Параметры:

name - Имя параметра.

Возвращает:

Текущий объект, связанный с указанным параметром, или null если объект не связан или параметр не поддерживается.

Исключения:

DOMException - NOT_FOUND_ERR: Вызывается, если имя параметра не распознано.

canSetParameter

boolean canSetParameter(String name,
                        Object value)

Проверяет, поддерживается ли установка параметра в определенное значение.

Параметры:

name - Имя параметра для проверки.

value - Объект. Если null, возвращаемое значение равно true.

Возвращает:

true если параметр можно успешно установить в указанное значение или false если параметр не распознан или запрошенное значение не поддерживается. Это не изменяет текущее значение самого параметра.

getParameterNames

DOMStringList getParameterNames()

Список параметров, поддерживаемых этим объектом DOMConfiguration и для которых приложение может установить по крайней мере одно значение. Обратите внимание, что этот список может также содержать имена параметров, определённых вне этой спецификации.