Класс DocumentBuilderFactory

java.lang.Object
- javax.xml.parsers.DocumentBuilderFactory

public abstract class DocumentBuilderFactory
extends Object

Определяет фабричный API, позволяющий приложениям получать анализатор, который создаёт деревья DOM-объектов из XML-документов.

Версия:: $Revision: 1.9 $, $Date: 2010/05/25 16:19:44 $

Конструкторы

Модификатор	Конструктор и описание
`protected`	`DocumentBuilderFactory()` Защищённый конструктор для предотвращения создания экземпляров.

Методы

Модификатор и тип	Метод и описание
`abstract Object`	`getAttribute(String name)` Позволяет пользователю получить определённые атрибуты на основе реализации.
`abstract boolean`	`getFeature(String name)` Получение состояния указанного параметра.
`Schema`	`getSchema()` Получение объекта `Schema`, заданного методом `setSchema(Schema schema)`.
`boolean`	`isCoalescing()` Указывает, сконфигурирован ли фабричный объект для создания анализаторов, которые преобразуют узлы CDATA в текстовые узлы и добавляют их к смежному (если есть) текстовому узлу.
`boolean`	`isExpandEntityReferences()` Указывает, сконфигурирован ли фабричный объект для создания анализаторов, которые обрабатывают ссылки на сущности.
`boolean`	`isIgnoringComments()` Указывает, сконфигурирован ли фабричный объект для создания анализаторов, которые игнорируют комментарии.
`boolean`	`isIgnoringElementContentWhitespace()` Указывает, сконфигурирован ли фабричный объект для создания анализаторов, которые игнорируют пренебрежимые пробелы в содержимом элемента.
`boolean`	`isNamespaceAware()` Указывает, сконфигурирован ли фабричный объект для создания анализаторов, которые учитывают пространства имён.
`boolean`	`isValidating()` Указывает, сконфигурирован ли фабричный объект для создания анализаторов, которые валидируют содержимое XML во время разбора.
`boolean`	`isXIncludeAware()` Получение состояния обработки XInclude.
`abstract DocumentBuilder`	`newDocumentBuilder()` Создаёт новый экземпляр `DocumentBuilder` с использованием текущих параметров конфигурации.
`static DocumentBuilderFactory`	`newInstance()` Получение нового экземпляра `DocumentBuilderFactory`.
`static DocumentBuilderFactory`	`newInstance(String factoryClassName, ClassLoader classLoader)` Получение нового экземпляра `DocumentBuilderFactory` по имени класса.
`abstract void`	`setAttribute(String name, Object value)` Позволяет пользователю установить определённые атрибуты на основе реализации.
`void`	`setCoalescing(boolean coalescing)` Указывает, что анализатор, созданный этим кодом, будет преобразовывать узлы CDATA в текстовые узлы и добавлять их к смежному (если есть) текстовому узлу.
`void`	`setExpandEntityReferences(boolean expandEntityRef)` Указывает, что анализатор, созданный этим кодом, будет обрабатывать ссылки на сущности.
`abstract void`	`setFeature(String name, boolean value)` Установка параметра для этого `DocumentBuilderFactory` и `DocumentBuilder` объектов, созданных этой фабрикой.
`void`	`setIgnoringComments(boolean ignoreComments)` Указывает, что анализатор, созданный этим кодом, будет игнорировать комментарии.
`void`	`setIgnoringElementContentWhitespace(boolean whitespace)` Указывает, что анализаторы, созданные этой фабрикой, должны удалять пробелы в содержимом элемента (иногда неофициально называемые «игнорируемыми пробелами»), при разборе XML-документов (см. XML Rec 2.10).
`void`	`setNamespaceAware(boolean awareness)` Указывает, что анализатор, созданный этим кодом, будет поддерживать XML-пространства имён.
`void`	`setSchema(Schema schema)` Установка `Schema`, который будет использоваться анализаторами, созданными из этой фабрики.
`void`	`setValidating(boolean validating)` Указывает, что созданный анализатор будет валидировать документы при разборе.
`void`	`setXIncludeAware(boolean state)` Установка состояния обработки XInclude.

Методы, унаследованные от класса java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Конструкторы

DocumentBuilderFactory

protected DocumentBuilderFactory()

Защищённый конструктор для предотвращения создания экземпляров. Используйте newInstance().

Методы

newInstance

public static DocumentBuilderFactory newInstance()

Получить новый экземпляр DocumentBuilderFactory. Этот статический метод создаёт новый экземпляр фабрики. Этот метод использует следующую упорядоченную процедуру поиска для определения класса реализации DocumentBuilderFactory для загрузки:

