javax.xml.bind
Класс JAXBContext

java.lang.Object
  расширенный javax.xml.bind.JAXBContext

public abstract class JAXBContext
расширяет java.lang. Объект

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

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

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

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

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

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

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

Немаршалинг

Unmarshaller class обеспечивает клиентское приложение возможность преобразовать данные 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-аннотируемым class, у приложения должны быть доступ и знание о каждой схеме полученные классы ObjectFactory, которые существуют в каждом из пакетов java, содержавшихся в contextPath. Для каждой схемы полученный java class есть статический метод фабрики, который производит объекты того типа. Например, предположите, что после компиляции схемы, у Вас есть пакет com.acme.foo, который содержит схему полученный интерфейс под названием PurchaseOrder. Чтобы создать объекты того типа, клиентское приложение использовало бы метод фабрики как это:

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

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

Для получения дополнительной информации по сгенерированным классам ObjectFactory см. Раздел 4.2 Пакета Java спецификации.

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

Маршалинг

Marshaller class обеспечивает клиентское приложение возможность преобразовать дерево контента 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 class был осужден и сделан дополнительный. Это означает, что Вам советуют не использовать этот class и, фактически, это, возможно, даже не доступно в зависимости от Вашего провайдера 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. Для каждого package/class, который явно передают в к newInstance(java.lang.String) метод, в порядке, они определяются, файл jaxb.properties, ищется в его пакете, при использовании связанного classloader — это the owner class loader для a Class параметр, и для пакета speified ClassLoader.

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

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

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

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

С тех пор:
JAXB1.0
Автор:
  • Райан Шоемэкер, Sun Microsystems, Inc.
  • Kohsuke Кавагути, Sun Microsystems, Inc.
  • Джо Фьалли, Sun Microsystems, Inc.
См. Также:
Marshaller, Unmarshaller, S 7.4.1.1" Аннотации Пакета" в Спецификации языка Java, 3-ьем Выпуске

Полевая Сводка
static java.lang.String JAXB_CONTEXT_FACTORY
          The name of the property that contains the name of the class capable of creating new JAXBContext objects.
 
Сводка конструктора
protected JAXBContext()
           
 
Сводка метода
 Binder<org.w3c.dom.Node> createBinder()
          Creates a Binder for W3C DOM.
<T> Binder<T>
createBinder(java.lang.Class<T> domType)
          Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.
 JAXBIntrospector createJAXBIntrospector()
          Creates a JAXBIntrospector object that can be used to introspect JAXB objects.
abstract  Marshaller createMarshaller()
          Create a Marshaller object that can be used to convert a java content tree into XML data.
abstract  Unmarshaller createUnmarshaller()
          Create an Unmarshaller object that can be used to convert XML data into a java content tree.
abstract  Validator createValidator()
          Осуждаемый. начиная с JAXB2.0
 void generateSchema(SchemaOutputResolver outputResolver)
          Генерирует документы схемы для этого контекста.
static JAXBContext newInstance(java.lang.Class... classesToBeBound)
          Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(java.lang.Class[] classesToBeBound, java.util.Map<java.lang.String,?> properties)
          Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(java.lang.String contextPath)
          Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(java.lang.String contextPath, java.lang.ClassLoader classLoader)
          Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(java.lang.String contextPath, java.lang.ClassLoader classLoader, java.util.Map<java.lang.String,?> properties)
          Obtain a new instance of a JAXBContext class.
 
Методы, наследованные от class java.lang. Объект
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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

JAXB_CONTEXT_FACTORY

public static final java.lang.String JAXB_CONTEXT_FACTORY
The name of the property that contains the name of the class capable of creating new JAXBContext objects.

См. Также:
Постоянные Значения полей
Деталь конструктора

JAXBContext

protected JAXBContext()
Деталь метода

newInstance

public static JAXBContext newInstance(java.lang.String contextPath)
                               throws JAXBException

Obtain a new instance of a JAXBContext class.

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

Броски:
JAXBException - if an error was encountered while creating the JAXBContext such as
  1. отказ определить местоположение любого ObjectFactory. class или jaxb.index в пакетах
  2. неоднозначность среди глобальных элементов содержится в contextPath
  3. отказ определить местоположение значения для свойства провайдера фабрики контекста
  4. смешивание схемы полученные пакеты от различных провайдеров на том же самом contextPath

