javax.xml.bind

Класс JAXBContext

java.lang. Объект

javax.xml.bind. JAXBContext

public abstract class JAXBContext
extends Object

Класс 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 является intialized с классом (ами), который передают как параметр (ы) и классы, которые статически достижимы от них класс (ы). См. 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.

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

Немаршалинг

Unmarshaller класс обеспечивает клиентское приложение возможность преобразовать данные XML в дерево объектов контента Java. Неупорядочивать метод учитывает любой глобальный элемент XML, который, как объявляют в схеме, был неупорядочен как корень документа экземпляра. Дополнительно, неупорядочивать метод учитывает нераспознанный корневой элемент, у которого есть значение 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 спецификации.

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

Маршалинг

Marshaller класс обеспечивает клиентское приложение возможность преобразовать дерево контента Java назад в данные XML. Нет никакого различия между маршалингом дерева контента, которое создается, вручную используя методы фабрики и упорядочивая дерево контента, которое является результатом работа unmarshal . Клиенты могут упорядочить дерево контента java назад к данным XML к java.io.OutputStream или java.io.Writer. Процесс маршалинга может альтернативно произвести потоки событий SAX2 для зарегистрированного ContentHandler или произвести объект ДОМА Ноуда. Клиентские приложения управляют выходным кодированием так же как упорядочить ли данные 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 включал convenince методы, которые представляют JAXP 1.3 javax.xml.validation платформа. Пожалуйста, обратитесь к Unmarshaller.setSchema(javax.xml.validation.Schema) API для получения дополнительной информации.

Время выполнения JAXB, Связывая Совместимость Платформы

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

Открытие реализации JAXB

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

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

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

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

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

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

С тех пор:

JAXB1.0

См. Также:

Marshaller, Unmarshaller, 7.4.1 "Named Packages" in Java Language Specification

Полевая Сводка

Поля

Модификатор и Тип	Поле и Описание
static String	JAXB_CONTEXT_FACTORY Имя свойства, которое содержит имя класса, способного к созданию новых объектов JAXBContext.

Сводка конструктора

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

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

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
Binder<Node>	createBinder() Создает Binder для W3C ДОМ.
<T> Binder<T>	createBinder(Class<T> domType) Создает объект Binder, который может использоваться для ассоциативного/на месте немаршалинга/маршалинга.
JAXBIntrospector	createJAXBIntrospector() Создает объект JAXBIntrospector, который может использоваться, чтобы анализировать объекты JAXB.
abstract Marshaller	createMarshaller() Создайте объект Marshaller, который может использоваться, чтобы преобразовать дерево контента java в данные XML.
abstract Unmarshaller	createUnmarshaller() Создайте объект Unmarshaller, который может использоваться, чтобы преобразовать данные XML в дерево контента java.
abstract Validator	createValidator() Осуждаемый. начиная с JAXB2.0
void	generateSchema(SchemaOutputResolver outputResolver) Генерирует документы схемы для этого контекста.
static JAXBContext	newInstance(Class... classesToBeBound) Получите новый экземпляр класса JAXBContext.
static JAXBContext	newInstance(Class[] classesToBeBound, Map<String,?> properties) Получите новый экземпляр класса JAXBContext.
static JAXBContext	newInstance(String contextPath) Получите новый экземпляр класса JAXBContext.
static JAXBContext	newInstance(String contextPath, ClassLoader classLoader) Получите новый экземпляр класса JAXBContext.
static JAXBContext	newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) Получите новый экземпляр класса JAXBContext.

Методы java.lang унаследованный от класса. Объект

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

Полевая Деталь

JAXB_CONTEXT_FACTORY

public static final String JAXB_CONTEXT_FACTORY

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

См. Также:

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

Деталь конструктора

JAXBContext

protected JAXBContext()

Деталь метода

newInstance

public static JAXBContext newInstance(String contextPath)
                               throws JAXBException

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

Это - метод удобства, чтобы вызвать newInstance(String,ClassLoader) метод с загрузчиком класса контекста текущего потока.

Броски:

JAXBException - если с ошибкой встретились, создавая JAXBContext такой как

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

newInstance

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

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

Клиентское приложение должно предоставить путь контекста, который является списком двоеточия (': ', \u003A) разделенные имена пакета java, которые содержат производные классы схемы и/или полностью определили JAXB-аннотируемые классы. Полученный из схемы код регистрируется в JAXBContext ObjectFactory.class, сгенерированным на пакет. Альтернативно чем быть перечисленным в пути контекста, программист аннотировал JAXB, отображенные классы могут быть перечислены в файле ресурсов jaxb.index, формат, описанный ниже. Отметьте, что пакет java может содержать оба производных класса схемы и пользователя аннотируемые классы JAXB. Дополнительно, пакет java может содержать аннотации пакета JAXB, которые должны быть обработаны. (см. JLS, Раздел 7.4.1" Именованных Пакета").

