Класс 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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, является ли другой объект «равным» этому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API подлежит удалению в будущей версии. Финализация объявлена устаревшей и подлежит удалению в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения определённого периода реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения определённого периода реального времени.

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

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 по имени класса. Этот метод полезен, если в classpath присутствует несколько поставщиков. Он предоставляет приложению больше контроля, позволяя указать, какой поставщик следует загрузить.

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

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

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