Интерфейс Marshaller

Класс Marshaller отвечает за управление процессом сериализации деревьев Java-содержимого обратно в XML-данные. Он предоставляет базовые методы маршаллирования:

Предполагается следующий код настройки для всех последующих фрагментов кода:

JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
Object element = u.unmarshal( new File( "foo.xml" ) );
Marshaller m = jc.createMarshaller();

Маршаллирование в файл:

OutputStream os = new FileOutputStream( "nosferatu.xml" );
m.marshal( element, os );

Маршаллирование в SAX ContentHandler:

// assume MyContentHandler instanceof ContentHandler
m.marshal( element, new MyContentHandler() );

Маршаллирование в DOM Node:

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.newDocument();

m.marshal( element, doc );

Маршаллирование в java.io.OutputStream:

m.marshal( element, System.out );

Маршаллирование в java.io.Writer:

m.marshal( element, new PrintWriter( System.out ) );

Маршаллирование в javax.xml.transform.SAXResult:

// assume MyContentHandler instanceof ContentHandler
SAXResult result = new SAXResult( new MyContentHandler() );

m.marshal( element, result );

Маршаллирование в javax.xml.transform.DOMResult:

DOMResult result = new DOMResult();

m.marshal( element, result );

Маршаллирование в javax.xml.transform.StreamResult:

StreamResult result = new StreamResult( System.out );

m.marshal( element, result );

Маршаллирование в javax.xml.stream.XMLStreamWriter:

XMLStreamWriter xmlStreamWriter =
    XMLOutputFactory.newInstance().createXMLStreamWriter( ... );

m.marshal( element, xmlStreamWriter );

Маршаллирование в javax.xml.stream.XMLEventWriter:

XMLEventWriter xmlEventWriter =
    XMLOutputFactory.newInstance().createXMLEventWriter( ... );

m.marshal( element, xmlEventWriter );

Маршаллирование дерева содержимого, укоренённого в элементе JAXB

The first parameter of the overloaded Marshaller.marshal(java.lang.Object, ...) methods must be a JAXB element as computed by JAXBIntrospector.isElement(java.lang.Object); otherwise, a Marshaller.marshal method must throw a MarshalException. There exist two mechanisms to enable marshalling an instance that is not a JAXB element. One method is to wrap the instance as a value of a JAXBElement, and pass the wrapper element as the first parameter to a Marshaller.marshal method. For java to schema binding, it is also possible to simply annotate the instance's class with @XmlRootElement.

Кодировка

By default, the Marshaller will use UTF-8 encoding when generating XML data to a java.io.OutputStream, or a java.io.Writer. Use the setProperty API to change the output encoding used during these marshal operations. Client applications are expected to supply a valid character encoding name as defined in the W3C XML 1.0 Recommendation and supported by your Java Platform.

Валидация и корректность

Приложениям-клиентам не требуется валидировать дерево Java-содержимого перед вызовом API маршаллирования. Кроме того, нет требования, чтобы дерево Java-содержимого было валидным относительно исходной схемы, чтобы маршаллировать его обратно в XML-данные. Различные поставщики JAXB поддерживают маршаллирование невалидных деревьев Java-содержимого на разных уровнях, однако все поставщики JAXB должны уметь маршаллировать валидное дерево содержимого обратно в XML-данные. Поставщик JAXB должен бросить исключение MarshalException при невозможности завершить операцию маршаллирования из-за невалидного содержимого. Некоторые поставщики JAXB полностью разрешают маршаллирование невалидного содержимого, другие откажутся при первой ошибке валидации.

Даже когда валидация схемы не явно включена для операции маршаллирования, возможно, что некоторые типы событий валидации будут обнаружены во время операции. События валидации будут сообщены зарегистрированному обработчику событий. Если приложение-клиент не зарегистрировало обработчик событий перед вызовом одного из API маршаллирования, то события будут переданы в обработчик по умолчанию, который завершит операцию маршаллирования после обнаружения первой ошибки или критической ошибки. Обратите внимание, что для JAXB 2.0 и более поздних версий, DefaultValidationEventHandler больше не используется.

Поддерживаемые свойства

Все поставщики JAXB обязаны поддерживать следующий набор свойств. Некоторые поставщики могут поддерживать дополнительные свойства.

jaxb.encoding - значение должно быть java.lang.String

Кодировка вывода для использования при маршаллировании XML-данных. Маршаллировщик по умолчанию будет использовать "UTF-8", если это свойство не указано.

jaxb.formatted.output - значение должно быть java.lang.Boolean