Использование системной переменной javax.xml.parsers.DocumentBuilderFactory.
Использование файла свойств "lib/jaxp.properties" в каталоге JRE. Этот файл конфигурации имеет стандартный java.util.Properties формат и содержит полное имя класса реализации с ключом, являющимся системной переменной, определённой выше. Файл jaxp.properties читается только один раз реализацией JAXP, а его значения затем кэшируются для последующего использования. Если файл не существует во время первой попытки его чтения, дальнейшие попытки проверки его существования не предпринимаются. После первого чтения файла свойств jaxp.properties изменить значение любого свойства невозможно.
Использует средства загрузки поставщиков услуг, определённые классом ServiceLoader, для попытки найти и загрузить реализацию службы с помощью механизма загрузки по умолчанию: средство загрузки поставщика услуг будет использовать потоковый контекстный загрузчик класса для попытки загрузки службы. Если контекстный загрузчик класса равен null, будет использован системный загрузчик класса.
В противном случае возвращается системная реализация по умолчанию.

После того, как приложение получило ссылку на DocumentBuilderFactory, оно может использовать фабрику для настройки и получения экземпляров парсера.

Совет по устранению неполадок

Установка системной переменной jaxp.debug заставит этот метод выводить множество сообщений отладки в System.err о выполняемых действиях и местах поиска.

Если у вас проблемы с загрузкой DocumentBuilder, попробуйте:

java -Djaxp.debug=1 YourProgram ....

Возвращает:: Новый экземпляр DocumentBuilderFactory
Исключение:: FactoryConfigurationError - в случае ошибки конфигурации службы или если реализация недоступна или не может быть создана.

newInstance

public static DocumentBuilderFactory newInstance(String factoryClassName,
                                                 ClassLoader classLoader)

Получить новый экземпляр DocumentBuilderFactory по имени класса. Эта функция полезна, когда в пути к классам присутствует несколько поставщиков. Она даёт больше контроля приложению, поскольку оно может указать, какой поставщик должен быть загружен.

После получения ссылки на DocumentBuilderFactory приложение может использовать фабрику для настройки и получения экземпляров парсера.

Совет по устранению неполадок

Если у вас проблемы, попробуйте:

java -Djaxp.debug=1 YourProgram ....

Параметры:: factoryClassName - полное имя класса фабрики, предоставляющего реализацию javax.xml.parsers.DocumentBuilderFactory.; classLoader - ClassLoader, используемый для загрузки класса фабрики. Если null используется контекстный загрузчик класса текущего Thread для загрузки класса фабрики.
Возвращает:: Новый экземпляр DocumentBuilderFactory
Исключение:: FactoryConfigurationError - если factoryClassName является null, или класс фабрики не может быть загружен или создан.
С:: 1.6
См. также:: newInstance()

newDocumentBuilder

public abstract DocumentBuilder newDocumentBuilder()
                                            throws ParserConfigurationException

Создаёт новый экземпляр DocumentBuilder с использованием текущих параметров конфигурации.

Возвращает:: Новый экземпляр DocumentBuilder.
Исключение:: ParserConfigurationException - если DocumentBuilder не может быть создан, удовлетворяя запрошенную конфигурацию.

setNamespaceAware

public void setNamespaceAware(boolean awareness)

Указывает, что парсер, созданный этим кодом, будет поддерживать XML-пространства имён. По умолчанию это значение установлено в false

Параметры:: awareness - true, если созданный парсер будет поддерживать XML-пространства имён; false в противном случае.

setValidating

public void setValidating(boolean validating)

Указывает, что парсер, созданный этим кодом, будет проверять документы по мере их разбора. По умолчанию значение установлено в false.

Примечание: «проверка» здесь означает валидирующий парсер, как определено в рекомендации по XML. Другими словами, это в основном просто управляет проверкой DTD. (за исключением устаревших двух свойств, определённых в JAXP 1.2.)

Для использования современных языков схем, таких как W3C XML Schema или RELAX NG вместо DTD, вы можете настроить свой парсер на невалидирующий парсер, оставив метод setValidating(boolean) false, а затем использовать метод setSchema(Schema) для связывания схемы с парсером.

Параметры:: validating - true, если созданный парсер будет проверять документы по мере их разбора; false в противном случае.

setIgnoringElementContentWhitespace

public void setIgnoringElementContentWhitespace(boolean whitespace)

Указывает, что парсеры, созданные этой фабрикой, должны удалять пробелы в содержимом элементов (иногда неофициально называемые «пробелами, допускаемыми для игнорирования») при разборе XML-документов (см. XML Rec 2.10). Обратите внимание, что будут удалены только те пробелы, которые находятся непосредственно внутри содержимого элемента, имеющего только модель содержимого элемента (см. XML Rec 3.2.1). Из-за зависимости от модели содержимого данная настройка требует, чтобы парсер находился в режиме валидации. По умолчанию значение установлено в false.

