Класс JAXBContext

Класс JAXBContext предоставляет точку входа для клиента в API JAXB. Он предоставляет абстракцию для управления информацией о связывании XML/Java, необходимой для реализации операций фреймворка JAXB: разбор, формирование и валидация.

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

• JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
  Экземпляр JAXBContext инициализируется списком имён Java-пакетов, разделённых двоеточием. Каждый Java-пакет содержит связанные с JAXB классы, классы, полученные из схем, и/или классы, аннотированные пользователем. Кроме того, Java-пакет может содержать аннотации пакетов JAXB, которые должны быть обработаны. (см. JLS, Раздел 7.4.1 «Именованные пакеты»).
• JAXBContext.newInstance( com.acme.foo.Foo.class )
  Экземпляр JAXBContext инициализируется с классами, переданными в качестве параметра(ов), и классами, которые статически достижимы из этих классов. Подробнее см. newInstance(Class...).

ТРЕБОВАНИЕ СПЕЦИФИКАЦИИ: поставщик должен предоставить реализующий класс, содержащий следующие сигнатуры методов:

public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException
 public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException

Следующее требование JAXB 1.0 необходимо только для связывания схем с интерфейсами/реализациями Java. Оно не применяется к классам, аннотированным JAXB. Поставщики JAXB должны сгенерировать файл jaxb.properties в каждом пакете, содержащем классы, полученные из схем. Файл свойств должен содержать свойство с именем javax.xml.bind.context.factory, значение которого является именем класса, реализующего API createContext.

Класс, предоставленный поставщиком, не обязательно должен быть присваиваемым к javax.xml.bind.JAXBContext, он просто должен предоставлять класс, реализующий API createContext.

Кроме того, поставщик должен вызвать API DatatypeConverter.setDatatypeConverter до любых вызовов клиента методов marshal и unmarshal. Это необходимо для настройки конвертера типов данных, который будет использоваться во время этих операций.

Разбор

Класс Unmarshaller предоставляет приложению-клиенту возможность конвертировать данные XML в дерево Java-объектов контента. Метод unmarshal позволяет разбор любого глобального XML-элемента, объявленного в схеме, как корня документа-экземпляра. Кроме того, метод unmarshal позволяет разбор нераспознанного корневого элемента, значение атрибута xsi:type которого ссылается на определение типа, объявленное в схеме, как корня документа-экземпляра. Объект JAXBContext позволяет объединять глобальные элементы и определения типов через набор схем (перечисленные в contextPath). Поскольку каждая схема в наборе схем может принадлежать различным именованным пространствам имён, объединение схем в контекст разбора должно быть независимым от именованных пространств имён. Это означает, что приложение-клиент может разбор XML-документов, являющихся экземплярами любой из схем, перечисленных в contextPath. Например:

JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
        Unmarshaller u = jc.createUnmarshaller();
        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
        BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
        BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath

Приложение-клиент также может явно генерировать деревья Java-контента вместо разбора существующих XML-данных. Для всех классов значений, аннотированных JAXB, приложение может создавать контент, используя конструкторы. Для классов интерфейсов/реализаций, полученных из схемы, и для создания элементов, не связанных с классом, аннотированным JAXB, приложение должно иметь доступ и знание каждого из классов ObjectFactory, полученных из схемы, которые существуют в каждом из Java-пакетов, содержащихся в contextPath. Для каждого Java-класса, полученного из схемы, есть статический фабричный метод, который производит объекты этого типа. Например, предположим, что после компиляции схемы у вас есть пакет com.acme.foo, который содержит интерфейс, полученный из схемы, с именем PurchaseOrder. Чтобы создать объекты этого типа, приложение-клиент использовало бы фабричный метод следующим образом:

com.acme.foo.PurchaseOrder po =
           com.acme.foo.ObjectFactory.createPurchaseOrder();

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

