Marshaller class ответственен за управление процессом сериализации деревьев контента 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() );
Маршалинг дерева контента базировался элементом JAXB
Первый параметр перегруженных методов Marshaller.marshal(java.lang.Object, ...) должен быть элементом JAXB как вычислено JAXBIntrospector#isElement(java.lang.Object); иначе, метод Marshaller.marshal должен бросить a MarshalException. Там существуйте два механизма, чтобы позволить упорядочить экземпляр, который не является элементом JAXB. Один метод должен обернуть экземпляр как значение a JAXBElement, и передайте элемент обертки как первый параметр к методу Marshaller.marshal. Для java к привязке схемы также возможно просто аннотировать class экземпляраXmlRootElement.
Кодирование
По умолчанию Marshaller будет использовать кодирование UTF-8, генерируя данные XML к java.io.OutputStream, или java.io.Writer. Используйте setProperty API, чтобы изменить выходное кодирование, используемое во время них, упорядочивает операции. Клиентские приложения, как ожидают, предоставят допустимое имя кодировки символов как определено в XML 1.0 W3C Рекомендация и поддерживаются Вашей Платформой Java.
Проверка допустимости и Отмеченность
Клиентские приложения не обязаны проверять дерева контента Java до вызова любого упорядочивать API. Кроме того нет никакого требования, что дерево контента Java быть допустимым относительно его исходной схемы, чтобы упорядочить его назад в данные XML. Различные Провайдеры JAXB будут поддерживать упорядочивающие недопустимые деревья контента Java на переменных уровнях, однако все Провайдеры JAXB должны быть в состоянии упорядочить допустимое дерево контента назад к данным XML. Провайдер JAXB должен бросить MarshalException, когда это неспособно завершить упорядочивать работу из-за недопустимого контента. Некоторые Провайдеры JAXB полностью позволят упорядочивать недопустимый контент, другие перестанут работать на первой ошибке проверки допустимости.
Даже когда проверка допустимости схемы не является explictly, включенным для упорядочивать работы, возможно, что определенные типы событий проверки допустимости будут обнаружены во время работы. О событиях проверки допустимости сообщат зарегистрированному обработчику событий. Если клиентское приложение не зарегистрировало обработчик событий до вызова одного из упорядочивать API, то события будут поставлены обработчику стандартного события, который завершит упорядочивать работу после обнаружения с первой ошибкой или фатальной ошибкой. Отметьте это JAXB 2.0 и более поздними версиями, DefaultValidationEventHandler больше не используется.
Поддерживаемые Свойства
Все Провайдеры JAXB обязаны поддерживать следующий набор свойств. Некоторые провайдеры могут поддерживать дополнительные свойства.
jaxb.encoding - значение должно быть java.lang. Строка
Выходное кодирование, чтобы использовать, упорядочивая данные XML. Marshaller будет использовать "UTF-8" по умолчанию, если это свойство не будет определено.
jaxb.formatted.output - значение должно быть java.lang. Булев
Это свойство управляет, отформатирует ли Marshaller получающиеся данные XML с разрывами строки и добавлением отступа. Истинное значение для этого свойства указывает удобочитаемый, располагал xml данные с отступом, в то время как ложное значение указывает на восстановленные после форматирования xml данные. Marshaller примет значение по умолчанию ко лжи (восстановленной после форматирования), если это свойство не будет определено.
jaxb.schemaLocation - значение должно быть java.lang. Строка
jaxb.fragment - значение должно быть java.lang. Булев
Это свойство определяет, будут ли события уровня документа сгенерированы Marshaller. Если свойство не определяется, значением по умолчанию является false. У этого свойства есть различные импликации, в зависимости от которых упорядочивают api, который Вы используете - когда это свойство устанавливается в истину:
marshal(Object,ContentHandler) - Marshaller не будет вызывать ContentHandler.startDocument() и ContentHandler.endDocument().
marshal(Object,Result) - зависит от вида объекта Результата, см. семантику для Узла, ContentHandler, и Потоковых API
marshal(Object,XMLEventWriter) - Marshaller не будет генерировать XMLStreamConstants.START_DOCUMENT и XMLStreamConstants.END_DOCUMENT события.
marshal(Object,XMLStreamWriter) - Marshaller не будет генерировать XMLStreamConstants.START_DOCUMENT и XMLStreamConstants.END_DOCUMENT события.
Упорядочьте Обратные вызовы События
" Marshaller обеспечивает два стиля механизмов обратного вызова, которые позволяют специализированную обработку во время ключевых пунктов в процессе немаршалинга. В обратных вызовах события 'class defined' специализированный код, помещенный в JAXB отображенные классы, инициирован во время маршалинга. 'Внешние слушатели' учитывают централизованную обработку, упорядочивают события в одном методе обратного вызова, а не обратными вызовами события типа.
Класс определенные методы обратного вызова события позволяет любому JAXB отображенный class, чтобы определить его собственные определенные методы обратного вызова, определяя методы с помощью следующих сигнатур методов:
// 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 afterMmarshal(Marshaller);
Определенные методы обратного вызова события class должны использоваться, когда метод обратного вызова требует доступа к непубличным методам и/или полям class.
Внешний механизм обратного вызова слушателя включает регистрации a Marshaller.Listener экземпляр с a Marshaller#setListener(Listener). Внешний слушатель получает все события обратного вызова, учитывая более централизованную обработку чем на class определенные методы обратного вызова.
Метод обратного вызова события, выдающий исключение, завершается, ток упорядочивают процесс.
С тех пор:
JAXB1.0
Автор:
Kohsuke Кавагути, Sun Microsystems, Inc.
Райан Шоемэкер, Sun Microsystems, Inc.
Джо Фьалли, Sun Microsystems, Inc.
См. Также:
JAXBContext, Validator, Unmarshaller
Вложенная Сводка Класса
static class
Marshaller. Слушатель Зарегистрируйте экземпляр реализации этого class с a Marshaller чтобы внешне прислушаться упорядочивают события.
Полевая Сводка
static java.lang.String
JAXB_ENCODING Имя свойства, используемого, чтобы определить выходное кодирование в упорядоченных данных XML.
static java.lang.String
JAXB_FORMATTED_OUTPUT Имя свойства, используемого, чтобы определить, форматируются ли упорядоченные данные XML с переводами строки и добавлением отступа.
static java.lang.String
JAXB_FRAGMENT Имя свойства, используемого, чтобы определить, генерирует ли marshaller события уровня документа (то есть вызывающий startDocument или endDocument).
static java.lang.String
JAXB_NO_NAMESPACE_SCHEMA_LOCATION Имя свойства, используемого, чтобы определить xsi:noNamespaceSchemaLocation значение атрибута, чтобы поместить в упорядоченный вывод XML.
static java.lang.String
JAXB_SCHEMA_LOCATION Имя свойства, используемого, чтобы определить xsi:schemaLocation значение атрибута, чтобы поместить в упорядоченный вывод XML.
marshal(java.lang.Object jaxbElement, org.xml.sax.ContentHandler handler) Упорядочьте дерево контента, базированное в событиях jaxbElement into SAX2.
void
marshal(java.lang.Object jaxbElement, java.io.File output) Упорядочьте дерево контента, базированное в jaxbElement в файл.
void
marshal(java.lang.Object jaxbElement, org.w3c.dom.Node node) Упорядочьте дерево контента, базированное в jaxbElement в дерево ДОМА.
void
marshal(java.lang.Object jaxbElement, java.io.OutputStream os) Упорядочьте дерево контента, базированное в jaxbElement в поток вывода.
void
marshal(java.lang.Object jaxbElement, javax.xml.transform.Result result) Упорядочьте дерево контента, базированное в jaxbElement в указанный javax.xml.transform.Result.
void
marshal(java.lang.Object jaxbElement, java.io.Writer writer) Упорядочьте дерево контента, базированное в jaxbElement в Писателя.
void
marshal(java.lang.Object jaxbElement, javax.xml.stream.XMLEventWriter writer) Упорядочьте дерево контента, базированное в jaxbElement в a XMLEventWriter.
void
marshal(java.lang.Object jaxbElement, javax.xml.stream.XMLStreamWriter writer) Упорядочьте дерево контента, базированное в jaxbElement в a XMLStreamWriter.
setAdapter(java.lang.Class<A> type, A adapter) Связывает сконфигурированный экземпляр XmlAdapter с этим marshaller.
void
setAdapter(XmlAdapter adapter) Связывает сконфигурированный экземпляр XmlAdapter с этим marshaller.
void
setAttachmentMarshaller(AttachmentMarshaller am) Свяжите контекст, который позволяет двоичным данным в пределах XML-документа быть переданными как двоичный файл XML оптимизированное присоединение.
setProperty(java.lang.String name, java.lang.Object value) Установите определенное свойство в базовой реализации Marshaller.
void
setSchema(javax.xml.validation.Schema schema) Определите JAXP 1.3 Schema объект, который должен использоваться, чтобы проверить последующий, упорядочивает операции против.
Полевая Деталь
JAXB_ENCODING
static final java.lang.String JAXB_ENCODING
Имя свойства, используемого, чтобы определить выходное кодирование в упорядоченных данных XML.
Упорядочьте дерево контента, базированное в jaxbElement в указанный javax.xml.transform.Result.
Все Провайдеры JAXB должны, по крайней мере, поддерживать DOMResult, SAXResult, и StreamResult. Это может поддерживать другие производные классы Result также.
Параметры:
jaxbElement - Корень дерева контента, которое будет упорядочено.
result - XML будет отправлен этому Результату
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить obj (или любой объект, достижимый от obj). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Упорядочьте дерево контента, базированное в jaxbElement в поток вывода.
Параметры:
jaxbElement - Корень дерева контента, которое будет упорядочено.
os - XML будет добавлен к этому потоку.
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить obj (или любой объект, достижимый от obj). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Упорядочьте дерево контента, базированное в jaxbElement в файл.
Параметры:
jaxbElement - Корень дерева контента, которое будет упорядочено.
output - Файл, который будет записан. Если этот файл уже будет существовать, то он будет перезаписан.
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить obj (или любой объект, достижимый от obj). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Упорядочьте дерево контента, базированное в jaxbElement в Писателя.
Параметры:
jaxbElement - Корень дерева контента, которое будет упорядочено.
writer - XML будет отправлен этому писателю.
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить obj (или любой объект, достижимый от obj). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Упорядочьте дерево контента, базированное в событиях jaxbElement into SAX2.
Параметры:
jaxbElement - Корень дерева контента, которое будет упорядочено.
handler - XML будет отправлен этому обработчику как события SAX2.
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить obj (или любой объект, достижимый от obj). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Упорядочьте дерево контента, базированное в jaxbElement в дерево ДОМА.
Параметры:
jaxbElement - Дерево контента, которое будет упорядочено.
node - Узлы ДОМА будут добавлены как дочерние элементы этого узла. Этим параметром должен быть Узел, который принимает дочерние элементы (Document, DocumentFragment, или Element)
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить jaxbElement (или любой объект, достижимый от jaxbElement). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Упорядочьте дерево контента, базированное в jaxbElement в a XMLStreamWriter.
Параметры:
jaxbElement - Дерево контента, которое будет упорядочено.
writer - XML будет отправлен этому писателю.
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить obj (или любой объект, достижимый от obj). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Упорядочьте дерево контента, базированное в jaxbElement в a XMLEventWriter.
Параметры:
jaxbElement - Дерево контента базировалось в jaxbElement, который будет упорядочен.
writer - XML будет отправлен этому писателю.
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
MarshalException - Если ValidationEventHandler возвращает false от его метода handleEvent, или Marshaller неспособен упорядочить obj (или любой объект, достижимый от obj). См. Маршалинг элемента JAXB.
IllegalArgumentException - Если какой-либо из параметров метода является нулем
Получите структурный вид ДОМА (Дополнительного) дерева контента. Если возвращенное дерево ДОМА обновляется, эти изменения также видимы в дереве контента. Использовать marshal(Object, org.w3c.dom.Node) вызвать глубокую копию дерева контента к представлению ДОМА.
Параметры:
contentTree - Представление Java JAXB контента XML
Возвраты:
структурный вид ДОМА contentTree
Броски:
UnsupportedOperationException - Если реализация провайдера JAXB не поддерживает представление ДОМА дерева контента
IllegalArgumentException - Если какой-либо из параметров метода является нулем
JAXBException - Если какая-либо неожиданная проблема происходит
Установите определенное свойство в базовой реализации Marshaller. Этот метод может только использоваться, чтобы установить один из стандартных JAXB определенные свойства выше или провайдер определенное свойство. Попытка установить неопределенное свойство приведет к бросаемому PropertyException. См. Поддерживаемые Свойства.
Параметры:
name - имя свойства, которое будет установлено. Это значение может или быть определено, используя одно из постоянных полей или пользователя предоставленная строка.
value - значение свойства, которое будет установлено
Броски:
PropertyException - когда есть ошибка, обрабатывая данное свойство или значение
IllegalArgumentException - Если параметр имени является нулем
Получите определенное свойство в базовой реализации Marshaller. Этот метод может только использоваться, чтобы получить один из стандартных JAXB определенные свойства выше или провайдер определенное свойство. Попытка получить неопределенное свойство приведет к бросаемому PropertyException. См. Поддерживаемые Свойства.
Параметры:
name - имя свойства, чтобы получить
Возвраты:
значение требуемого свойства
Броски:
PropertyException - когда есть ошибка, получая данное свойство или имя свойства значения
IllegalArgumentException - Если параметр имени является нулем
Позвольте приложению регистрировать обработчик событий проверки допустимости.
Обработчик событий проверки допустимости вызовет Провайдер JAXB, если с какими-либо ошибками проверки допустимости встретятся во время звонков в какой-либо упорядочивать API. Если клиентское приложение не зарегистрирует обработчик событий проверки допустимости прежде, чем вызвать один из упорядочивать методов, то события проверки допустимости будут обработаны обработчиком стандартного события, который завершит упорядочивать работу после первой ошибки, или с фатальной ошибкой встречаются.
Вызов этого метода с нулевым параметром заставит Marshaller возвращаться назад к обработчику стандартного события значения по умолчанию.
Параметры:
handler - обработчик событий проверки допустимости
Броски:
JAXBException - если с ошибкой встретились, устанавливая обработчик событий
<A extends XmlAdapter> void setAdapter(java.lang.Class<A> type,
A adapter)
Связывает сконфигурированный экземпляр XmlAdapter с этим marshaller.
Каждый marshaller внутренне поддерживает a Map<Class,XmlAdapter>, который это использует для того, чтобы упорядочить классы, поля/методы которых аннотируются XmlJavaTypeAdapter.
Этот метод позволяет приложениям использовать сконфигурированный экземпляр XmlAdapter. Когда пример адаптера не будет приведен, marshaller создаст один, вызывая его конструктора по умолчанию.
Параметры:
type - Тип адаптера. Указанный экземпляр будет использоваться когда XmlJavaTypeAdapter.value() обращается к этому типу.
adapter - Экземпляр адаптера, который будет использоваться. Если ноль, это незарегистрирует текущий набор адаптера для этого типа.
Броски:
IllegalArgumentException - если параметр типа является нулем.
UnsupportedOperationException - если вызвано agains JAXB 1.0 реализации.
С тех пор:
JAXB 2.0
getAdapter
<A extends XmlAdapter> A getAdapter(java.lang.Class<A> type)
Свяжите контекст, который позволяет двоичным данным в пределах XML-документа быть переданными как двоичный файл XML оптимизированное присоединение. На присоединение ссылаются от модели контента XML-документа URI идентификатора контента (уголовный розыск) ссылки, сохраненные в пределах xml документа.
Броски:
IllegalStateException - если попытка одновременно вызвать этот метод во время упорядочивать работы.
Определите JAXP 1.3 Schema объект, который должен использоваться, чтобы проверить последующий, упорядочивает операции против. Передача нуля в этот метод отключит проверку допустимости.
Этот метод позволяет вызывающей стороне проверять упорядоченного XML, поскольку это упорядочивается.
Первоначально это свойство устанавливается в null.
Параметры:
schema - Объект схемы проверить упорядочивает операции против или нуль, чтобы отключить проверку допустимости
Броски:
UnsupportedOperationException - мог быть брошен, если этот метод вызывается на Marshaller, создаваемый из JAXBContext, ссылающегося на JAXB 1.0 отображенных класса
С тех пор:
JAXB2.0
getSchema
javax.xml.validation.Schema getSchema()
Получите JAXP 1.3 Schema объект, используемый, чтобы выполнить, упорядочивает разовую проверку допустимости. Если не будет никакого набора Схемы на marshaller, то этот метод возвратит нуль, указывающий, которые упорядочивают разовую проверку допустимости, не будет выполняться.
Возвраты:
объект Схемы, используемый, чтобы выполнить, упорядочивает разовую проверку допустимости или нуль если не существующий.
Броски:
UnsupportedOperationException - мог быть брошен, если этот метод вызывается на Marshaller, создаваемый из JAXBContext, ссылающегося на JAXB 1.0 отображенных класса
Регистр упорядочивает обратный вызов события Marshaller.Listener с этим Marshaller.
Есть только один Слушатель на Marshaller. Установка Слушателя заменяет предыдущего Слушателя набора. Можно незарегистрировать текущего Слушателя, устанавливая слушателя null.