Параметры:: whitespace - true, если созданный парсер должен удалять пробелы в содержимом элемента при разборе XML-документов; false в противном случае.

setExpandEntityReferences

public void setExpandEntityReferences(boolean expandEntityRef)

Указывает, что парсер, созданный этим кодом, будет расширять узлы ссылок на сущности. По умолчанию значение установлено в true

Параметры:: expandEntityRef - true, если созданный парсер будет расширять узлы ссылок на сущности; false в противном случае.

setIgnoringComments

public void setIgnoringComments(boolean ignoreComments)

Указывает, что парсер, созданный этим кодом, будет игнорировать комментарии. По умолчанию значение установлено в false.

Параметры:: ignoreComments - значение boolean для игнорирования комментариев во время обработки

setCoalescing

public void setCoalescing(boolean coalescing)

Указывает, что парсер, созданный этим кодом, будет преобразовывать узлы CDATA в узлы Text и добавлять их к смежному (если таковой есть) узлу text. По умолчанию значение установлено в false

Параметры:: coalescing - true, если созданный парсер преобразует узлы CDATA в узлы Text и добавляет их к смежному (если таковой есть) узлу text; false в противном случае.

isNamespaceAware

public boolean isNamespaceAware()

Указывает, настроена ли фабрика для создания парсеров, осознающих пространства имён.

Возвращает:: true, если фабрика настроена на создание парсеров, осознающих пространства имён; false в противном случае.

isValidating

public boolean isValidating()

Указывает, настроена ли фабрика на создание парсеров, которые валидируют XML-содержимое во время разбора.

Возвращает:: true, если фабрика настроена на создание парсеров, которые валидируют XML-содержимое во время разбора; false в противном случае.

isIgnoringElementContentWhitespace

public boolean isIgnoringElementContentWhitespace()

Указывает, настроена ли фабрика на создание парсеров, которые игнорируют пробелы, допускаемые для игнорирования, в содержимом элемента.

Возвращает:: true, если фабрика настроена на создание парсеров, которые игнорируют пробелы, допускаемые для игнорирования, в содержимом элемента; false в противном случае.

isExpandEntityReferences

public boolean isExpandEntityReferences()

Указывает, настроена ли фабрика на создание парсеров, которые расширяют узлы ссылок на сущности.

Возвращает:: true, если фабрика настроена на создание парсеров, которые расширяют узлы ссылок на сущности; false в противном случае.

isIgnoringComments

public boolean isIgnoringComments()

Указывает, настроена ли фабрика на создание парсеров, которые игнорируют комментарии.

Возвращает:: true, если фабрика настроена на создание парсеров, которые игнорируют комментарии; false в противном случае.

isCoalescing

public boolean isCoalescing()

Указывает, настроена ли фабрика на создание парсеров, которые преобразуют узлы CDATA в узлы Text и добавляют их к смежному (если таковой есть) узлу Text.

Возвращает:: true, если фабрика настроена на создание парсеров, которые преобразуют узлы CDATA в узлы Text и добавляют их к смежному (если таковой есть) узлу Text; false в противном случае.

setAttribute

public abstract void setAttribute(String name,
                                  Object value)
                           throws IllegalArgumentException

Позволяет пользователю установить определённые атрибуты в базовой реализации.

Все реализации, поддерживающие JAXP 1.5 или более позднюю версию, обязаны поддерживать свойства XMLConstants.ACCESS_EXTERNAL_DTD и XMLConstants.ACCESS_EXTERNAL_SCHEMA.

Установление свойства XMLConstants.ACCESS_EXTERNAL_DTD ограничивает доступ к внешним DTD, внешним ссылкам на сущности протоколами, указанными в свойстве. Если доступ запрещён во время разбора из-за ограничения этого свойства, SAXException будет выброшено методами разбора, определёнными DocumentBuilder.

Установление свойства XMLConstants.ACCESS_EXTERNAL_SCHEMA ограничивает доступ к внешним схемам, заданным атрибутом schemaLocation, протоколами, указанными в свойстве. Если доступ запрещён во время разбора из-за ограничения этого свойства, SAXException будет выброшено методами разбора, определёнными DocumentBuilder.

Параметры:: name - Имя атрибута.; value - Значение атрибута.
Исключения:: IllegalArgumentException - выбрасывается, если базовая реализация не распознаёт атрибут.

getAttribute

public abstract Object getAttribute(String name)
                             throws IllegalArgumentException

Позволяет пользователю получить определённые атрибуты из базовой реализации.