Это свойство контролирует, будет ли маршаллировщик форматировать результирующие XML-данные с разрывами строк и отступами. Значение true для этого свойства указывает удобочитаемые отформатированные XML-данные, а значение false - неформатированные XML-данные. Маршаллировщик по умолчанию будет использовать false (неформатированный) если это свойство не указано.

jaxb.schemaLocation - значение должно быть java.lang.String

Это свойство позволяет приложению-клиенту указать атрибут xsi:schemaLocation в генерируемых XML-данных. Формат значения атрибута schemaLocation обсуждается в понятной, ненормативной форме в Разделе 5.6 W3C XML Schema Part 0: Primer и указан в Разделе 2.6 W3C XML Schema Part 1: Structures.

jaxb.noNamespaceSchemaLocation - значение должно быть java.lang.String

Это свойство позволяет приложению-клиенту указать атрибут xsi:noNamespaceSchemaLocation в генерируемых XML-данных. Формат значения атрибута schemaLocation обсуждается в понятной, ненормативной форме в Разделе 5.6 W3C XML Schema Part 0: Primer и указан в Разделе 2.6 W3C XML Schema Part 1: Structures.

jaxb.fragment - значение должно быть java.lang.Boolean

Это свойство определяет, будут ли генерироваться события уровня документа маршаллировщиком. Если свойство не указано, значение по умолчанию false. Это свойство имеет разные последствия в зависимости от используемого API маршаллирования - когда это свойство установлено в true:

• marshal(Object,ContentHandler) - маршаллировщик не вызовет ContentHandler.startDocument() и ContentHandler.endDocument().
• marshal(Object,Node) - свойство не влияет на этот API.
• marshal(Object,OutputStream) - маршаллировщик не сгенерирует объявление XML.
• marshal(Object,Writer) - маршаллировщик не сгенерирует объявление XML.
• marshal(Object,Result) - зависит от типа объекта Result, см. семантику для Node, ContentHandler и Stream API
• marshal(Object,XMLEventWriter) - маршаллировщик не сгенерирует события XMLStreamConstants.START_DOCUMENT и XMLStreamConstants.END_DOCUMENT.
• marshal(Object,XMLStreamWriter) - маршаллировщик не сгенерирует события XMLStreamConstants.START_DOCUMENT и XMLStreamConstants.END_DOCUMENT.

Обратные вызовы событий маршаллирования

"Интерфейс Marshaller предоставляет два типа механизмов обратных вызовов, которые позволяют обработку, специфичную для приложения, в ключевые моменты процесса маршаллирования. В обратных вызовах, определяемых классом, код приложения, размещённый в отображаемых JAXB классах, запускается во время маршаллирования. 'Внешние слушатели' позволяют централизованную обработку событий маршаллирования в одном методе обратного вызова вместо обратных вызовов событий по типу.

Методы обратного вызова событий, определяемые классом, позволяют любому отображаемому классу JAXB указать свои собственные методы обратного вызова, определяя методы со следующими сигнатурами:

// Invoked by Marshaller after it has created an instance of this object.
boolean beforeMarshal(Marshaller);

// Invoked by Marshaller after it has marshalled all properties of this object.
void afterMarshal(Marshaller);

Методы обратного вызова событий, определяемые классом, должны использоваться, когда метод обратного вызова требует доступа к закрытым методам и/или полям класса.

Механизм обратного вызова внешних слушателей позволяет зарегистрировать экземпляр Marshaller.Listener с помощью setListener(Listener). Внешний слушатель получает все события обратного вызова, что позволяет более централизованную обработку, чем методы обратного вызова по каждому классу.

Методы обратного вызова 'определяемые классом' и внешние слушатели независимы друг от друга, оба могут вызываться для одного события. Порядок вызова, когда оба метода обратного вызова существуют, определен в Marshaller.Listener.beforeMarshal(Object) и Marshaller.Listener.afterMarshal(Object).

Метод обратного вызова, выбрасывающий исключение, завершает текущий процесс маршаллирования.

Поля

JAXB_ENCODING

static final String JAXB_ENCODING

Имя свойства, используемого для указания кодировки вывода в маршализованных данных XML.

См. также:

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

JAXB_FORMATTED_OUTPUT

static final String JAXB_FORMATTED_OUTPUT

Имя свойства, используемого для указания форматирования маршализованных данных XML с помощью символов новой строки и отступов.

См. также:

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

JAXB_SCHEMA_LOCATION

static final String JAXB_SCHEMA_LOCATION

Имя свойства, используемого для указания значения атрибута xsi:schemaLocation для размещения в выходных маршализованных данных XML.

См. также:

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

JAXB_NO_NAMESPACE_SCHEMA_LOCATION

static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION

Имя свойства, используемого для указания значения атрибута xsi:noNamespaceSchemaLocation для размещения в выходных маршализованных данных XML.

См. также:

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

JAXB_FRAGMENT

static final String JAXB_FRAGMENT

Имя свойства, используемого для указания того, генерирует ли маршализующий компонент события уровня документа (т.е. вызывает startDocument или endDocument).

См. также:

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

Методы

marshal

void marshal(Object jaxbElement,
             Result result)
      throws JAXBException

Параметры:

jaxbElement - Корень дерева содержимого, подлежащего маршализации.

result - XML будет отправлен в этот Result

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать obj (или любой объект, доступный из obj). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

marshal

void marshal(Object jaxbElement,
             OutputStream os)
      throws JAXBException

Маршализует дерево содержимого, укорененное в jaxbElement, в поток вывода.

Параметры:

jaxbElement - Корень дерева содержимого, подлежащего маршализации.

os - XML будет добавлен в этот поток.

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать obj (или любой объект, доступный из obj). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

marshal

void marshal(Object jaxbElement,
             File output)
      throws JAXBException

Маршализует дерево содержимого, укорененное в jaxbElement, в файл.

Параметры:

jaxbElement - Корень дерева содержимого, подлежащего маршализации.

output - Файл для записи. Если этот файл уже существует, он будет перезаписан.

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать obj (или любой объект, доступный из obj). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

C момента:

JAXB2.1

marshal

void marshal(Object jaxbElement,
             Writer writer)
      throws JAXBException

Маршализует дерево содержимого, укорененное в jaxbElement, в Writer.

Параметры:

jaxbElement - Корень дерева содержимого, подлежащего маршализации.

writer - XML будет отправлен в этот writer.

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать obj (или любой объект, доступный из obj). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

marshal

void marshal(Object jaxbElement,
             ContentHandler handler)
      throws JAXBException

Маршализует дерево содержимого, укорененное в jaxbElement, в события SAX2.

Параметры:

jaxbElement - Корень дерева содержимого, подлежащего маршализации.

handler - XML будет отправлен в этот обработчик в виде событий SAX2.

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать obj (или любой объект, доступный из obj). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

marshal

void marshal(Object jaxbElement,
             Node node)
      throws JAXBException

Маршализует дерево содержимого, укорененное в jaxbElement, в дерево DOM.

Параметры:

jaxbElement - Дерево содержимого, подлежащее маршализации.

node - Узлы DOM будут добавлены в качестве потомков этого узла. Этот параметр должен быть узлом, который принимает потомков (Document, DocumentFragment или Element)

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать jaxbElement (или любой объект, доступный из jaxbElement). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

marshal

void marshal(Object jaxbElement,
             XMLStreamWriter writer)
      throws JAXBException

Маршализует дерево содержимого, укорененное в jaxbElement, в XMLStreamWriter.

Параметры:

jaxbElement - Дерево содержимого, подлежащее маршализации.

writer - XML будет отправлен в этот writer.

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать obj (или любой объект, доступный из obj). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

C момента:

JAXB 2.0

marshal

void marshal(Object jaxbElement,
             XMLEventWriter writer)
      throws JAXBException

Маршализует дерево содержимого, укорененное в jaxbElement, в XMLEventWriter.

Параметры:

jaxbElement - Дерево содержимого, укорененное в jaxbElement, подлежащее маршализации.

writer - XML будет отправлен в этот writer.

Исключение:

JAXBException - Если возникнет непредвиденная проблема во время маршализации.

MarshalException - Если ValidationEventHandler возвращает false из своего метода handleEvent или Marshaller не может маршализовать obj (или любой объект, доступный из obj). См. Маршализация элемента JAXB.

IllegalArgumentException - Если какой-либо из параметров метода равен null

C момента:

JAXB 2.0

getNode

Node getNode(Object contentTree)
      throws JAXBException

Получить представление дерева DOM дерева содержимого (необязательно). Если возвращаемое дерево DOM обновляется, эти изменения также видны в дереве содержимого. Используйте marshal(Object, org.w3c.dom.Node) для принудительного создания глубокой копии дерева содержимого в представлении DOM.

Параметры:

contentTree - - Представление JAXB Java XML содержимого

Возвращает:

представление дерева DOM дерева содержимого

Исключение:

UnsupportedOperationException - Если реализация поставщика JAXB не поддерживает представление дерева содержимого в виде DOM

IllegalArgumentException - Если какой-либо из параметров метода равен null

JAXBException - Если возникнет непредвиденная проблема

setProperty

void setProperty(String name,
                 Object value)
          throws PropertyException

