Интерфейс Unmarshaller
- Все известные реализующие классы:
- AbstractUnmarshallerImpl
public interface Unmarshaller
Класс Unmarshaller управляет процессом десериализации XML-данных в новые созданные деревья Java-содержания, при необходимости валидируя XML-данные во время разбора. Он предоставляет перегрузку методов unmarshal для различных типов входных данных.
Разбор из файла:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); Object o = u.unmarshal( new File( "nosferatu.xml" ) );
Разбор из потока ввода:
InputStream is = new FileInputStream( "nosferatu.xml" ); JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); Object o = u.unmarshal( is );
Разбор из URL:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); URL url = new URL( "http://beaker.east/nosferatu.xml" ); Object o = u.unmarshal( url );
Разбор из StringBuffer с использованием javax.xml.transform.stream.StreamSource:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." ); Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );
Разбор из org.w3c.dom.Node:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); DocumentBuilder db = dbf.newDocumentBuilder(); Document doc = db.parse(new File( "nosferatu.xml")); Object o = u.unmarshal( doc );
Разбор из javax.xml.transform.sax.SAXSource с использованием указанного клиентом валидирующего SAX2.0 парсера:
// configure a validating SAX2.0 parser (Xerces2)
static final String JAXP_SCHEMA_LANGUAGE =
"http://java.sun.com/xml/jaxp/properties/schemaLanguage";
static final String JAXP_SCHEMA_LOCATION =
"http://java.sun.com/xml/jaxp/properties/schemaSource";
static final String W3C_XML_SCHEMA =
"http://www.w3.org/2001/XMLSchema";
System.setProperty( "javax.xml.parsers.SAXParserFactory",
"org.apache.xerces.jaxp.SAXParserFactoryImpl" );
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setNamespaceAware(true);
spf.setValidating(true);
SAXParser saxParser = spf.newSAXParser();
try {
saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://....");
} catch (SAXNotRecognizedException x) {
// exception handling omitted
}
XMLReader xmlReader = saxParser.getXMLReader();
SAXSource source =
new SAXSource( xmlReader, new InputSource( "http://..." ) );
// Setup JAXB to unmarshal
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
ValidationEventCollector vec = new ValidationEventCollector();
u.setEventHandler( vec );
// turn off the JAXB provider's default validation mechanism to
// avoid duplicate validation
u.setValidating( false )
// unmarshal
Object o = u.unmarshal( source );
// check for events
if( vec.hasEvents() ) {
// iterate over events
} Разбор из StAX XMLStreamReader:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
javax.xml.stream.XMLStreamReader xmlStreamReader =
javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... );
Object o = u.unmarshal( xmlStreamReader ); Разбор из StAX XMLEventReader:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
javax.xml.stream.XMLEventReader xmlEventReader =
javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );
Object o = u.unmarshal( xmlEventReader ); Разбор XML-данных
Разбор может десериализовать XML-данные, представляющие собой либо весь XML-документ, либо поддерево XML-документа. Обычно достаточно использовать методы разбора, описанные в разбор корневого элемента, объявленного глобально. Эти методы разбора используют сопоставлениеJAXBContextглобальных объявлений XML-элементов и определений типов с отображёнными JAXB-классами для инициирования разбора корневого элемента XML-данных. Когда сопоставленияJAXBContextнедостаточно для разбора корневого элемента XML-данных, приложение может помочь в этом процессе, используя методы разбора по типу. Эти методы полезны для разбора XML-данных, где корневой элемент соответствует локальному объявлению элемента в схеме.
Метод unmarshal никогда не возвращает null. Если процесс разбора не может разобрать корень XML-содержания в объект, отображаемый JAXB, сообщается об ошибке, которая завершает обработку, выбросив исключение JAXBException.
Разбор корневого элемента, объявленного глобально
The unmarshal methods that do not have an declaredType parameter use JAXBContext to unmarshal the root element of an XML data. The JAXBContext instance is the one that was used to create this Unmarshaller. The JAXBContext instance maintains a mapping of globally declared XML element and type definition names to JAXB mapped classes. The unmarshal method checks if JAXBContext has a mapping from the root element's XML name and/or @xsi:type to a JAXB mapped class. If it does, it umarshalls the XML data using the appropriate JAXB mapped class. Note that when the root element name is unknown and the root element has an @xsi:type, the XML data is unmarshalled using that JAXB mapped class as the value of a JAXBElement. When the JAXBContext object does not have a mapping for the root element's name nor its @xsi:type, if it exists, then the unmarshal operation will abort immediately by throwing a UnmarshalException. This exception scenario can be worked around by using the unmarshal by declaredType methods described in the next subsection.
Разбор по объявленному типу
The unmarshal methods with a declaredType parameter enable an application to deserialize a root element of XML data, even when there is no mapping in JAXBContext of the root element's XML name. The unmarshaller unmarshals the root element using the application provided mapping specified as the declaredType parameter. Note that even when the root element's element name is mapped by JAXBContext, the declaredType parameter overrides that mapping for deserializing the root element when using these unmarshal methods. Additionally, when the root element of XML data has an xsi:type attribute and that attribute's value references a type definition that is mapped to a JAXB mapped class by JAXBContext, that the root element's xsi:type attribute takes precedence over the unmarshal methods declaredType parameter. These methods always return a JAXBElement<declaredType> instance. The table below shows how the properties of the returned JAXBElement instance are set. Unmarshal By Declared Type returned JAXBElement JAXBElement Property Value name xml element name value instanceof declaredType declaredType unmarshal method declaredType parameter scope null (actual scope is unknown)
Следующий пример использования метода разбора по объявленному типу.
Разбор по объявленному типу из org.w3c.dom.Node:
Schema fragment for example
<xs:schema>
<xs:complexType name="FooType">...<\xs:complexType>
<!-- global element declaration "PurchaseOrder" -->
<xs:element name="PurchaseOrder">
<xs:complexType>
<xs:sequence>
<!-- local element declaration "foo" -->
<xs:element name="foo" type="FooType"/>
...
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.parse(new File( "nosferatu.xml"));
Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
// local element declaration in schema.
// FooType is the JAXB mapping of the type of local element declaration foo.
JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class); Поддержка SAX2.0-совместимых парсеров
Приложению-клиенту предоставляется возможность выбрать парсер SAX2.0 по своему выбору. Если парсер SAX не выбран, будет использован парсер по умолчанию JAXB-провайдера. Хотя парсер по умолчанию JAXB-провайдера не обязан быть совместимым с SAX2.0, все провайдеры обязаны позволять приложению-клиенту указывать свой собственный парсер SAX2.0. Некоторые провайдеры могут потребовать, чтобы приложение-клиент указало парсер SAX2.0 во время компиляции схемы. Подробности см. в unmarshal(Source). Валидация и корректность
Приложение-клиент может включить или выключить механизм валидации JAXP 1.3 через API
setSchema(javax.xml.validation.Schema). Развитые клиенты могут указать свой собственный валидирующий SAX 2.0-совместимый парсер и обойти механизм валидации JAXP 1.3, используя APIunmarshal(Source).Поскольку разбор некорректного XML-содержания определён в JAXB 2.0, обработчик валидации по умолчанию Unmarshaller был сделан более гибким, чем в JAXB 1.0. При регистрации кода, сгенерированного компилятором привязки JAXB 1.0, со
JAXBContext, обработчик валидации по умолчанию для разбора —DefaultValidationEventHandler, и он завершает операцию разбора после обнаружения критической или некритической ошибки. Для приложения-клиента JAXB 2.0 явно определённый обработчик валидации по умолчанию отсутствует, и обработка событий по умолчанию завершает операцию разбора только после обнаружения критической ошибки.
Поддерживаемые свойства
В настоящее время нет свойств, которые должны поддерживаться всеми JAXB-провайдерами в Unmarshaller. Однако некоторые провайдеры могут поддерживать свой собственный набор свойств, специфичных для провайдера.
Обратные вызовы событий разбора
Unmarshallerпредоставляет два типа механизмов обратных вызовов, которые позволяют выполнять обработку, специфичную для приложения, в ключевых точках процесса разбора. В обратных вызовах, определённых классом, код, специфичный для приложения, помещённый в сопоставленные с JAXB классы, запускается во время разбора. «Внешние слушатели» позволяют централизованно обрабатывать события разбора в одном методе обратного вызова вместо обратных вызовов по типу.Методы обратных вызовов, определённые классом, позволяют любому отображаемому JAXB классу указать свои собственные методы обратных вызовов, определив методы со следующим сигнатуром:
// This method is called immediately after the object is created and before the unmarshalling of this // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling. void beforeUnmarshal(Unmarshaller, Object parent); //This method is called after all the properties (except IDREF) are unmarshalled for this object, //but before this object is set to the parent object. void afterUnmarshal(Unmarshaller, Object parent);Методы обратных вызовов, определённые классом, следует использовать, когда методу обратного вызова требуется доступ к закрытым методам и/или полям класса.Механизм обратного вызова внешнего слушателя позволяет зарегистрировать экземпляр
Unmarshaller.Listenerс помощьюsetListener(Listener). Внешний слушатель получает все события обратного вызова, что позволяет более централизованную обработку, чем обработку по типу обратных вызовов. Внешний слушатель получает события, когда процесс разбора передаёт данные в JAXB-элемент или в отображаемый JAXB-класс.Методы обратных вызовов «определённые классом» и внешние слушатели независимы друг от друга; оба могут быть вызваны для одного события. Порядок вызова, когда существуют оба типа методов обратного вызова, определён в
Unmarshaller.Listener.beforeUnmarshal(Object, Object)иUnmarshaller.Listener.afterUnmarshal(Object, Object).Метод обратного вызова, выбрасывающий исключение, прерывает текущий процесс разбора.
- С:
- JAXB1.0
- См. также:
-
JAXBContext,Marshaller,Validator
Вложенные классы
| Модификатор и тип | Интерфейс и описание |
|---|---|
static class |
Unmarshaller.Listener
Зарегистрируйте экземпляр реализации этого класса с помощью Unmarshaller, чтобы внешне прослушивать события разбора. |
Методы
| Модификатор и тип | Метод и описание |
|---|---|
<A extends XmlAdapter> |
getAdapter(Class<A> type) Получает адаптер, связанный со указанным типом. |
AttachmentUnmarshaller |
getAttachmentUnmarshaller() |
ValidationEventHandler |
getEventHandler() Возвращает текущий обработчик событий или обработчик по умолчанию, если он не был задан. |
Unmarshaller.Listener |
getListener() Возвращает зарегистрированный |
Object |
getProperty(String name) Получить конкретное свойство в базовой реализации |
Schema |
getSchema() Получить объект JAXP 1.3 |
UnmarshallerHandler |
getUnmarshallerHandler() Получить объект обработчика разбора, который может использоваться как компонент в XML-пайплайне. |
boolean |
isValidating() Устарело. с JAXB2.0, см. |
<A extends XmlAdapter> |
setAdapter(Class<A> type,
A adapter) Связывает настроенный экземпляр |
void |
setAdapter(XmlAdapter adapter) Связывает настроенный экземпляр |
void |
setAttachmentUnmarshaller(AttachmentUnmarshaller au) Связывает контекст, который разрешает идентификаторы содержимого (CID), URI идентификаторов содержимого, с бинарными данными, переданными в виде вложений. |
void |
setEventHandler(ValidationEventHandler handler) Позволяет приложению зарегистрировать |
void |
setListener(Unmarshaller.Listener listener) Регистрирует обратный вызов события разбора |
void |
setProperty(String name,
Object value) Устанавливает конкретное свойство в базовой реализации |
void |
setSchema(Schema schema) Укажите объект JAXP 1.3 |
void |
setValidating(boolean validating) Устарело. с JAXB2.0, см. |
Object |
unmarshal(File f) Разбирает XML-данные из указанного файла и возвращает результирующее дерево содержимого. |
Object |
unmarshal(InputSource source) Разбирает XML-данные из указанного SAX InputSource и возвращает результирующее дерево содержимого. |
Object |
unmarshal(InputStream is) Разбирает XML-данные из указанного InputStream и возвращает результирующее дерево содержимого. |
Object |
unmarshal(Node node) Разбирает глобальные XML-данные из указанного дерева DOM и возвращает результирующее дерево содержимого. |
<T> JAXBElement<T> |
unmarshal(Node node,
Class<T> declaredType) Разбирает XML-данные с использованием сопоставленного с JAXB |
Object |
unmarshal(Reader reader) Разбирает XML-данные из указанного Reader и возвращает результирующее дерево содержимого. |
Object |
unmarshal(Source source) Разбирает XML-данные из указанного XML Source и возвращает результирующее дерево содержимого. |
<T> JAXBElement<T> |
unmarshal(Source source,
Class<T> declaredType) Разбирает XML-данные из указанного XML Source с помощью |
Object |
unmarshal(URL url) Разбирает XML-данные из указанного URL и возвращает результирующее дерево содержимого. |
Object |
unmarshal(XMLEventReader reader) Разбирает XML-данные из указанного парсера pull и возвращает результирующее дерево содержимого. |
<T> JAXBElement<T> |
unmarshal(XMLEventReader reader,
Class<T> declaredType) Разбирает корневой элемент с использованием сопоставления JAXB |
Object |
unmarshal(XMLStreamReader reader) Разбирает XML-данные из указанного парсера pull и возвращает результирующее дерево содержимого. |
<T> JAXBElement<T> |
unmarshal(XMLStreamReader reader,
Class<T> declaredType) Разбирает корневой элемент с использованием сопоставления JAXB |
Методы
unmarshal
Object unmarshal(File f)
throws JAXBException Распаковывает XML-данные из указанного файла и возвращает результирующее дерево контента.
Реализует Unmarshal Global Root Element.
- Параметры:
-
f- файл, из которого нужно распаковать XML-данные - Возвращает:
- недавно созданный корневой объект дерева контента java
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если параметр file равен null
unmarshal
Object unmarshal(InputStream is)
throws JAXBException Распаковывает XML-данные из указанного InputStream и возвращает результирующее дерево контента. Информация о местоположении события проверки может быть неполной при использовании этой формы API unmarshal.
Реализует Unmarshal Global Root Element.
- Параметры:
-
is- InputStream, из которого нужно распаковать XML-данные - Возвращает:
- недавно созданный корневой объект дерева контента java
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если параметр InputStream равен null
unmarshal
Object unmarshal(Reader reader)
throws JAXBException Распаковывает XML-данные из указанного Reader и возвращает результирующее дерево контента. Информация о местоположении события проверки может быть неполной при использовании этой формы API unmarshal, поскольку Reader не предоставляет системный ID.
Реализует Unmarshal Global Root Element.
- Параметры:
-
reader- Reader, из которого нужно распаковать XML-данные - Возвращает:
- недавно созданный корневой объект дерева контента java
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если параметр InputStream равен null - С версии:
- JAXB2.0
unmarshal
Object unmarshal(URL url)
throws JAXBException Распаковывает XML-данные из указанного URL и возвращает результирующее дерево контента.
Реализует Unmarshal Global Root Element.
- Параметры:
-
url- url, из которого нужно распаковать XML-данные - Возвращает:
- недавно созданный корневой объект дерева контента java
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если параметр URL равен null
unmarshal
Object unmarshal(InputSource source)
throws JAXBException Распаковывает XML-данные из указанного SAX InputSource и возвращает результирующее дерево контента.
Реализует Unmarshal Global Root Element.
- Параметры:
-
source- источник ввода, из которого нужно распаковать XML-данные - Возвращает:
- недавно созданный корневой объект дерева контента java
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если параметр InputSource равен null
unmarshal
Object unmarshal(Node node)
throws JAXBException Распаковывает глобальные XML-данные из указанного дерева DOM и возвращает результирующее дерево контента.
Реализует Unmarshal Global Root Element.
- Параметры:
-
node- документ/элемент, из которого нужно распаковать XML-данные. Вызывающий должен поддерживать как минимум Document и Element. - Возвращает:
- недавно созданный корневой объект дерева контента java
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если параметр Node равен null - См. также:
unmarshal(org.w3c.dom.Node, Class)
unmarshal
<T> JAXBElement<T> unmarshal(Node node,
Class<T> declaredType)
throws JAXBException Распаковывает XML-данные с помощью сопоставленного JAXB declaredType и возвращает результирующее дерево контента.
Реализует Unmarshal by Declared Type
- Параметры:
-
node- документ/элемент, из которого нужно распаковать XML-данные. Вызывающий должен поддерживать как минимум Document и Element. -
declaredType- соответствующий сопоставленный класс JAXB для хранения XML-данныхnode. - Возвращает:
-
JAXB Element представление
node - Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если любой параметр равен null - С версии:
- JAXB2.0
unmarshal
Object unmarshal(Source source)
throws JAXBException Распаковывает XML-данные из указанного XML Source и возвращает результирующее дерево контента.
Реализует Unmarshal Global Root Element.
Возможность подключения парсера SAX 2.0
Клиентское приложение может отказаться от использования механизма парсера по умолчанию, поставляемого с его поставщиком JAXB. Любой совместимый с SAX 2.0 парсер может быть заменен механизмом по умолчанию поставщика JAXB. Для этого клиентское приложение должно правильно настроить SAXSource, содержащий XMLReader, реализованный поставщиком парсера SAX 2.0. Если XMLReader имеет зарегистрированный org.xml.sax.ErrorHandler, он будет заменен поставщиком JAXB, чтобы ошибки проверки могли быть сообщены через механизм ValidationEventHandler JAXB. Если SAXSource не содержит XMLReader, то будет использоваться механизм парсера по умолчанию поставщика JAXB.
Этот механизм замены парсера также может использоваться для замены механизма проверки во время распаковки поставщика JAXB. Клиентское приложение должно правильно настроить свой совместимый с SAX 2.0 парсер для выполнения проверки (как показано в примере выше). Любые SAXParserExceptions , обнаруженные парсером во время операции распаковки, будут обработаны поставщиком JAXB и преобразованы в объекты JAXB ValidationEvent, которые будут переданы клиенту через ValidationEventHandler, зарегистрированный в Unmarshaller. Примечание: указание замещающего парсера SAX 2.0 для распаковки не обязательно заменяет механизм проверки, используемый поставщиком JAXB для выполнения проверки по требованию.
Единственный способ для клиентского приложения указать альтернативный механизм парсера, который будет использоваться во время распаковки, - это через API unmarshal(SAXSource). Все другие формы метода распаковки (File, URL, Node и т.д.) будут использовать механизмы парсера и валидатора по умолчанию поставщика JAXB.
- Параметры:
-
source- XML Source, из которого нужно распаковать XML-данные (поставщики обязаны поддерживать только SAXSource, DOMSource и StreamSource) - Возвращает:
- недавно созданный корневой объект дерева контента java
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если параметр Source равен null - См. также:
unmarshal(javax.xml.transform.Source, Class)
unmarshal
<T> JAXBElement<T> unmarshal(Source source,
Class<T> declaredType)
throws JAXBException Распаковывает XML-данные из указанного XML Source по declaredType и возвращает результирующее дерево контента.
Реализует Unmarshal by Declared Type
- Параметры:
-
source- XML Source, из которого нужно распаковать XML-данные (поставщики обязаны поддерживать только SAXSource, DOMSource и StreamSource) -
declaredType- соответствующий сопоставленный класс JAXB для хранения корневого элемента xmlsource - Возвращает:
- Java контент с корнем JAXB Element
- Исключения:
-
JAXBException- Если во время распаковки возникают непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Unmarshalling XML Data -
IllegalArgumentException- Если любой параметр равен null - С версии:
- JAXB2.0
unmarshal
Object unmarshal(XMLStreamReader reader)
throws JAXBException Распарсить XML-данные из указанного парсера pull и вернуть получившееся дерево содержимого.
Реализует Распарсивание глобального корневого элемента.
Этот метод предполагает, что парсер находится в событии START_DOCUMENT или START_ELEMENT. Распарсивание будет выполняться от этого начального события до соответствующего конечного события. Если этот метод выполняется успешно, reader будет указывать на токен сразу после конечного события.
- Параметры:
-
reader- Парсер для чтения. - Возвращает:
- новый созданный корневой объект дерева содержимого Java.
- Исключения:
-
JAXBException- Если при распарсивании произошли какие-либо непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Распарсивание XML-данных -
IllegalArgumentException- Если параметрreaderравен null -
IllegalStateException- Еслиreaderне указывает на событие START_DOCUMENT или START_ELEMENT. - С:
- JAXB2.0
- См. также:
unmarshal(javax.xml.stream.XMLStreamReader, Class)
unmarshal
<T> JAXBElement<T> unmarshal(XMLStreamReader reader,
Class<T> declaredType)
throws JAXBException Распарсить корневой элемент в сопоставленный с JAXB declaredType и вернуть получившееся дерево содержимого.
Этот метод реализует распарсивание по declaredType.
Этот метод предполагает, что парсер находится в событии START_DOCUMENT или START_ELEMENT. Распарсивание будет выполняться от этого начального события до соответствующего конечного события. Если этот метод выполняется успешно, reader будет указывать на токен сразу после конечного события.
- Параметры:
-
reader- Парсер для чтения. -
declaredType- соответствующий сопоставленный с JAXB класс для храненияreaderданных START_ELEMENT XML. - Возвращает:
- дерево содержимого с корнем в представлении элемента JAXB
- Исключения:
-
JAXBException- Если при распарсивании произошли какие-либо непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Распарсивание XML-данных -
IllegalArgumentException- Если какой-либо параметр равен null - С:
- JAXB2.0
unmarshal
Object unmarshal(XMLEventReader reader)
throws JAXBException Распарсить XML-данные из указанного парсера pull и вернуть получившееся дерево содержимого.
Этот метод является методом распарсивания глобального корневого элемента.
Этот метод предполагает, что парсер находится в событии START_DOCUMENT или START_ELEMENT. Распарсивание будет выполняться от этого начального события до соответствующего конечного события. Если этот метод выполняется успешно, reader будет указывать на токен сразу после конечного события.
- Параметры:
-
reader- Парсер для чтения. - Возвращает:
- новый созданный корневой объект дерева содержимого Java.
- Исключения:
-
JAXBException- Если при распарсивании произошли какие-либо непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Распарсивание XML-данных -
IllegalArgumentException- Если параметрreaderравен null -
IllegalStateException- Еслиreaderне указывает на событие START_DOCUMENT или START_ELEMENT. - С:
- JAXB2.0
- См. также:
unmarshal(javax.xml.stream.XMLEventReader, Class)
unmarshal
<T> JAXBElement<T> unmarshal(XMLEventReader reader,
Class<T> declaredType)
throws JAXBException Распарсить корневой элемент в сопоставленный с JAXB declaredType и вернуть получившееся дерево содержимого.
Этот метод реализует распарсивание по declaredType.
Этот метод предполагает, что парсер находится в событии START_DOCUMENT или START_ELEMENT. Распарсивание будет выполняться от этого начального события до соответствующего конечного события. Если этот метод выполняется успешно, reader будет указывать на токен сразу после конечного события.
- Параметры:
-
reader- Парсер для чтения. -
declaredType- соответствующий сопоставленный с JAXB класс для храненияreaderданных START_ELEMENT XML. - Возвращает:
- дерево содержимого с корнем в представлении элемента JAXB
- Исключения:
-
JAXBException- Если при распарсивании произошли какие-либо непредвиденные ошибки -
UnmarshalException- ЕслиValidationEventHandlerвозвращает false из своего методаhandleEventилиUnmarshallerне может выполнить привязку XML к Java. См. Распарсивание XML-данных -
IllegalArgumentException- Если какой-либо параметр равен null - С:
- JAXB2.0
getUnmarshallerHandler
UnmarshallerHandler getUnmarshallerHandler()
Получить объект обработчика распарсивания, который может быть использован как компонент в XML-пайплайне.
JAXB Provider может вернуть тот же объект обработчика для нескольких вызовов этого метода. Другими словами, этот метод не обязательно создаёт новый экземпляр UnmarshallerHandler. Если приложение нуждается в использовании более одного UnmarshallerHandler, оно должно создать более одного Unmarshaller.
- Возвращает:
- объект обработчика распарсивания
- См. также:
UnmarshallerHandler
setValidating
void setValidating(boolean validating)
throws JAXBException Устаревший. С JAXB2.0, см. setSchema(javax.xml.validation.Schema)
Указывает, должен ли механизм валидации по умолчанию Unmarshaller выполнять валидацию во время операций распарсивания. По умолчанию Unmarshaller не выполняет валидацию.
Этот метод может быть вызван только до или после вызова одного из методов распарсивания.
Этот метод управляет только механизмом валидации распарсивания по умолчанию JAXB Provider - он не влияет на клиентов, которые указывают свой собственный валидирующий SAX 2.0-совместимый парсер. Клиенты, которые указывают свой собственный механизм валидации распарсивания, могут отключить механизм валидации по умолчанию JAXB Provider через этот API, чтобы избежать «двойной валидации».
Этот метод устарел с JAXB 2.0 - используйте новый API setSchema(javax.xml.validation.Schema).
- Параметры:
-
validating- true, если Unmarshaller должен выполнять валидацию во время распарсивания, иначе false - Исключения:
-
JAXBException- если произошла ошибка при включении или отключении валидации во время распарсивания -
UnsupportedOperationException- может быть выброшен, если этот метод вызван на Unmarshaller, созданном из JAXBContext, ссылающемся на классы JAXB 2.0
isValidating
boolean isValidating()
throws JAXBException Устаревший. С JAXB2.0, см. getSchema()
Указывает, сконфигурирован ли Unmarshaller для валидации во время операций распарсивания.
Этот API возвращает состояние механизма валидации распарсивания по умолчанию JAXB Provider.
Этот метод устарел с JAXB 2.0 - используйте новый API getSchema().
- Возвращает:
- true, если Unmarshaller сконфигурирован для валидации во время распарсивания, иначе false
- Исключения:
-
JAXBException- если при получении флага валидации произошла ошибка -
UnsupportedOperationException- может быть выброшен, если этот метод вызван на Unmarshaller, созданном из JAXBContext, ссылающемся на классы JAXB 2.0
setEventHandler
void setEventHandler(ValidationEventHandler handler)
throws JAXBException Позволяет приложению зарегистрировать ValidationEventHandler.
ValidationEventHandler будет вызван JAXB Provider, если при валидации во время вызовов методов распарсивания будут обнаружены ошибки. Если клиентское приложение не зарегистрирует ValidationEventHandler перед вызовом методов распарсивания, то ValidationEvents будет обрабатываться обработчиком событий по умолчанию, который завершит операцию распарсивания после обнаружения первой или критической ошибки.
Вызов этого метода с параметром null вернёт Unmarshaller к обработчику событий по умолчанию.
- Параметры:
-
handler- обработчик событий валидации - Исключения:
-
JAXBException- если произошла ошибка при установке обработчика событий
getEventHandler
ValidationEventHandler getEventHandler()
throws JAXBException Возвращает текущий обработчик событий или обработчик событий по умолчанию, если он не установлен.
- Возвращает:
- текущий ValidationEventHandler или обработчик событий по умолчанию, если он не установлен
- Исключения:
-
JAXBException- если при получении текущего обработчика событий произошла ошибка
setProperty
void setProperty(String name,
Object value)
throws PropertyException Установить определённый свойство в базовой реализации Unmarshaller. Этот метод может использоваться только для установки одного из стандартных свойств JAXB или свойства, специфичного для провайдера. Попытка установить неопределённое свойство приведёт к выбросу исключения PropertyException. См. Поддерживаемые свойства.
- Параметры:
-
name- имя свойства для установки. Это значение может быть указано с использованием одного из константных полей или строки, предоставленной пользователем. -
value- значение свойства для установки - Исключения:
-
PropertyException- при возникновении ошибки обработки заданного свойства или значения -
IllegalArgumentException- Если параметр name равен null
getProperty
Object getProperty(String name)
throws PropertyException Получить определённое свойство в базовой реализации Unmarshaller. Этот метод может использоваться только для получения одного из стандартных свойств JAXB или свойства, специфичного для провайдера. Попытка получить неопределённое свойство приведёт к выбросу исключения PropertyException. См. Поддерживаемые свойства.
- Параметры:
-
name- имя свойства для извлечения - Возвращает:
- значение запрошенного свойства
- Выбрасывает:
-
PropertyException- при ошибке извлечения заданного свойства или имени свойства -
IllegalArgumentException- если параметр имени равен null
setSchema
void setSchema(Schema schema)
Укажите объект JAXP 1.3 Schema, который должен использоваться для валидации последующих операций разархивирования относительно него. Передача null в этот метод отключит валидацию.
Этот метод заменяет устаревший API setValidating(boolean).
Изначально это свойство установлено в null.
- Параметры:
-
schema- Объект схемы для валидации операций разархивирования или null для отключения валидации - Выбрасывает:
-
UnsupportedOperationException- может быть выброшено, если этот метод вызывается на разархиваторе, созданном из JAXBContext, ссылающемся на отображенные классы JAXB 1.0 - С:
- JAXB2.0
getSchema
Schema getSchema()
Получить объект JAXP 1.3 Schema, используемый для валидации во время разархивирования. Если для разархиватора не задана схема, то этот метод вернет null, указывая, что валидация во время разархивирования не будет выполнена.
Этот метод предоставляет функциональность для замены устаревшего API isValidating(), а также доступ к объекту схемы. Для определения, включена ли валидация в разархиваторе, просто проверьте возвращаемый тип на null:
boolean isValidating = u.getSchema()!=null;
- Возвращает:
- объект схемы, используемый для валидации во время разархивирования, или null, если он отсутствует
- Выбрасывает:
-
UnsupportedOperationException- может быть выброшено, если этот метод вызывается на разархиваторе, созданном из JAXBContext, ссылающемся на отображенные классы JAXB 1.0 - С:
- JAXB2.0
setAdapter
void setAdapter(XmlAdapter adapter)
Связывает с данным разархиватором настроенный экземпляр XmlAdapter.
Это удобный метод, который вызывает setAdapter(adapter.getClass(),adapter);.
- Выбрасывает:
-
IllegalArgumentException- если параметр адаптера равен null. -
UnsupportedOperationException- если вызов производится на реализации JAXB 1.0. - С:
- JAXB2.0
- См. также:
setAdapter(Class,XmlAdapter)
setAdapter
<A extends XmlAdapter> void setAdapter(Class<A> type,
A adapter) Связывает с данным разархиватором настроенный экземпляр XmlAdapter.
Каждый разархиватор внутренне поддерживает Map<Class,XmlAdapter>, который он использует для разархивирования классов, поля/методы которых аннотированы с XmlJavaTypeAdapter.
Этот метод позволяет приложениям использовать настроенный экземпляр XmlAdapter. Если экземпляр адаптера не указан, разархиватор создаст его, вызвав его конструктор по умолчанию.
- Параметры:
-
type- Тип адаптера. Указанный экземпляр будет использоваться, когдаXmlJavaTypeAdapter.value()ссылается на этот тип. -
adapter- Экземпляр адаптера для использования. Если null, текущий адаптер для этого типа будет удален. - Выбрасывает:
-
IllegalArgumentException- если параметр типа равен null. -
UnsupportedOperationException- если вызов производится на реализации JAXB 1.0. - С:
- JAXB2.0
getAdapter
<A extends XmlAdapter> A getAdapter(Class<A> type)
Получить адаптер, связанный со специфицированным типом. Это обратная операция метода setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter).
- Выбрасывает:
-
IllegalArgumentException- если параметр типа равен null. -
UnsupportedOperationException- если вызов производится на реализации JAXB 1.0. - С:
- JAXB2.0
setAttachmentUnmarshaller
void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
Связывает контекст, который разрешает cid, URI идентификатора содержимого, с бинарными данными, переданными в качестве вложений.
Валидация во время разархивирования, включенная с помощью setSchema(Schema), должна поддерживаться даже когда разархиватор выполняет обработку XOP.
- Выбрасывает:
-
IllegalStateException- если попытка одновременного вызова этого метода во время операции разархивирования.
getAttachmentUnmarshaller
AttachmentUnmarshaller getAttachmentUnmarshaller()
setListener
void setListener(Unmarshaller.Listener listener)
Регистрирует обратный вызов события разархивирования Unmarshaller.Listener с данным Unmarshaller.
На один разархиватор может быть зарегистрирован только один слушатель. Установка слушателя заменяет ранее установленного. Можно отменить регистрацию текущего слушателя, установив слушателя в null.
- Параметры:
-
listener- предоставляет обратные вызовы событий разархивирования для данногоUnmarshaller - С:
- JAXB2.0
getListener
Unmarshaller.Listener getListener()
Возвращает зарегистрированный Unmarshaller.Listener с этим Unmarshaller.
- Возвращает:
- зарегистрированный
Unmarshaller.Listenerилиnullесли с этим разархиватором не зарегистрирован ни один слушатель. - С:
- JAXB2.0
© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.