Класс SchemaFactory

protected SchemaFactory()

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

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

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

public static SchemaFactory newDefaultInstance()

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

public static SchemaFactory newInstance(String schemaLanguage)

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

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

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

http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory

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

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

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

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

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

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

public abstract boolean isSchemaLanguageSupported(String schemaLanguage)

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

public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException

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

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

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

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

Задает функцию для этой SchemaFactory, создаваемых этой фабрикой объектов Schema и, как следствие, создаваемых этими Schema объектами Validator и ValidatorHandler.

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

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

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

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

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

• Доступ к внешним DTD в файлах схем ограничивается протоколами, указанными свойством XMLConstants.ACCESS_EXTERNAL_DTD. Если из-за ограничений этого свойства доступ запрещен при создании новой схемы, метод newSchema(Source), newSchema(File), newSchema(URL) или newSchema(Source[]) вызовет исключение SAXException.

  Доступ к внешним DTD в исходных XML-файлах ограничивается протоколами, указанными свойством XMLConstants.ACCESS_EXTERNAL_DTD. Если из-за ограничений этого свойства доступ запрещен во время проверки, метод Validator.validate(Source) или Validator.validate(Source, Result) вызовет исключение SAXException.

  Доступ к внешней ссылке, заданной атрибутом schemaLocation, ограничивается протоколами, указанными свойством XMLConstants.ACCESS_EXTERNAL_SCHEMA. Если из-за ограничений этого свойства доступ запрещен во время проверки, метод Validator.validate(Source) или Validator.validate(Source, Result) вызовет исключение SAXException.

  Доступ к внешней ссылке, заданной элементами Import и Include, ограничивается протоколами, указанными свойством XMLConstants.ACCESS_EXTERNAL_SCHEMA. Если из-за ограничений этого свойства доступ запрещен при создании новой схемы, метод newSchema(Source), newSchema(File), newSchema(URL) или newSchema(Source[]) вызовет исключение SAXException.

public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException

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

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

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

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

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. Это поле НЕ будет унаследовано объектами Schema, Validator или ValidatorHandler, созданными этой SchemaFactory.

public abstract ErrorHandler getErrorHandler()

Получает текущий ErrorHandler, заданный для этой SchemaFactory.

public abstract void setResourceResolver(LSResourceResolver resourceResolver)

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

SchemaFactory использует LSResourceResolver, когда необходимо найти внешние ресурсы при анализе схем, хотя точное определение понятия «поиск внешних ресурсов» зависит от языка схем. Например, для W3C XML Schema сюда входят файлы, которые <include> или <import>, а также 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. Это поле НЕ будет унаследовано объектами Schema, Validator или ValidatorHandler, созданными этой SchemaFactory.

public abstract LSResourceResolver getResourceResolver()

Получает текущий LSResourceResolver, заданный для этой SchemaFactory.

public Schema newSchema(Source schema) throws SAXException

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

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

public Schema newSchema(File schema) throws SAXException

Анализирует указанный File как схему и возвращает его в виде Schema.

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

public Schema newSchema(URL schema) throws SAXException

Анализирует указанный URL как схему и возвращает его в виде Schema.

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

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

Анализирует указанные источники как схему и возвращает результат в виде схемы.

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

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

W3C XML Schema 1.0

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

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

RELAX NG

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

public abstract Schema newSchema() throws SAXException

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

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

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

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

Схема XML W3C 1.0

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

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

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

RELAX NG

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