Дополнительную информацию о сгенерированных классах ObjectFactory см. в разделе 4.2 Java Package спецификации.

ТРЕБОВАНИЕ СПЕЦИФИКАЦИИ: поставщик должен сгенерировать класс в каждом пакете, содержащий все необходимые фабричные методы объектов для этого пакета с именем ObjectFactory, а также статический метод newInstance( javaContentInterface )

Формирование

Класс Marshaller предоставляет приложению-клиенту возможность конвертировать дерево Java-контента обратно в XML-данные. Нет разницы между формированием дерева контента, созданного вручную с использованием фабричных методов, и формированием дерева контента, являющегося результатом операции unmarshal . Клиенты могут сформировать Java-дерево контента обратно в XML-данные в java.io.OutputStream или java.io.Writer. Процесс формирования альтернативно может генерировать потоки событий SAX2 в зарегистрированный ContentHandler или генерировать объект узла DOM. Приложения-клиенты имеют контроль над кодировкой вывода, а также над тем, формировать ли XML-данные как полный документ или как фрагмент.

Вот простой пример, который разбирает XML-документ, а затем формирует его обратно:

JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );

        // unmarshal from foo.xml
        Unmarshaller u = jc.createUnmarshaller();
        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );

        // marshal to System.out
        Marshaller m = jc.createMarshaller();
        m.marshal( fooObj, System.out );

Валидация

Валидация значительно изменилась с момента JAXB 1.0. Класс Validator устарел и стал необязательным. Это означает, что вам рекомендуется не использовать этот класс, и, фактически, он может даже не быть доступен в зависимости от вашего поставщика JAXB. Приложения-клиенты JAXB 1.0, которые полагаются на Validator, по-прежнему будут работать должным образом при развертывании с системой выполнения JAXB 1.0. В JAXB 2.0 в Unmarshaller были включены методы удобства, которые экспонируют фреймворк JAXP 1.3 javax.xml.validation. Обратитесь к API Unmarshaller.setSchema(javax.xml.validation.Schema) для получения дополнительной информации.

Совместимость фреймворка привязки к реализации JAXB

Следующее ограничение JAXB 1.0 относится только к привязке схем к классам интерфейсов/реализации. Поскольку для этой привязки не требуется общая система выполнения, приложение-клиент JAXB не должно пытаться смешивать объекты выполнения (JAXBContext, Marshaller, и т. д.) от разных поставщиков. Это не означает, что приложение-клиент не переносимо, это просто означает, что клиент должен использовать систему выполнения, предоставленную тем же поставщиком, который использовался для компиляции схемы.

Обнаружение реализации JAXB

Когда вызывается один из методов newInstance, реализация JAXB обнаруживается следующими шагами.

1. Для каждого пакета/класса, явно переданного в метод newInstance(java.lang.String), в порядке их указания, файл jaxb.properties ищется в его пакете, используя связанный загрузчик классов — это the owner class loader для аргумента Class, и для пакета указанный ClassLoader.

   Если такой файл найден, он загружается как файл свойств с помощью loaded, и значение ключа JAXB_CONTEXT_FACTORY предполагается быть классом фабрики поставщика. Этот класс затем загружается связанным загрузчиком классов, обсуждавшимся выше.

   Эта фаза поиска позволяет некоторым пакетам принудительно использовать определённую реализацию JAXB. (Например, возможно, компилятор схем сгенерировал некоторое расширение поставщика в коде.)

