Класс 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()`	Создаёт новый экземпляр встроенной реализации по умолчанию.
`static DocumentBuilderFactory`	`newDefaultNSInstance()`	Создаёт новый экземпляр NamespaceAware встроенной реализации по умолчанию.
`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.
Возвращает:: новый экземпляр встроенной реализации по умолчанию DocumentBuilderFactory.
С:: 13

newNSInstance

public static DocumentBuilderFactory newNSInstance()

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

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

newNSInstance

public static DocumentBuilderFactory newNSInstance(String factoryClassName, ClassLoader classLoader)

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

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

newDefaultInstance

public static DocumentBuilderFactory newDefaultInstance()

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

Возвращает:: новый экземпляр встроенной реализации по умолчанию DocumentBuilderFactory.
С:: 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 по имени класса. Эта функция полезна, когда в пути класса есть несколько поставщиков. Она даёт больше контроля приложению, позволяя указать, какой поставщик должен быть загружен.

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

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

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

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

Параметры:

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

classLoader - ClassLoader, используемый для загрузки класса фабрики. Если null, используется текущий Thread контекстный загрузчик классов.

Возвращает:

Новый экземпляр DocumentBuilderFactory

Изначает:

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 - 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 во время разбора.

Возвращает:: 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 в текстовые узлы и добавляют их к смежному (если есть) текстовому узлу.

Возвращает:: true, если фабрика настроена на создание парсеров, которые преобразуют узлы CDATA в текстовые узлы и добавляют их к смежному (если есть) текстовому узлу; 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

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

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

Все реализации обязаны поддерживать свойство 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 - если эта фабрика или созданные ею парсеры не поддерживают это свойство.; NullPointerException - Если параметр name равен null.
Since:: 1.5

getFeature

public abstract boolean getFeature(String name) throws ParserConfigurationException

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

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

getSchema

public Schema getSchema()

Возвращает объект Schema, указанный методом setSchema(Schema schema).

Возвращает:: объект Schema, последний установленный методом setSchema(Schema), или null, если метод не вызывался с момента создания фабрики DocumentBuilderFactory.
Исключения:: 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 является ошибкой. Такая конфигурация при вызове newDocumentBuilder() вызовет исключение ParserConfigurationException.

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

Парсер должен уметь работать с любой реализацией 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.

Parameters:: state - Установить обработку XInclude на true или false
Throws:: UnsupportedOperationException - Когда реализация не переопределяет этот метод.
Since:: 1.5

isXIncludeAware

public boolean isXIncludeAware()

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

Returns:: текущее состояние обработки XInclude
Throws:: UnsupportedOperationException - Когда реализация не переопределяет этот метод.
Since:: 1.5

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.xml/javax/xml/parsers/DocumentBuilderFactory.html