Класс DocumentBuilderFactory

java.lang.Object

javax.xml.parsers.DocumentBuilderFactory

public abstract class DocumentBuilderFactory extends Object

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

Since:: 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 и добавляет их к смежным (если есть) узлам 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, используется контекстный класс-загрузчик текущего Thread для загрузки класса фабрики.
Возвращает:: новый экземпляр конкретной реализации.
Исключения:: FactoryConfigurationError - если factoryClassName является null, или класс фабрики не может быть загружен или создан.
С:: 13

newDefaultInstance

public static DocumentBuilderFactory newDefaultInstance()

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

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

newInstance

public static DocumentBuilderFactory newInstance()

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

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

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

Установка свойства системы jaxp.debug приведет к выводу большого количества отладочных сообщений в System.err о том, что делает метод и где он ищет.

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

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

Возвращает:: Новый экземпляр конкретной реализации.
Исключения:: 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.

Возвращает:

Новый экземпляр конкретной реализации.

Исключения:

FactoryConfigurationError - если factoryClassName является null, или класс фабрики не может быть загружен или создан.

С:

1.6

См. также:

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 - значение, определяющее игнорирование комментариев во время обработки.

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 и DocumentBuilders, созданных этой фабрикой.

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

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

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

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

getFeature

public abstract boolean getFeature(String name) throws ParserConfigurationException

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

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

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 включения (XInclude) Версия 1.0.

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

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

isXIncludeAware

public boolean isXIncludeAware()

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

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

© 1993, 2023, 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/21/docs/api/java.xml/javax/xml/parsers/DocumentBuilderFactory.html