newInstance

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

Obtain a new instance of a JAXBContext class.

The client application must supply a context path which is a list of colon (':', \u003A) separated java package names that contain schema-derived classes and/or fully qualified JAXB-annotated classes. Schema-derived code is registered with the JAXBContext by the ObjectFactory.class generated per package. Alternatively than being listed in the context path, programmer annotated JAXB mapped classes can be listed in a jaxb.index resource file, format described below. Note that a java package can contain both schema-derived classes and user annotated JAXB classes. Additionally, the java package may contain JAXB package annotations that must be processed. (see JLS 3rd Edition, Section 7.4.1. "Package Annotations").

Every package listed on the contextPath must meet one or both of the following conditions otherwise a JAXBException will be thrown:

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

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

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

Constraints on class name occuring in a jaxb.index file are:

  • Не должен закончиться ".class".
  • Class names are resolved relative to package containing jaxb.index file. Only classes occuring directly in package containing jaxb.index file are allowed.
  • Полностью определенные имена class не позволяются. Квалифицированному имени class, относительно текущего пакета, только позволяют определить вложенный или внутренний class.

To maintain compatibility with JAXB 1.0 schema to java interface/implementation binding, enabled by schema customization , the JAXB provider will ensure that each package on the context path has a jaxb.properties file which contains a value for the javax.xml.bind.context.factory property and that all values resolve to the same provider. This requirement does not apply to JAXB annotated classes.

If there are any global XML element name collisions across the various packages listed on the contextPath, a JAXBException will be thrown.

Mixing generated interface/impl bindings from multiple JAXB Providers in the same context path may result in a JAXBException being thrown.

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

Параметры:
contextPath - список имен пакета java, которые содержат схему полученный class и/или java к схеме (JAXB-аннотируемые) отображенные классы
classLoader - Этот загрузчик class будет использоваться, чтобы определить местоположение классов реализации.
Возвраты:
a new instance of a JAXBContext
Броски:
JAXBException - if an error was encountered while creating the JAXBContext such as
  1. отказ определить местоположение любого ObjectFactory. class или jaxb.index в пакетах
  2. неоднозначность среди глобальных элементов содержится в contextPath
  3. отказ определить местоположение значения для свойства провайдера фабрики контекста
  4. смешивание схемы полученные пакеты от различных провайдеров на том же самом contextPath

newInstance

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

Obtain a new instance of a JAXBContext class.

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

The interpretation of properties is up to implementations. Implementations should throw JAXBException if it finds properties that it doesn't understand.

Параметры:
contextPath - список имен пакета java, которые содержат производные классы схемы
classLoader - Этот загрузчик class будет использоваться, чтобы определить местоположение классов реализации.
properties - специфичные для провайдера свойства. Может быть нуль, что означает ту же самую вещь как передающий в пустой карте.
Возвраты:
a new instance of a JAXBContext
Броски:
JAXBException - if an error was encountered while creating the JAXBContext such as
  1. отказ определить местоположение любого ObjectFactory. class или jaxb.index в пакетах
  2. неоднозначность среди глобальных элементов содержится в contextPath
  3. отказ определить местоположение значения для свойства провайдера фабрики контекста
  4. смешивание схемы полученные пакеты от различных провайдеров на том же самом contextPath
С тех пор:
JAXB2.0

newInstance

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

Obtain a new instance of a JAXBContext class.

The client application must supply a list of classes that the new context object needs to recognize. Not only the new context will recognize all the classes specified, but it will also recognize any classes that are directly/indirectly referenced statically from the specified classes. Subclasses of referenced classes nor @XmlTransient referenced classes are not registered with JAXBContext. For example, in the following Java code, if you do newInstance(Foo.class), the newly created JAXBContext will recognize both Foo and Bar, but not Zot or FooBar:

 class Foo {
      @XmlTransient FooBar c;
      Bar b;
 }
 class Bar { int x; }
 class Zot extends Bar { int y; }
 class FooBar { }
 
Поэтому, типичное клиентское приложение только должно определить высокоуровневые классы, но это должно быть осторожно.

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

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

