Класс 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 в текстовые узлы и добавляющих их к соседнему (если он есть) текстовому узлу.
`boolean`	`isExpandEntityReferences()`	Указывает, настроена ли фабрика на создание анализаторов, раскрывающих узлы ссылок на сущности.
`boolean`	`isIgnoringComments()`	Указывает, настроена ли фабрика на создание анализаторов, игнорирующих комментарии.
`boolean`	`isIgnoringElementContentWhitespace()`	Указывает, настроена ли фабрика на создание анализаторов, игнорирующих пробельные символы, которые можно игнорировать, в содержимом элементов.
`boolean`	`isNamespaceAware()`	Указывает, настроена ли фабрика на создание анализаторов с поддержкой пространств имён.
`boolean`	`isValidating()`	Указывает, настроена ли фабрика на создание анализаторов, проверяющих корректность содержимого XML во время разбора.
`boolean`	`isXIncludeAware()`	Получает состояние обработки XInclude.
`static DocumentBuilderFactory`	`newDefaultInstance()`	Создаёт новый экземпляр встроенной системной реализации по умолчанию `DocumentBuilderFactory`.
`static DocumentBuilderFactory`	`newDefaultNSInstance()`	Создаёт новый экземпляр с поддержкой пространств имён встроенной системной реализации по умолчанию `DocumentBuilderFactory`.
`abstract DocumentBuilder`	`newDocumentBuilder()`	Создаёт новый экземпляр `DocumentBuilder` с использованием текущих настроек.
`static DocumentBuilderFactory`	`newInstance()`	Получает новый экземпляр `DocumentBuilderFactory`.
`static DocumentBuilderFactory`	`newInstance(String factoryClassName, ClassLoader classLoader)`	Получает новый экземпляр `DocumentBuilderFactory` по имени класса.
`static DocumentBuilderFactory`	`newNSInstance()`	Создаёт новый экземпляр `DocumentBuilderFactory` с поддержкой пространств имён.
`static DocumentBuilderFactory`	`newNSInstance(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-документов (см. раздел 2.10 рекомендации XML).
`void`	`setNamespaceAware(boolean awareness)`	Указывает, что анализатор, созданный этим кодом, будет поддерживать пространства имён XML.
`void`	`setSchema(Schema schema)`	Задаёт `Schema`, который будет использоваться анализаторами, создаваемыми этой фабрикой.
`void`	`setValidating(boolean validating)`	Указывает, что анализатор, созданный этим кодом, будет проверять документы во время их разбора.
`void`	`setXIncludeAware(boolean state)`	Задаёт состояние обработки XInclude.

Методы, объявленные в классе Object

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

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

DocumentBuilderFactory

protected DocumentBuilderFactory()

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

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

newDefaultNSInstance

public static DocumentBuilderFactory newDefaultNSInstance()

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

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

newNSInstance

public static DocumentBuilderFactory newNSInstance()

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

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

newNSInstance

public static DocumentBuilderFactory newNSInstance(String factoryClassName, ClassLoader classLoader)

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

Требования к реализации:: Помимо создания экземпляра фабрики тем же способом, что и newInstance(java.lang.String, java.lang.ClassLoader), этот метод должен установить для NamespaceAware значение true.
Параметры:: factoryClassName — полное имя класса фабрики, реализующего javax.xml.parsers.DocumentBuilderFactory.; classLoader — ClassLoader, используемый для загрузки класса фабрики. Если он равен null, для загрузки класса фабрики используется контекстный classLoader текущего 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 по имени класса. Этот метод полезен, если в пути к классам находятся несколько поставщиков. Он предоставляет приложению больше контроля, позволяя указать, какой поставщик следует загрузить.

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

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

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

Параметры:

factoryClassName — полное имя класса фабрики, реализующего javax.xml.parsers.DocumentBuilderFactory.

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

Параметры:: coalescing — true, если созданный парсер будет преобразовывать узлы CDATA в текстовые узлы и добавлять их к соседнему (если он есть) текстовому узлу; в противном случае 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 и внешним ссылкам на сущности протоколами, указанными в этом свойстве. Если во время разбора доступ запрещён из-за ограничения, заданного этим свойством, методы разбора, определённые в DocumentBuilder, выбрасывают SAXException.
Задание свойства XMLConstants.ACCESS_EXTERNAL_SCHEMA ограничивает доступ к внешней схеме, заданной атрибутом schemaLocation, протоколами, указанными в этом свойстве. Если во время разбора доступ запрещён из-за ограничения, заданного этим свойством, методы разбора, определённые в DocumentBuilder, выбрасывают SAXException.

Параметры:: 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. Реализации могут определять собственные функции. Если этот DocumentBuilderFactory или создаваемые им DocumentBuilder не поддерживают функцию, выбрасывается ParserConfigurationException. 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 или создаваемые им DocumentBuilder не поддерживают эту функцию.; NullPointerException — если параметр name равен null.
С версии:: 1.5

getFeature

public abstract boolean getFeature(String name) throws ParserConfigurationException

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

Параметры:: name — имя функции.
Возвращает:: состояние указанной функции.
Выбрасывает:: ParserConfigurationException — если этот DocumentBuilderFactory или создаваемые им DocumentBuilder не поддерживают эту функцию.
С версии:: 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 нельзя. При такой конфигурации вызов метода newDocumentBuilder() приведёт к выбрасыванию исключения ParserConfigurationException.

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

Парсер должен работать с любой реализацией 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, 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://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/parsers/DocumentBuilderFactory.html