Класс SchemaFactory

public abstract class SchemaFactory
extends Object

Фабрика, создающая объекты Schema. Точка входа в API валидации.

SchemaFactory — это компилятор схем. Он считывает внешние представления схем и готовит их для валидации.

Класс SchemaFactory не является потокобезопасным. Другими словами, приложение отвечает за обеспечение того, чтобы в любой момент времени не более одного потока использовал объект SchemaFactory.

Реализации рекомендуются помечать методы как synchronized для защиты от некорректно работающих клиентов.

SchemaFactory не рекурсивен. Пока один из newSchema методов вызывается, приложения не могут пытаться рекурсивно вызвать метод newSchema, даже из того же потока.

Язык схем

Этот стандарт использует URI пространства имён для обозначения языка схемы. В следующей таблице показаны определённые в этом стандарте значения.

Для соответствия стандарту, реализация обязана поддерживать W3C XML Schema 1.0. Однако, если она выберет поддержку других языков схем, перечисленных здесь, она должна соответствовать соответствующим описаниям поведения в этом стандарте.

Языки схем, не перечисленные здесь, должны использовать свои собственные URI для представления себя. Класс SchemaFactory способен находить другие реализации для других языков схем во время выполнения.

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

значение язык
XMLConstants.W3C_XML_SCHEMA_NS_URI ("http://www.w3.org/2001/XMLSchema") W3C XML Schema 1.0
XMLConstants.RELAXNG_NS_URI ("http://relaxng.org/ns/structure/1.0") RELAX NG 1.0
С момента:
1.5

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

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

Конструктор для производных классов.

Методы

Модификатор и тип Метод Описание
abstract ErrorHandler getErrorHandler()

Получает текущий ErrorHandler, установленный для этого SchemaFactory.
boolean getFeature​(String name)

Получает значение флага функции.
Object getProperty​(String name)

Получает значение свойства.
abstract LSResourceResolver getResourceResolver()

Получает текущий LSResourceResolver, установленный для этого SchemaFactory.
abstract boolean isSchemaLanguageSupported​(String schemaLanguage)

Поддерживается ли указанная схема этим SchemaFactory?
static SchemaFactory newDefaultInstance()

Создаёт новый экземпляр встроенной реализации системы по умолчанию SchemaFactory.
static SchemaFactory newInstance​(String schemaLanguage)