Параметры:
classesToBeBound - список классов java, которые будут распознаны новым JAXBContext. Может быть пустым, когда a JAXBContext то единственное знает об определенных с помощью спецификации классах, будет возвращен.
Возвраты:
A new instance of a JAXBContext. Always non-null valid object.
Броски:
JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
  1. Никакая реализация JAXB не была обнаружена
  2. Классы используют аннотации JAXB неправильно
  3. У классов есть сталкивающиеся аннотации (то есть, два класса с тем же самым именем типа)
  4. Реализация JAXB была неспособна определить местоположение специфичной для провайдера внеполосной информации (такой как дополнительные файлы, сгенерированные во время разработки.)
IllegalArgumentException - если параметр содержит null (то есть, newInstance(null);)
С тех пор:
JAXB2.0

newInstance

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

Obtain a new instance of a JAXBContext class.

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

The interpretation of properties is up to implementations. Implementations should throw JAXBException if it finds properties that it doesn't understand.

Параметры:
classesToBeBound - список классов java, которые будут распознаны новым JAXBContext. Может быть пустым, когда a JAXBContext то единственное знает об определенных с помощью спецификации классах, будет возвращен.
properties - специфичные для провайдера свойства. Может быть нуль, что означает ту же самую вещь как передающий в пустой карте.
Возвраты:
A new instance of a JAXBContext. Always non-null valid object.
Броски:
JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
  1. Никакая реализация JAXB не была обнаружена
  2. Классы используют аннотации JAXB неправильно
  3. У классов есть сталкивающиеся аннотации (то есть, два класса с тем же самым именем типа)
  4. Реализация JAXB была неспособна определить местоположение специфичной для провайдера внеполосной информации (такой как дополнительные файлы, сгенерированные во время разработки.)
IllegalArgumentException - если параметр содержит null (то есть, newInstance(null,someMap);)
С тех пор:
JAXB2.0

createUnmarshaller

public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException
Create an Unmarshaller object that can be used to convert XML data into a java content tree.

Возвраты:
an Unmarshaller object
Броски:
JAXBException - if an error was encountered while creating the Unmarshaller object

createMarshaller

public abstract Marshaller createMarshaller()
                                     throws JAXBException
Create a Marshaller object that can be used to convert a java content tree into XML data.

Возвраты:
a Marshaller object
Броски:
JAXBException - if an error was encountered while creating the Marshaller object

createValidator

public abstract Validator createValidator()
                                   throws JAXBException
Осуждаемый. начиная с JAXB2.0

Validator был сделан дополнительным и осуждаемым в JAXB 2.0. Пожалуйста, обратитесь к javadoc для Validator для большего количества детали.

Create a Validator object that can be used to validate a java content tree against its source schema.

Возвраты:
a Validator object
Броски:
JAXBException - if an error was encountered while creating the Validator object

createBinder

public <T> Binder<T> createBinder(java.lang.Class<T> domType)
Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.

Параметры:
domType - выберите API ДОМА, чтобы использовать, передавая в его ДОМЕ Ноуде class.
Возвраты:
always a new valid Binder object.
Броски:
UnsupportedOperationException - if DOM API corresponding to domType is not supported by the implementation.
С тех пор:
JAXB2.0

createBinder

public Binder<org.w3c.dom.Node> createBinder()
Creates a Binder for W3C DOM.

Возвраты:
always a new valid Binder object.
С тех пор:
JAXB2.0

createJAXBIntrospector

public JAXBIntrospector createJAXBIntrospector()
Creates a JAXBIntrospector object that can be used to introspect JAXB objects.

Возвраты:
always return a non-null valid JAXBIntrospector object.
Броски:
UnsupportedOperationException - Вызов этого метода на JAXB 1.0 реализации бросит UnsupportedOperationException.
С тех пор:
JAXB2.0

generateSchema

public void generateSchema(SchemaOutputResolver outputResolver)
                    throws java.io.IOException
Генерирует документы схемы для этого контекста.

Параметры:
outputResolver - этот объект управляет выводом, которому будут отправлены схемы.
Броски:
java.io.IOException - если SchemaOutputResolver броски IOException.
UnsupportedOperationException - Вызов этого метода на JAXB 1.0 реализации бросит UnsupportedOperationException.
С тех пор:
JAXB 2.0


Представьте ошибку или функцию

Авторское право © 2009-2011, Oracle Corporation и/или его филиалы. Все права защищены. Использование подвергается срокам действия лицензии.

Сгенерированный на 10-February-2011 12:41


Spec-Zone.ru - all specs in one place



free hit counter