public abstract class JAXBContext extends Object
JAXBContext class обеспечивает точку входа клиента для API JAXB. Это обеспечивает абстракцию для того, чтобы она управляла информацией о привязке XML/Java, необходимой, чтобы реализовать JAXB обязательные операции платформы: неупорядочьте, упорядочьте и проверьте.
Клиентское приложение обычно получает новые экземпляры этого class, используя один из этих двух стилей для newInstance методов, хотя есть другие специализированные формы доступного метода:
JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
JAXBContext.newInstance( com.acme.foo.Foo.class )
newInstance(Class...)
для деталей. ТРЕБОВАНИЕ СПЕЦИФИКАЦИИ: провайдер должен предоставить реализацию 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, значение которого является именем 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 1.0 ограничения только применяется к обязательной схеме к классам интерфейсов/реализации. Так как эта привязка не требует общей системы времени выполнения, клиентское приложение JAXB не должно попытаться смешать объекты периода выполнения (JAXBContext, Marshaller, и т.д.) от различных провайдеров. Это не означает, что клиентское приложение не переносимо, это просто означает, что клиент должен использовать систему времени выполнения, обеспеченную тем же самым провайдером, который использовался, чтобы скомпилировать схему.
Когда один из методов newInstance вызывают, реализация JAXB обнаруживается следующими шагами.
newInstance(java.lang.String)
метод, в порядке, они определяются, файл jaxb.properties, ищется в его пакете, при использовании связанного classloader — это the owner class loader
для a Class
параметр, и для пакета указанное ClassLoader
. Если такой файл обнаруживается, это loaded
как файл свойств, и значение JAXB_CONTEXT_FACTORY
ключ, как будет предполагаться, будет фабрикой провайдера class. Этот class тогда загружается связанным classloader, обсужденным выше.
Эта фаза взгляда позволяет некоторым пакетам вызывать использование определенной реализации JAXB. (Например, возможно компилятор схемы генерировал некоторое расширение поставщика в коде.)
JAXB_CONTEXT_FACTORY
существует, тогда его значение, как предполагается, является фабрикой провайдера class. Эта фаза взгляда включает переопределению на JVM реализации JAXB. Однажды фабрика провайдера class обнаруживается, его метод public static JAXBContext createContext(String,ClassLoader,Map) (см. newInstance(String, ClassLoader, Map)
для семантики параметра.) или метод public static JAXBContext createContet(Class[],Map) (см. newInstance(Class[], Map)
для семантики параметра), вызываются, чтобы создать a JAXBContext
.
Marshaller
, Unmarshaller
, 7.4.1 "Named Packages" in Java Language Specification
Модификатор и Тип | Поле и Описание |
---|---|
static String |
JAXB_CONTEXT_FACTORY
Имя свойства, которое содержит имя class, способного к созданию новых объектов 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 class.
|
static JAXBContext |
newInstance(Class[] classesToBeBound, Map<String,?> properties)
Получите новый экземпляр JAXBContext class.
|
static JAXBContext |
newInstance(String contextPath)
Получите новый экземпляр JAXBContext class.
|
static JAXBContext |
newInstance(String contextPath, ClassLoader classLoader)
Получите новый экземпляр JAXBContext class.
|
static JAXBContext |
newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties)
Получите новый экземпляр JAXBContext class.
|
public static final String JAXB_CONTEXT_FACTORY
public static JAXBContext newInstance(String contextPath) throws JAXBException
Получите новый экземпляр JAXBContext class.
Это - метод удобства, чтобы вызвать newInstance(String,ClassLoader)
метод с контекстом загрузчик class текущего потока.
JAXBException
- если с ошибкой встретились, создавая JAXBContext такой как public static JAXBContext newInstance(String contextPath, ClassLoader classLoader) throws JAXBException
Получите новый экземпляр JAXBContext class.
Клиентское приложение должно предоставить путь контекста, который является списком двоеточия (': ', \u003A) разделенные имена пакета java, которые содержат производные классы схемы и/или полностью определили JAXB-аннотируемые классы. Полученный из схемы код регистрируется в JAXBContext ObjectFactory. class сгенерирован на пакет. Альтернативно чем быть перечисленным в пути контекста, программист аннотировал JAXB, отображенные классы могут быть перечислены в файле ресурсов jaxb.index, формат, описанный ниже. Отметьте, что пакет java может содержать оба производных класса схемы и пользователя аннотируемые классы JAXB. Дополнительно, пакет java может содержать аннотации пакета JAXB, которые должны быть обработаны. (см. JLS, Раздел 7.4.1" Именованных Пакета").
Каждый пакет, перечисленный на contextPath, должен встретиться один или оба из следующих условий иначе, JAXBException будет брошен:
Формат для jaxb.index
Файл содержит разделенный от новой строки список имен class. Пространство и символы вкладки, так же как пустые строки, игнорируются. Символ комментария '#' (0x23); на каждой строке игнорируются все символы после первого символа комментария. Файл должен быть закодирован в UTF-8. Классы, которые достижимы, как определено в newInstance(Class...)
, от перечисленных классов также регистрируются в JAXBContext.
Ограничения на имя class, происходящее в файле 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, обсуждаются в class javadoc.
contextPath
- список имен пакета java, которые содержат схему полученный class и/или java к схеме (JAXB-аннотируемые) отображенные классыclassLoader
- Этот загрузчик class будет использоваться, чтобы определить местоположение классов реализации.JAXBException
- если с ошибкой встретились, создавая JAXBContext такой как public static JAXBContext newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) throws JAXBException
Получите новый экземпляр JAXBContext class.
Это - главным образом то же самое как newInstance(String, ClassLoader)
, но эта версия позволяет Вам передавать в специфичных для провайдера свойствах, чтобы сконфигурировать инстанцирование JAXBContext
.
Интерпретация свойств до реализаций. Реализации должны бросить JAXBException, если он находит свойства, которые он не понимает.
contextPath
- список имен пакета java, которые содержат производные классы схемыclassLoader
- Этот загрузчик class будет использоваться, чтобы определить местоположение классов реализации.properties
- специфичные для провайдера свойства. Может быть нуль, что означает ту же самую вещь как передающий в пустой карте.JAXBException
- если с ошибкой встретились, создавая JAXBContext такой как public static JAXBContext newInstance(Class... classesToBeBound) throws JAXBException
Получите новый экземпляр JAXBContext class.
Клиентское приложение должно предоставить список классов, которые должен распознать новый объект контекста. Не только новый контекст распознает все определенные классы, но он также распознает любые классы, на которые непосредственно/косвенно ссылаются статически от указанных классов. Подклассы классов, на которые ссылаются, ни @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, обсуждаются в class javadoc.
classesToBeBound
- список классов java, которые будут распознаны новым JAXBContext
. Может быть пустым, когда a JAXBContext
то единственное знает об определенных с помощью спецификации классах, будет возвращен.JAXBException
- если с ошибкой встретились, создавая JAXBContext, такой как (но не ограничена): IllegalArgumentException
- если параметр содержит null
(то есть, newInstance(null);
)public static JAXBContext newInstance(Class[] classesToBeBound, Map<String,?> properties) throws JAXBException
Получите новый экземпляр JAXBContext class.
Перегрузка newInstance(Class...)
сконфигурировать 'свойства' для этого инстанцирования JAXBContext
.
Интерпретация свойств до реализаций. Реализации должны бросить JAXBException, если он находит свойства, которые он не понимает.
classesToBeBound
- список классов java, которые будут распознаны новым JAXBContext
. Может быть пустым, когда a JAXBContext
то единственное знает об определенных с помощью спецификации классах, будет возвращен.properties
- специфичные для провайдера свойства. Может быть нуль, что означает ту же самую вещь как передающий в пустой карте.JAXBException
- если с ошибкой встретились, создавая JAXBContext, такой как (но не ограничена): IllegalArgumentException
- если параметр содержит null
(то есть, newInstance(null,someMap);
)public abstract Unmarshaller createUnmarshaller() throws JAXBException
JAXBException
- если с ошибкой встретились, создавая объект Unmarshallerpublic abstract Marshaller createMarshaller() throws JAXBException
JAXBException
- если с ошибкой встретились, создавая объект Marshallerpublic abstract Validator createValidator() throws JAXBException
Validator
был сделан дополнительным и осуждаемым в JAXB 2.0. Пожалуйста, обратитесь к javadoc для Validator
для большего количества детали. Создайте объект Validator, который может использоваться, чтобы проверить дерева контента java против его исходной схемы.
JAXBException
- если с ошибкой встретились, создавая объект Validatorpublic <T> Binder<T> createBinder(Class<T> domType)
domType
- выберите API ДОМА, чтобы использовать, передавая в его ДОМЕ Ноуде class.UnsupportedOperationException
- если API ДОМА, соответствующий domType, не поддерживается реализацией.public Binder<Node> createBinder()
public JAXBIntrospector createJAXBIntrospector()
UnsupportedOperationException
- Вызов этого метода на JAXB 1.0 реализации бросит UnsupportedOperationException.public void generateSchema(SchemaOutputResolver outputResolver) throws IOException
outputResolver
- этот объект управляет выводом, которому будут отправлены схемы.IOException
- если SchemaOutputResolver
броски IOException
.UnsupportedOperationException
- Вызов этого метода на JAXB 1.0 реализации бросит UnsupportedOperationException.
Для дальнейшей ссылки API и документации разработчика, см. Java Документация SE. Та документация содержит более подробные, предназначенные разработчиком описания, с концептуальными краткими обзорами, определениями сроков, обходных решений, и рабочих примеров кода.
Авторское право © 1993, 2013, Oracle и/или его филиалы. Все права защищены.
Проект сборка-b92