Установить определенное свойство в базовой реализации Marshaller. Этот метод может использоваться только для установки одного из стандартных свойств JAXB или свойства, специфичного для поставщика. Попытка установить неопределенное свойство приведет к выбросу исключения PropertyException. См. Поддерживаемые свойства.

Параметры:

name - имя свойства, которое нужно установить. Это значение может быть задано с помощью одного из постоянных полей или строки, введённой пользователем.

value - значение свойства, которое нужно установить

Исключения:

PropertyException - при возникновении ошибки при обработке заданного свойства или значения

IllegalArgumentException - если параметр name имеет значение null

getProperty

Object getProperty(String name)
            throws PropertyException

Получить определённое свойство в базовой реализации Marshaller. Этот метод можно использовать только для получения одного из стандартных свойств, определённых JAXB, или свойства, специфичного для поставщика. Попытка получить неопределённое свойство приведёт к тому, что будет брошено исключение PropertyException. См. Поддерживаемые свойства.

Параметры:

name - имя свойства, которое нужно получить

Возвращает:

значение запрашиваемого свойства

Исключения:

PropertyException - при возникновении ошибки при получении заданного свойства или значения имени свойства

IllegalArgumentException - если параметр name имеет значение null

setEventHandler

void setEventHandler(ValidationEventHandler handler)
              throws JAXBException

Параметры:

handler - обработчик событий валидации

Исключения:

JAXBException - если при установке обработчика событий возникла ошибка

getEventHandler

ValidationEventHandler getEventHandler()
                                throws JAXBException

Возвращает текущий обработчик событий или обработчик событий по умолчанию, если он не был установлен.

Возвращает:

текущий ValidationEventHandler или обработчик событий по умолчанию, если он не был установлен

Исключения:

JAXBException - если при получении текущего обработчика событий возникла ошибка

setAdapter

void setAdapter(XmlAdapter adapter)

Исключения:

IllegalArgumentException - если параметр adapter имеет значение null.

UnsupportedOperationException - если вызов осуществляется в реализации JAXB 1.0.

С:

JAXB 2.0

См. также:

setAdapter(Class,XmlAdapter)

setAdapter

<A extends XmlAdapter> void setAdapter(Class<A> type,
                                       A adapter)

Параметры:

type - тип адаптера. Указанный экземпляр будет использован, когда XmlJavaTypeAdapter.value() ссылается на этот тип.

adapter - экземпляр адаптера, который будет использоваться. Если null, то текущий адаптер для этого типа будет дерегистрирован.

Исключения:

IllegalArgumentException - если параметр type имеет значение null.

UnsupportedOperationException - если вызов осуществляется в реализации JAXB 1.0.

С:

JAXB 2.0

getAdapter

<A extends XmlAdapter> A getAdapter(Class<A> type)

Получает адаптер, связанный с указанным типом. Это обратная операция метода setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter).

Исключения:

IllegalArgumentException - если параметр type имеет значение null.

UnsupportedOperationException - если вызов осуществляется в реализации JAXB 1.0.

С:

JAXB 2.0

setAttachmentMarshaller

void setAttachmentMarshaller(AttachmentMarshaller am)

Исключения:

IllegalStateException - если попытка вызвать этот метод происходит во время операции маршализации.

getAttachmentMarshaller

AttachmentMarshaller getAttachmentMarshaller()

setSchema

void setSchema(Schema schema)

Параметры:

schema - Объект схемы для валидации операций маршализации или null для отключения валидации

Исключения:

UnsupportedOperationException - может быть вызвано, если этот метод вызывается в маршализующем объекте, созданном из JAXBContext, ссылающемся на классы, сопоставленные с JAXB 1.0

С:

JAXB2.0

getSchema

Schema getSchema()

Получить объект JAXP 1.3 Schema, используемый для проверки маршализации. Если для маршализующего объекта не установлена схема, то этот метод вернёт null, что указывает на то, что проверка маршализации не будет выполнена.

Возвращает:

объект схемы, используемый для проверки маршализации, или null, если он отсутствует.

Исключения:

UnsupportedOperationException - может быть вызвано, если этот метод вызывается в маршализующем объекте, созданном из JAXBContext, ссылающемся на классы, сопоставленные с JAXB 1.0

С:

JAXB2.0

setListener

void setListener(Marshaller.Listener listener)

Параметры:

listener - экземпляр класса, реализующего Marshaller.Listener

С:

JAXB2.0

getListener

Marshaller.Listener getListener()

Возвращает:

зарегистрированный Marshaller.Listener или null если с этим маршализующим объектом не зарегистрирован обработчик событий.

С:

JAXB2.0