Ищет реализацию SchemaFactory, поддерживающую указанный язык схемы, и возвращает её.
static SchemaFactory newInstance​(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

Получение нового экземпляра SchemaFactory из имени класса.
abstract Schema newSchema()

Создаёт специальный объект Schema.
Schema newSchema​(File schema)

Парсит указанный File как схему и возвращает его как Schema.
Schema newSchema​(URL schema)

Парсит указанный URL как схему и возвращает его как Schema.
Schema newSchema​(Source schema)

Парсит указанный источник как схему и возвращает его как схему.
abstract Schema newSchema​(Source[] schemas)

Парсит указанный источник(и) как схему и возвращает его как схему.
abstract void setErrorHandler​(ErrorHandler errorHandler)

Устанавливает ErrorHandler для получения ошибок, возникших во время вызова метода newSchema.
void setFeature​(String name, boolean value)

Устанавливает функцию для этого SchemaFactory, Schema объектов, созданных этой фабрикой, и, как следствие, Validator и ValidatorHandler объектов, созданных этими Schema.
void setProperty​(String name, Object object)

Устанавливает значение свойства.
abstract void setResourceResolver​(LSResourceResolver resourceResolver)

Устанавливает LSResourceResolver для настройки разрешения ресурсов при парсинге схем.

Методы, унаследованные от класса java.lang.Object

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

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

SchemaFactory

protected SchemaFactory()

Конструктор для производных классов.

Конструктор ничего не делает.

Производные классы должны создавать объекты SchemaFactory, у которых есть null ErrorHandler и null LSResourceResolver.

Методы

newDefaultInstance

public static SchemaFactory newDefaultInstance()

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

Требования к реализации:
Встроенная реализация по умолчанию SchemaFactory должна поддерживать только W3C XML Schema 1.0, но может поддерживать дополнительные языки схем.
Возвращает:
Новый экземпляр SchemaFactory встроенной реализации по умолчанию.
С:
9

newInstance

public static SchemaFactory newInstance(String schemaLanguage)

Ищет реализацию SchemaFactory, которая поддерживает указанный язык схемы, и возвращает её.

Для поиска объекта SchemaFactory для заданного языка схемы этот метод ищет в следующих местах в указанном порядке, где «загрузчик классов» относится к загрузчику контекста классов:

  1. Если присутствует системное свойство "javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>" (где schemaLanguage — параметр этого метода), то его значение читается как имя класса. Метод попытается создать новый экземпляр этого класса, используя загрузчик классов, и вернёт его, если создание успешно.

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

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

  3. Используется механизм загрузки поставщиков сервисов, определённый классом ServiceLoader, для попытки найти и загрузить реализацию сервиса, используя стандартный механизм загрузки: механизм загрузки поставщиков сервисов будет использовать загрузчик классов текущей нити для попытки загрузки сервиса. Если загрузчик контекста классов равен null, будет использован системный загрузчик классов.
    Каждый потенциальный поставщик сервиса должен реализовать метод isSchemaLanguageSupported(String schemaLanguage).
    Первый обнаруженный поставщик сервиса, который поддерживает указанный язык схемы, возвращается.
    В случае ServiceConfigurationError будет брошено исключение SchemaFactoryConfigurationError.

  4. Реализация платформенного значения SchemaFactory находится в реализации в специфическом месте. Должна существовать платформенная реализация по умолчанию SchemaFactory для W3C XML Schema.

Если всё не удаётся, будет брошено исключение IllegalArgumentException.

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

См. Properties.load(java.io.InputStream), чтобы узнать, как именно анализируется файл свойств. В частности, двоеточия ':' необходимо экранировать в файле свойств, поэтому убедитесь, что URI языка схемы правильно экранированы в нём. Например: 

http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
Параметры:
schemaLanguage - Указывает язык схемы, который будет понимать возвращённый SchemaFactory. См. список доступных языков схем для возможных значений.
Возвращает:
Новый экземпляр SchemaFactory
Исключения:
IllegalArgumentException - Если реализация языка схемы недоступна.
NullPointerException - Если параметр schemaLanguage равен null.
SchemaFactoryConfigurationError - Если произошла ошибка конфигурации.
См. также:
newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

newInstance

public static SchemaFactory newInstance(String schemaLanguage,
                                        String factoryClassName,
                                        ClassLoader classLoader)

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

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

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

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

java -Djaxp.debug=1 YourProgram ....
Параметры:
schemaLanguage - Указывает язык схемы, который будет понимать возвращённый SchemaFactory. См. список доступных языков схем для возможных значений.
factoryClassName - Полное имя класса фабрики, который предоставляет реализацию javax.xml.validation.SchemaFactory.
classLoader - ClassLoader для загрузки класса фабрики. Если null используется текущий загрузчик классов контекста Thread.
Возвращает:
Новый экземпляр SchemaFactory
Исключения:
IllegalArgumentException - если factoryClassName является null, или класс фабрики не может быть загружен, создан или не поддерживает язык схемы, указанный в параметре schemLanguage.
NullPointerException - Если параметр schemaLanguage равен null.
С:
1.6
См. также:
newInstance(String schemaLanguage)

isSchemaLanguageSupported

public abstract boolean isSchemaLanguageSupported(String schemaLanguage)

Поддерживается ли указанный язык схемы этой SchemaFactory?

Параметры:
schemaLanguage - Указывает язык схемы, который будет понимать возвращённый SchemaFactory. schemaLanguage должен указывать действительный язык схемы.
Возвращает:
true если SchemaFactory поддерживает schemaLanguage, иначе false.
Исключения:
NullPointerException - Если schemaLanguage является null.
IllegalArgumentException - Если schemaLanguage.length() == 0 или schemaLanguage не указывают действительный язык схемы.

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

Получить значение флага функции.

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

Реализаторам разрешено (и рекомендуется) придумывать свои собственные функции, используя имена, построенные на их собственных URI.

Параметры:
name - Имя функции, которое является непустым полностью квалифицированным URI.
Возвращает:
Текущее значение функции (true или false).
Исключения:
SAXNotRecognizedException - Если значение функции не может быть присвоено или получено.
SAXNotSupportedException - Когда SchemaFactory распознаёт имя функции, но не может определить её значение в данный момент.
NullPointerException - Если name является null.
См. также:
setFeature(String, boolean)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

Установить функцию для данной SchemaFactory, Schemas, созданных этой фабрикой, и, соответственно, Validators и ValidatorHandlers, созданных этими Schemas.

Реализаторам и разработчикам следует уделить особое внимание тому, как обрабатывается специальный объект Schema, возвращаемый newSchema(). В некоторых случаях, например, когда SchemaFactory и класс, фактически загружающий схему, происходят из разных реализаций, может быть невозможно автоматически наследовать функции SchemaFactory. Разработчики должны убедиться, что такие функции, как безопасная обработка, явно устанавливаются в обоих местах.

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

Все реализации обязаны поддерживать функцию XMLConstants.FEATURE_SECURE_PROCESSING. Когда функция:

  • true: реализация ограничит обработку XML, чтобы соответствовать ограничениям реализации. Примеры включают ограничения расширения сущностей и конструкции XML Schema, которые потребляют большие объёмы ресурсов. Если обработка XML ограничена по соображениям безопасности, это будет сообщено посредством вызова зарегистрированного обработчика ошибок ErrorHandler.fatalError(SAXParseException exception). См. setErrorHandler(ErrorHandler errorHandler).
  • false: реализация будет обрабатывать XML в соответствии со спецификациями XML, не учитывая возможные ограничения реализации.
Параметры:
name - Имя функции, которое является непустым полностью квалифицированным URI.
value - Запрашиваемое значение функции (true или false).
Исключения:
SAXNotRecognizedException - Если значение функции не может быть присвоено или получено.
SAXNotSupportedException - Когда SchemaFactory распознаёт имя функции, но не может установить запрашиваемое значение.
NullPointerException - Если name является null.
См. также:
getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException

Установите значение свойства.

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

Все реализации, реализующие JAXP 1.5 или более позднюю версию, обязаны поддерживать свойства XMLConstants.ACCESS_EXTERNAL_DTD и XMLConstants.ACCESS_EXTERNAL_SCHEMA.

Parameters:
name - Имя свойства, которое является непустым полностью квалифицированным URI.
object - Запрашиваемое значение свойства.
Throws:
SAXNotRecognizedException - Если значение свойства нельзя назначить или получить.
SAXNotSupportedException - Когда SchemaFactory распознает имя свойства, но не может установить запрошенное значение.
NullPointerException - Если name равно null.

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

Получить значение свойства.

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

SchemaFactory не обязаны распознавать какие-либо конкретные имена свойств.

Реализаторы могут (и должны) придумывать свои собственные свойства, используя имена, основанные на собственных URI.

Parameters:
name - Имя свойства, которое является непустым полностью квалифицированным URI.
Returns:
Текущее значение свойства.
Throws:
SAXNotRecognizedException - Если значение свойства нельзя назначить или получить.
SAXNotSupportedException - Когда XMLReader распознает имя свойства, но не может определить его значение в данный момент.
NullPointerException - Если name равно null.
See Also:
setProperty(String, Object)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)