Каждый пакет, перечисленный на contextPath, должен встретиться один или оба из следующих условий иначе, JAXBException будет брошен:

1. это должно содержать ObjectFactory.class
2. это должно содержать jaxb.index

Формат для jaxb.index

Файл содержит разделенный от новой строки список имен классов. Пространство и символы вкладки, так же как пустые строки, игнорируются. Символ комментария '#' (0x23); на каждой строке игнорируются все символы после первого символа комментария. Файл должен быть закодирован в UTF-8. Классы, которые достижимы, как определено в newInstance(Class...), от перечисленных классов также регистрируются в JAXBContext.

Ограничения на имя класса, происходящее в файле jaxb.index:

• Не должен закончиться ".class".
• Имена классов разрешаются относительно пакета, содержащего файл jaxb.index. Только классы, происходящие непосредственно в пакете, содержащем файл jaxb.index, позволяются.
• Полностью определенные имена классов не позволяются. Квалифицированному имени класса, относительно текущего пакета, только позволяют определить вложенный или внутренний класс.

Чтобы поддержать совместимость с JAXB 1.0 схемы к привязке интерфейса/реализации java, включенной настройкой схемы <jaxb:globalBindings valueClass="false">, провайдер JAXB гарантирует, что у каждого пакета на пути контекста есть файл jaxb.properties, который содержит значение для свойства javax.xml.bind.context.factory и что все значения решают к тому же самому провайдеру. Это требование не применяется к JAXB аннотируемые классы.

Если будут какие-либо глобальные коллизии имени элемента XML через различные пакеты, перечисленные на contextPath, то JAXBException будет брошен.

Смешивание генерировало interface/impl привязку от многократных Провайдеров JAXB в том же самом пути контекста, может привести к бросаемому JAXBException.

Шаги, включенные в обнаружение реализации JAXB, обсуждаются в классе javadoc.

Параметры:

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

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

Это - главным образом то же самое как newInstance(String, ClassLoader), но эта версия позволяет Вам передавать в специфичных для провайдера свойствах, чтобы сконфигурировать инстанцирование JAXBContext.

Интерпретация свойств до реализаций. Реализации должны бросить JAXBException, если он находит свойства, которые он не понимает.

Параметры:

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

classLoader - Этот загрузчик класса будет использоваться, чтобы определить местоположение классов реализации.

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

Возвраты:

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

Броски:

JAXBException - если с ошибкой встретились, создавая JAXBContext такой как

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

С тех пор:

JAXB2.0

newInstance

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

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

Клиентское приложение должно предоставить список классов, которые должен распознать новый объект контекста. Не только новый контекст распознает все определенные классы, но он также распознает любые классы, на которые непосредственно/косвенно ссылаются статически от указанных классов. Подклассы классов, на которые ссылаются, ни @XmlTransient классы, на которые ссылаются, не регистрируются в JAXBContext. Например, в следующем коде Java, если Вы делаете newInstance(Foo.class), недавно создаваемый JAXBContext распознает и Foo и Bar, но не Zot или FooBar:

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

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

Отметьте, что для каждого пакета java, зарегистрированного в JAXBContext, когда дополнительные аннотации пакета существуют, они должны быть обработаны. (см. JLS, Раздел 7.4.1" Именованных Пакета").

Шаги, включенные в обнаружение реализации JAXB, обсуждаются в классе javadoc.

Параметры:

classesToBeBound - список классов java, которые будут распознаны новым JAXBContext. Может быть пустым, когда a 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

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

Перегрузка newInstance(Class...) сконфигурировать 'свойства' для этого инстанцирования JAXBContext.

Интерпретация свойств до реализаций. Реализации должны бросить JAXBException, если он находит свойства, которые он не понимает.

Параметры:

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

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

Возвраты:

Новый экземпляр 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 был сделан дополнительным и осуждаемым в JAXB 2.0. Пожалуйста, обратитесь к javadoc для Validator для большего количества детали.

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

Возвраты:

объект Validator

Броски:

JAXBException - если с ошибкой встретились, создавая объект Validator

createBinder

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

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

Параметры:

domType - выберите API ДОМА, чтобы использовать, передавая в его классе ДОМА Ноуда.

Возвраты:

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

Броски:

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

С тех пор:

JAXB2.0

createBinder

public Binder<Node> createBinder()

Создает Binder для W3C ДОМ.

Возвраты:

всегда новый допустимый объект 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