Класс DocumentBuilderFactory

public abstract class DocumentBuilderFactory
extends Object

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

Since:
1.4

Конструкторы

Модификатор Конструктор Описание
protected DocumentBuilderFactory()

Защищённый конструктор для предотвращения инстанцирования.

Методы

Модификатор и тип Метод Описание
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.

abstract DocumentBuilder newDocumentBuilder()

Создаёт новый экземпляр DocumentBuilder с использованием текущих параметров конфигурации.
static DocumentBuilderFactory newInstance()

Получить новый экземпляр DocumentBuilderFactory.

static DocumentBuilderFactory newInstance​(String factoryClassName, ClassLoader classLoader)

Получить новый экземпляр 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 и DocumentBuilders, созданных этой фабрикой.
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().

Методы

newDefaultInstance

public static DocumentBuilderFactory newDefaultInstance()

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

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

newInstance

public static DocumentBuilderFactory newInstance()

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

  • Используйте системное свойство javax.xml.parsers.DocumentBuilderFactory.

  • Используйте конфигурационный файл "jaxp.properties". Файл находится в стандартном формате Properties и, как правило, расположен в каталоге conf установки Java. Он содержит полное имя класса реализации, причём ключ — это системное свойство, определённое выше.

    Файл jaxp.properties считывается реализацией JAXP только один раз, а затем его значения кешируются для дальнейшего использования. Если файл не существует при первой попытке его чтения, дальнейшие попытки проверки его существования не производятся. Изменить значение любого свойства в файле jaxp.properties после его первого прочтения невозможно.

  • Используйте механизм загрузки поставщиков услуг, определённый классом ServiceLoader, для попытки найти и загрузить реализацию службы с помощью механизма загрузки по умолчанию: механизм загрузки поставщиков услуг будет использовать класс загрузки текущей нити для попытки загрузки службы. Если класс загрузки контекста равен null, будет использован системный класс загрузки.

  • В противном случае возвращается реализация по умолчанию системы.

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

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

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

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

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

newInstance

public static DocumentBuilderFactory newInstance(String factoryClassName,
                                                 ClassLoader classLoader)

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

После того, как приложение получило ссылку на 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
См. также:
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 и добавлять их к смежному (если есть) узлу 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, созданных этим фабричным методом.

Имена свойств — полностью квалифицированные URI значения. Реализации могут определять свои собственные свойства. 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

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

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

Параметры:
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 Inclusions (XInclude) Version 1.0.

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

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

isXIncludeAware

public boolean isXIncludeAware()

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

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

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

Spec-Zone .ru
спецификации, руководства, описания, API