Устанавливает ErrorHandler для получения ошибок, возникших во время вызова метода newSchema.

Обработчик ошибок может использоваться для настройки процесса обработки ошибок во время разбора схемы. Когда установлен ErrorHandler, ошибки, обнаруженные во время разбора схем, будут сначала отправлены в ErrorHandler.

Обработчик ошибок может немедленно прервать разбор схемы, выбросив SAXException из обработчика. Или, например, он может вывести ошибку на экран и попытаться продолжить обработку, возвратившись нормально из ErrorHandler

Если из ErrorHandler будет выброшено какое-либо исключение Throwable (или экземпляры его производных классов), вызывающий метод newSchema получит тот же объект исключения Throwable.

SchemaFactory не разрешено выбрасывать SAXException без предварительного уведомления об этом ErrorHandler.

Приложения могут вызывать этот метод даже во время разбора Schema.

Когда ErrorHandler равен null, реализация будет вести себя так, как если бы был установлен следующий обработчик ошибок ErrorHandler: 

class DraconianErrorHandler implements ErrorHandler {
     public void fatalError( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void error( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void warning( SAXParseException e ) throws SAXException {
         // noop
     }
 }

При создании нового объекта SchemaFactory, по умолчанию это поле равно null. Это поле НЕ будет унаследовано Schemas, Validators или ValidatorHandlers, созданных из этого SchemaFactory.

Parameters:
errorHandler - Новый обработчик ошибок для установки. Этот параметр может быть null.

getErrorHandler

public abstract ErrorHandler getErrorHandler()

Возвращает текущий ErrorHandler, установленный для данного SchemaFactory.

Returns:
Этот метод возвращает объект, который был последний установлен через метод setErrorHandler(ErrorHandler), или null, если этот метод не вызывался с момента создания этого SchemaFactory.
See Also:
setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)

Устанавливает LSResourceResolver для настройки разрешения ресурсов при разборе схем.

SchemaFactory использует LSResourceResolver при необходимости поиска внешних ресурсов во время разбора схем, хотя то, что считается "поиском внешних ресурсов", зависит от каждого языка схем. Например, для W3C XML Schema это включает файлы <include>d или <import>ed, и DTD, на которые есть ссылка в файлах схемы и т. д.

Приложения могут вызывать этот метод даже во время разбора Schema.

Когда LSResourceResolver равен null, реализация будет вести себя так, как если бы был установлен следующий обработчик ресурсов LSResourceResolver: 

class DumbDOMResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {

         return null; // always return null
     }
 }

Если LSResourceResolver выбросит исключение RuntimeException (или экземпляры его производных классов), то SchemaFactory прервет разбор, и вызывающий метод newSchema получит то же исключение RuntimeException.

При создании нового объекта SchemaFactory, по умолчанию это поле равно null. Это поле НЕ будет унаследовано Schemas, Validators или ValidatorHandlers, созданных из этого SchemaFactory.

Parameters:
resourceResolver - Новый обработчик ресурсов для установки. Этот параметр может быть null.

getResourceResolver

public abstract LSResourceResolver getResourceResolver()

Возвращает текущий LSResourceResolver, установленный для данного SchemaFactory.

Returns:
Этот метод возвращает объект, который был последний установлен через метод setResourceResolver(LSResourceResolver), или null, если этот метод не вызывался с момента создания этого SchemaFactory.
See Also:
setErrorHandler(ErrorHandler)

newSchema

public Schema newSchema(Source schema)
                 throws SAXException

Парсит указанный источник как схему и возвращает его как схему.

Это вспомогательный метод для newSchema(Source[] schemas).

Parameters:
schema - Источник, представляющий схему.
Returns:
Новая Schema, полученная из разбора schema.
Throws:
SAXException - Если во время разбора произошла ошибка SAX.
NullPointerException - если schema равно null.

newSchema

public Schema newSchema(File schema)
                 throws SAXException

Парсит указанный File в качестве схемы и возвращает её как Schema.

Это удобный метод для newSchema(Source schema).

Параметры:
schema - Файл, представляющий схему.
Возвращает:
Новый Schema, полученный из парсинга schema.
Исключения:
SAXException - Если во время парсинга произошла ошибка SAX.
NullPointerException - если schema равно null.

newSchema

public Schema newSchema(URL schema)
                 throws SAXException

Парсит указанный URL в качестве схемы и возвращает её как Schema.

Это удобный метод для newSchema(Source schema).

Параметры:
schema - URL объект, представляющий схему.
Возвращает:
Новый Schema, полученный из парсинга schema.
Исключения:
SAXException - Если во время парсинга произошла ошибка SAX.
NullPointerException - если schema равно null.

newSchema

public abstract Schema newSchema(Source[] schemas)
                          throws SAXException

Парсит указанные источники как схему и возвращает её как схему.

Вызывающий метод прочитает все Source и объединит их в одну схему. Точное значение объединения зависит от языка схемы, для которого создан объект SchemaFactory.

