Класс DocumentBuilderFactory

java.lang.Object

javax.xml.parsers.DocumentBuilderFactory

public abstract class DocumentBuilderFactory extends Object

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

С:: 1.4

Краткое описание конструкторов

DocumentBuilderFactory()

Модификатор	Конструктор	Описание
`protected`	Защищённый конструктор для предотвращения инстанцирования.

Краткое описание методов

Модификатор и тип	Метод	Описание
`abstract Object`	`getAttribute(String name)`	Позволяет пользователю получить определённые атрибуты в базовой реализации.
`abstract boolean`	`getFeature(String name)`	Получить состояние указанного функционального параметра.
`Schema`	`getSchema()`	Получить объект `Schema`, указанный через метод `setSchema(Schema schema)`.
`boolean`	`isCoalescing()`	Указывает, настроена ли фабрика на создание парсеров, которые преобразуют узлы CDATA в узлы Text и добавляют их к смежному (если есть) узлу Text.
`boolean`	`isExpandEntityReferences()`	Указывает, настроена ли фабрика на создание парсеров, которые расширяют узлы ссылок на сущности.
`boolean`	`isIgnoringComments()`	Указывает, настроена ли фабрика на создание парсеров, которые игнорируют комментарии.
`boolean`	`isIgnoringElementContentWhitespace()`	Указывает, настроена ли фабрика на создание парсеров, которые игнорируют игнорируемые пробелы в содержимом элемента.
`boolean`	`isNamespaceAware()`	Указывает, настроена ли фабрика на создание парсеров, которые учитывают пространства имён.
`boolean`	`isValidating()`	Указывает, настроена ли фабрика на создание парсеров, которые проверяют XML-содержимое во время разбора.
`boolean`	`isXIncludeAware()`	Получить состояние обработки XInclude.
`static DocumentBuilderFactory`	`newDefaultInstance()`	Создаёт новый экземпляр `DocumentBuilderFactory` встроенной реализации по умолчанию системы.
`static DocumentBuilderFactory`	`newDefaultNSInstance()`	Создаёт новый NamespaceAware экземпляр `DocumentBuilderFactory` встроенной реализации по умолчанию системы.
`abstract DocumentBuilder`	`newDocumentBuilder()`	Создаёт новый экземпляр `DocumentBuilder` с использованием текущих параметров.
`static DocumentBuilderFactory`	`newInstance()`	Получает новый экземпляр `DocumentBuilderFactory`.
`static DocumentBuilderFactory`	`newInstance(String factoryClassName, ClassLoader classLoader)`	Получить новый экземпляр `DocumentBuilderFactory` по имени класса.
`static DocumentBuilderFactory`	`newNSInstance()`	Создаёт новый NamespaceAware экземпляр `DocumentBuilderFactory`.
`static DocumentBuilderFactory`	`newNSInstance(String factoryClassName, ClassLoader classLoader)`	Создаёт новый NamespaceAware экземпляр `DocumentBuilderFactory` по имени класса.
`abstract void`	`setAttribute(String name, Object value)`	Позволяет пользователю задать определённые атрибуты в базовой реализации.
`void`	`setCoalescing(boolean coalescing)`	Указывает, что парсер, созданный этим кодом, преобразует узлы CDATA в узлы Text и добавляет их к смежному (если есть) текстовому узлу.
`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().

Подробное описание методов

newDefaultNSInstance

public static DocumentBuilderFactory newDefaultNSInstance()

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

Требования к реализации:: Помимо создания экземпляра фабрики таким же образом, как и в методе newDefaultInstance(), этот метод должен установить NamespaceAware в значение true.
Возвращает:: новый экземпляр встроенной реализации по умолчанию.
С:: 13

newNSInstance

public static DocumentBuilderFactory newNSInstance()

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

Требования к реализации:: Помимо создания экземпляра фабрики таким же образом, как и в методе newInstance(), этот метод должен установить NamespaceAware в значение true.
Возвращает:: новый экземпляр определённой реализации.
Изначает:: FactoryConfigurationError - в случае ошибки конфигурации сервиса или если реализация недоступна или не может быть создана.
С:: 13

newNSInstance

public static DocumentBuilderFactory newNSInstance(String factoryClassName, ClassLoader classLoader)

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

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

newDefaultInstance

public static DocumentBuilderFactory newDefaultInstance()

Создаёт новый экземпляр встроенной реализации по умолчанию.

Возвращает:: Новый экземпляр встроенной реализации по умолчанию.
С:: 9

newInstance

public static DocumentBuilderFactory newInstance()

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

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

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

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

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

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

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

newInstance

public static DocumentBuilderFactory newInstance(String factoryClassName, ClassLoader classLoader)

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

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

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

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

Параметры:

factoryClassName - полное имя класса фабрики, предоставляющей реализацию javax.xml.parsers.DocumentBuilderFactory.

classLoader - ClassLoader для загрузки класса фабрики. Если null, используется контекстный classLoader текущего 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 и добавлять их к смежному (если есть) узлу текста. По умолчанию это значение равно false

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

isNamespaceAware

public boolean isNamespaceAware()

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

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

isValidating

public boolean isValidating()

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

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

isIgnoringElementContentWhitespace

public boolean isIgnoringElementContentWhitespace()

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

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

isExpandEntityReferences

public boolean isExpandEntityReferences()

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

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

isIgnoringComments

public boolean isIgnoringComments()

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

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

isCoalescing

public boolean isCoalescing()

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

Returns:: 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.

Parameters:: name - Название атрибута.; value - Значение атрибута.
Throws:: IllegalArgumentException - выброшен, если базовая реализация не распознаёт атрибут.

getAttribute

public abstract Object getAttribute(String name) throws IllegalArgumentException

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

Parameters:: name - Название атрибута.
Returns:: значение Значение атрибута.
Throws:: 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 Schema, которые потребляют большие объёмы ресурсов. Если обработка XML ограничена по соображениям безопасности, она будет сообщена вызовом зарегистрированному ErrorHandler.fatalError(SAXParseException exception). Смотрите DocumentBuilder.setErrorHandler(org.xml.sax.ErrorHandler errorHandler).
false: реализация будет обрабатывать XML в соответствии со спецификациями XML без учёта возможных ограничений реализации.

Parameters:: name - Имя параметра.; value - Состояние параметра true или false.
Throws:: ParserConfigurationException - если этот DocumentBuilderFactory или DocumentBuilder не поддерживают этот параметр.; NullPointerException - если параметр name равен null.
Since:: 1.5

getFeature

public abstract boolean getFeature(String name) throws ParserConfigurationException

Получает состояние именованного параметра.

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

Parameters:: name - Имя параметра.
Returns:: Состояние именованного параметра.
Throws:: ParserConfigurationException - если этот DocumentBuilderFactory или DocumentBuilder не поддерживают этот параметр.
Since:: 1.5

getSchema

public Schema getSchema()

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

Returns:: объект Schema, который был последним установлен через метод setSchema(Schema), или null, если метод не был вызван после создания DocumentBuilderFactory.
Throws:: UnsupportedOperationException - Когда реализация не переопределяет этот метод.
Since:: 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. Однако парсеры и схемы могут использовать специфичные для реализации механизмы, если они дают результат, описанный в спецификации.

Parameters:: schema - Schema для использования или null для удаления схемы.
Throws:: UnsupportedOperationException - Когда реализация не переопределяет этот метод.
Since:: 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, 2021, 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/17/docs/api/java.xml/javax/xml/parsers/DocumentBuilderFactory.html