2. Если системная переменная JAXB_CONTEXT_FACTORY существует, её значение предполагается быть классом фабрики поставщика. Эта фаза поиска позволяет переопределить реализацию JAXB для каждого JVM.
3. Поиск файла /META-INF/services/javax.xml.bind.JAXBContext в связанном загрузчике классов. Этот файл следует стандартной конвенции описателей сервиса, и если такой файл существует, его содержимое предполагается быть классом фабрики поставщика. Эта фаза поиска предназначена для автоматического обнаружения. Она позволяет пользователям просто поместить реализацию JAXB в путь класса и использовать её без дальнейшей настройки.
4. Наконец, если все вышеперечисленные шаги завершаются неудачей, то дальнейший поиск не определён. Тем не менее, рекомендуется просто искать какой-либо жёстко заданный платформенный по умолчанию реализацию JAXB. Эта фаза поиска нужна для того, чтобы JavaSE могла иметь свою собственную реализацию JAXB в качестве последнего средства.

После того, как класс фабрики поставщика найден, вызывается его метод public static JAXBContext createContext(String,ClassLoader,Map) (см. newInstance(String, ClassLoader, Map) для семантики параметра) или метод public static JAXBContext createContet(Class[],Map) (см. newInstance(Class[], Map) для семантики параметра), чтобы создать JAXBContext.

Поля

JAXB_CONTEXT_FACTORY

public static final String JAXB_CONTEXT_FACTORY

Имя свойства, содержащего имя класса, способного создавать новые JAXBContext объекты.

См. также:

Значения константных полей

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

JAXBContext

protected JAXBContext()

Методы

newInstance

public static JAXBContext newInstance(String contextPath)
                               throws JAXBException

Исключения:

JAXBException - если при создании JAXBContext возникла ошибка, например:

1. не удалось найти ObjectFactory.class или jaxb.index в пакетах
2. имеется неоднозначность среди глобальных элементов, содержащихся в contextPath
3. не удалось найти значение для свойства поставщика контекстного фабричного метода
4. смешивание пакетов, полученных из схем разных поставщиков, в одном contextPath

newInstance

public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader)
                               throws JAXBException

Параметры:

contextPath - список имён java-пакетов, содержащих классы, полученные из схем, и/или классы, отображенные с java на схему (помеченные аннотациями JAXB)

classLoader - Этот загрузчик классов будет использоваться для поиска реализующих классов.

Возвращает:

новый экземпляр JAXBContext

Исключения:

JAXBException - если при создании JAXBContext возникла ошибка, например:

1. не удалось найти ObjectFactory.class или jaxb.index в пакетах
2. имеется неоднозначность среди глобальных элементов, содержащихся в contextPath
3. не удалось найти значение для свойства поставщика контекстного фабричного метода
4. смешивание пакетов, полученных из схем разных поставщиков, в одном contextPath

newInstance

public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader,
                                      Map<String,?> properties)
                               throws JAXBException

Параметры:

contextPath - список имён java-пакетов, содержащих классы, полученные из схем

classLoader - Этот загрузчик классов будет использоваться для поиска реализующих классов.

properties - свойства, специфичные для поставщика. Может быть null, что эквивалентно передаче пустого отображения.

Возвращает:

новый экземпляр JAXBContext

Исключения:

JAXBException - если при создании JAXBContext возникла ошибка, например:

1. не удалось найти ObjectFactory.class или jaxb.index в пакетах
2. имеется неоднозначность среди глобальных элементов, содержащихся в contextPath
3. не удалось найти значение для свойства поставщика контекстного фабричного метода
4. смешивание пакетов, полученных из схем разных поставщиков, в одном contextPath

С момента:

JAXB2.0

newInstance

public static JAXBContext newInstance(Class... classesToBeBound)
                               throws JAXBException

class Foo {
      @XmlTransient FooBar c;
      Bar b;
 }
 class Bar { int x; }
 class Zot extends Bar { int y; }
 class FooBar { }

Параметры:

classesToBeBound - список java-классов, которые должен распознать новый JAXBContext. Может быть пустым, в этом случае будет возвращён JAXBContext, который знает только о классах, определённых спецификацией.

Возвращает:

Новый экземпляр JAXBContext. Всегда непустой действительный объект.

Исключения:

JAXBException - если при создании JAXBContext возникла ошибка, например (но не только):

