Интерфейс DOMConfiguration

public interface DOMConfiguration

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

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

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

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

"canonical-form"

true: [необязательно] Канонизировать документ в соответствии с правилами, указанными в [Каноническом XML], например, удалив узел DocumentType (если есть) из дерева или удалив избыточные объявления пространств имён из каждого элемента. Обратите внимание, что это ограничено возможностями представления в DOM; в частности, нет способа указать порядок атрибутов в DOM. Кроме того, установка этого параметра в true также установит состояние перечисленных ниже параметров. Позднее изменения состояния одного из этих параметров вернут «каноническую форму» к false. Параметры, установленные в false: «сущности», «нормализация символов», «разделы CDATA». Параметры, установленные в true: «пространства имён», «объявления пространств имён», «корректность», «пробелы в содержимом элемента». Другие параметры не изменяются, если явно не указано в описании параметров.
false: [обязательно] (по умолчанию)Не канонизировать документ.

"cdata-sections"

true: [обязательно] (по умолчанию)Сохранить узлы CDATASection в документе.
false: [обязательно]Преобразовать узлы CDATASection в документе в узлы Text. Новый узел Text затем объединяется с любым соседним узлом Text.

"check-character-normalization"

true: [необязательно] Проверить, являются ли символы в документе полностью нормализованными, как определено в приложении B [XML 1.1]. При обнаружении последовательности символов, не прошедших проверку нормализации, выдаётся ошибка с DOMError.type равной «провал-проверки-нормализации-символов».
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], и предназначен только для языков схем, отличных от Document Type Definition (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: «валидация-при-наличии-схемы», «сущности», «нормализация-типов-данных», «разделы-CDATA». Это приводит к установке следующих параметров в true: «объявления-пространств-имён», «корректность», «пробелы-в-содержимом-элемента», «комментарии», «пространства-имён». Другие параметры не изменяются, если явно не указано в описании параметров. Обратите внимание, что запросы к этому параметру с использованием getParameter возвращают true только в том случае, если указанные выше параметры установлены должным образом.
false: Указание параметра infoset в значение false не имеет эффекта.

"namespaces"

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

"namespace-declarations"

Этот параметр не имеет эффекта, если параметр «пространства имён» установлен в false.

true: [обязательно] (по умолчанию)Включить атрибуты объявления пространств имён, указанные или заданные по умолчанию из схемы, в документе. См. также разделы «Объявление пространств имён» в [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) имеют одинаковое targetNamespace, будет использоваться схема, указанная пользователем с помощью этого свойства. Если две схемы, указанные с помощью этого свойства, имеют одинаковое targetNamespace или не имеют пространства имён, поведение зависит от реализации. Если не указано расположение, этот параметр 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.

См. также Спецификацию Document Object Model (DOM) Level 3 Core.

С момента:: 1.5, DOM Level 3

Методы

Модификатор и тип	Метод	Описание
`boolean`	`canSetParameter(String name, Object value)`	Проверка поддержки установки параметра со значением.
`Object`	`getParameter(String name)`	Возврат значения параметра, если оно известно.
`DOMStringList`	`getParameterNames()`	Список параметров, поддерживаемых этим объектом `DOMConfiguration` и для которых приложение может установить хотя бы одно значение.
`void`	`setParameter(String name, Object value)`	Установка значения параметра.

Методы

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 и для которых приложение может установить хотя бы одно значение. Обратите внимание, что этот список также может содержать имена параметров, определённые за пределами данной спецификации.

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.xml/org/w3c/dom/DOMConfiguration.html