Если установлен обработчик ошибок ErrorHandler, вызывающий метод будет сообщать обо всех ошибках, найденных в источниках, этому обработчику. Если обработчик сгенерирует исключение, процесс компиляции схемы будет прерван, и это же исключение будет сгенерировано этим методом. Также после сообщения об ошибке обработчику, вызывающий метод может прервать дальнейшую обработку, сгенерировав исключение. Если обработчик ошибок не установлен, вызывающий метод сгенерирует первое обнаруженное исключение в источниках.

Схема W3C XML 1.0

Результирующая схема содержит компоненты из указанных источников. Тот же результат был бы достигнут, если бы все эти источники были импортированы, используя соответствующие значения для schemaLocation и namespace, в один документ схемы с другим targetNamespace и без собственных компонентов, если элементы импорта были заданы в том же порядке, что и источники. Раздел 4.2.3 рекомендации XML Schema описывает варианты, имеющиеся у процессоров в этом отношении. Хотя процессор должен быть последователен в своём обращении с источниками схем JAXP и импортами XML Schema, поведение между совместимыми с JAXP парсерами может различаться; в частности, парсеры могут выбрать игнорирование всех, кроме первого <import> для заданного namespace, независимо от информации, предоставленной в schemaLocation.

Если проанализированный набор схем включает ошибку(и), как указано в разделе 5.1 спецификации XML Schema, то ошибка должна быть сообщена обработчику ErrorHandler.

RELAX NG

Для RELAX NG этот метод должен сгенерировать исключение UnsupportedOperationException, если schemas.length!=1.

Параметры:
schemas - входные данные для парсинга. SchemaFactory должен распознавать SAXSource, StreamSource, StAXSource и DOMSource. Входные схемы должны быть XML-документами или XML-элементами и не должны быть null. Для обеспечения обратной совместимости результаты передачи чего-либо, кроме документа или элемента, зависят от реализации. Реализации должны либо распознавать и обрабатывать входные данные, либо генерировать IllegalArgumentException.
Возвращает:
Всегда возвращает не-null допустимый объект Schema. Обратите внимание, что когда была сообщена ошибка, нет гарантии, что возвращаемый объект Schema является осмысленным.
Исключения:
SAXException - Если во время обработки указанных входных данных найдена ошибка. Когда установлен обработчик ошибок ErrorHandler, ошибки сообщаются в первую очередь. Смотрите setErrorHandler(ErrorHandler).
NullPointerException - Если сам параметр schemas равен null или какой-либо элемент в массиве равен null.
IllegalArgumentException - Если какой-либо элемент в массиве не распознаётся этим методом.
UnsupportedOperationException - Если язык схемы не поддерживает эту операцию.

newSchema

public abstract Schema newSchema()
                          throws SAXException

Создаёт специальный объект Schema.

Точное значение возвращаемого объекта Schema зависит от языка схемы, для которого создан объект SchemaFactory.

Также реализации могут использовать специфичные для реализации свойства/функции для изменения семантики этого метода.

Реализаторам и разработчикам следует обратить особое внимание на то, как заданные функции этого объекта SchemaFactory обрабатываются этим специальным объектом Schema. В некоторых случаях, например, когда объект SchemaFactory и класс, фактически загружающий схему, происходят из разных реализаций, функции объекта SchemaFactory могут не быть унаследованы автоматически. Разработчики должны убедиться, что такие функции, как безопасная обработка, явно установлены в обоих местах.

Схема W3C XML 1.0

Для XML Schema этот метод создаёт объект Schema, который выполняет валидацию с использованием указателей расположения, указанных в документах.

Возвращаемый объект Schema предполагает, что если документы ссылаются на один и тот же URL в указателях расположения схемы, они всегда будут разрешаться в один и тот же документ схемы. Это предположение позволяет реализациям повторно использовать обработанные результаты документов схемы, чтобы многократная валидация по одной и той же схеме работала быстрее.

Обратите внимание, что использование указателей расположения схемы создаёт уязвимость к атакам с отказом в обслуживании.

RELAX NG

RELAX NG не поддерживает эту операцию.

Возвращает:
Всегда возвращает не-null допустимый объект Schema.
Исключения:
UnsupportedOperationException - Если эта операция не поддерживается вызываемым объектом.
SAXException - Если эта операция поддерживается, но не выполнена по какой-либо причине.

© 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/validation/SchemaFactory.html

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