Параметры:: name - Имя атрибута.
Возвращает:: значение Значение атрибута.
Исключения:: IllegalArgumentException - выбрасывается, если базовая реализация не распознаёт атрибут.

setFeature

public abstract void setFeature(String name,
                                boolean value)
                         throws ParserConfigurationException

Устанавливает свойство для этого DocumentBuilderFactory и DocumentBuilderы, созданных этой фабрикой.

Имена свойств — полностью квалифицированные URI. Реализации могут определять свои собственные свойства. ParserConfigurationException выбрасывается, если этот DocumentBuilderFactory или созданные им DocumentBuilderы не поддерживают это свойство. Возможно, что DocumentBuilderFactory может выставлять значение свойства, но не сможет изменить его состояние.

Все реализации обязаны поддерживать свойство XMLConstants.FEATURE_SECURE_PROCESSING. Когда свойство:

true: реализация ограничит обработку XML, чтобы соответствовать ограничениям реализации. Примерами являются ограничения расширения сущностей и конструкции XML-схем, которые потребляют большие объёмы ресурсов. Если обработка XML ограничена по соображениям безопасности, это будет сообщено вызовом зарегистрированного ErrorHandler.fatalError(SAXParseException exception). См. DocumentBuilder.setErrorHandler(org.xml.sax.ErrorHandler errorHandler).
false: реализация будет обрабатывать XML в соответствии со спецификациями XML без учёта возможных ограничений реализации.

Параметры:: name - Имя свойства.; value - Состояние свойства true или false.
Исключения:: ParserConfigurationException - если этот DocumentBuilderFactory или созданные им DocumentBuilderы не поддерживают это свойство.; NullPointerException - Если параметр name равен null.

getFeature

public abstract boolean getFeature(String name)
                            throws ParserConfigurationException

Получает состояние указанного свойства.

Параметры:: name - Имя свойства.
Возвращает:: Состояние указанного свойства.
Исключения:: ParserConfigurationException - если этот DocumentBuilderFactory или созданные им DocumentBuilderы не поддерживают это свойство.

getSchema

public Schema getSchema()

Получает объект Schema, указанный методом setSchema(Schema schema).

Возвращает:: объект Schema, который был последним установлен через метод setSchema(Schema), или null, если метод не вызывался с момента создания DocumentBuilderFactory.
Исключения:: UnsupportedOperationException - При реализации не переопределяет этот метод.
С тех пор:: 1.5

setSchema

public void setSchema(Schema schema)

Устанавливает Schema для использования парсерами, созданными из этой фабрики.

Если Schema не null, парсер будет использовать созданный из него валидатор для проверки документов, прежде чем передавать информацию приложению.

При обнаружении ошибок валидатором парсер отвечает за сообщение об этих ошибках пользователю, указанному в ErrorHandler (или, если обработчик ошибок не установлен, игнорировать их или выбросить), так же как и любые другие ошибки, обнаруженные самим парсером. Другими словами, если указанный пользователем ErrorHandler установлен, он должен получить эти ошибки, а если нет, они должны обрабатываться в соответствии с правилами обработки ошибок по умолчанию, специфичными для реализации.

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

Изначально в качестве Schema устанавливается null.

Эта обработка будет действовать даже если метод isValidating() возвращает false.

Использование свойств http://java.sun.com/xml/jaxp/properties/schemaSource и/или http://java.sun.com/xml/jaxp/properties/schemaLanguage вместе с объектом Schema запрещено. Такая конфигурация вызовет исключение ParserConfigurationException при вызове newDocumentBuilder().

Примечание для разработчиков реализаций

Парсер должен уметь работать с любой реализацией Schema. Однако парсеры и схемы могут использовать специфичные для реализации механизмы, если они дают результат, описанный в спецификации.

Параметры:: schema - Schema для использования или null для удаления схемы.
Исключения:: UnsupportedOperationException - При реализации не переопределяет этот метод.
С тех пор:: 1.5

setXIncludeAware

public void setXIncludeAware(boolean state)

Устанавливает состояние обработки XInclude.

Если в документе встречается разметка XInclude, следует ли обрабатывать её в соответствии со спецификацией XML Inclusions (XInclude) Version 1.0.

Обработка XInclude по умолчанию — false.

Параметры:: state - Установить обработку XInclude в true или false
Исключения:: UnsupportedOperationException - При реализации не переопределяет этот метод.
С тех пор:: 1.5

isXIncludeAware

public boolean isXIncludeAware()

Получить состояние обработки XInclude.

Возвращает:: текущее состояние обработки XInclude
Исключения:: UnsupportedOperationException - При реализации не переопределяет этот метод.
С тех пор:: 1.5

© 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.