1. Реализация JAXB не была обнаружена
2. Классы используют аннотации JAXB неправильно
3. Классы имеют конфликтующие аннотации (т.е. два класса с одним и тем же именем типа)
4. Реализация JAXB не смогла найти информацию, специфичную для поставщика, за пределами спецификации (такую, как дополнительные файлы, сгенерированные на этапе разработки).

IllegalArgumentException - если параметр содержит null (т.е. newInstance(null);)

С момента:

JAXB2.0

newInstance

public static JAXBContext newInstance(Class[] classesToBeBound,
                                      Map<String,?> properties)
                               throws JAXBException

Параметры:

classesToBeBound - список java-классов, которые должен распознать новый JAXBContext. Может быть пустым, в этом случае будет возвращён JAXBContext, который знает только о классах, определённых спецификацией.

properties - свойства, специфичные для поставщика. Может быть null, что эквивалентно передаче пустого отображения.

Возвращает:

Новый экземпляр JAXBContext. Всегда непустой действительный объект.

Исключения:

JAXBException - если при создании JAXBContext возникла ошибка, например (но не только):

1. Реализация JAXB не была обнаружена
2. Классы используют аннотации JAXB неправильно
3. Классы имеют конфликтующие аннотации (т.е. два класса с одним и тем же именем типа)
4. Реализация JAXB не смогла найти информацию, специфичную для поставщика, за пределами спецификации (такую, как дополнительные файлы, сгенерированные на этапе разработки).

IllegalArgumentException - если параметр содержит null (т.е. newInstance(null,someMap);)

С момента:

JAXB2.0

createUnmarshaller

public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException

Создать объект Unmarshaller, который можно использовать для преобразования XML-данных в дерево содержания java.

Возвращает:

объект Unmarshaller

Исключения:

JAXBException - если при создании объекта Unmarshaller возникла ошибка

createMarshaller

public abstract Marshaller createMarshaller()
                                     throws JAXBException

Создать объект Marshaller, который можно использовать для преобразования дерева содержания java в XML-данные.

Возвращает:

объект Marshaller

Исключения:

JAXBException - если при создании объекта Marshaller возникла ошибка

createValidator

public abstract Validator createValidator()
                                   throws JAXBException

Устаревшее. начиная с JAXB2.0

Возвращает:

объект Validator

Бросает:

JAXBException - если при создании объекта Validator произошла ошибка

createBinder

public <T> Binder<T> createBinder(Class<T> domType)

Создаёт объект Binder, который можно использовать для ассоциативного/непосредственного разбора/формирования.

Параметры:

domType - выбирает API DOM для использования, передавая его класс DOM-узла.

Возвращает:

всегда новый допустимый объект Binder

Бросает:

UnsupportedOperationException - если DOM-API, соответствующий domType, не поддерживается реализацией.

С:

JAXB2.0

createBinder

public Binder<Node> createBinder()

Создаёт Binder для W3C DOM.

Возвращает:

всегда новый допустимый объект Binder

С:

JAXB2.0

createJAXBIntrospector

public JAXBIntrospector createJAXBIntrospector()

Создаёт объект JAXBIntrospector, который можно использовать для интроспекции JAXB-объектов.

Возвращает:

всегда возвращает непустой допустимый объект JAXBIntrospector

Бросает:

UnsupportedOperationException - Вызов этого метода в реализациях JAXB 1.0 выбросит UnsupportedOperationException.

С:

JAXB2.0

generateSchema

public void generateSchema(SchemaOutputResolver outputResolver)
                    throws IOException

Генерирует документы схемы для этого контекста.

Параметры:

outputResolver - этот объект управляет выводом, в который будут отправлены схемы.

Бросает:

IOException - если SchemaOutputResolver выбросит IOException.

UnsupportedOperationException - Вызов этого метода в реализациях JAXB 1.0 выбросит UnsupportedOperationException.

С:

JAXB 2.0