Пожалуйста, учтите, что спецификации и другая информация, содержащаяся здесь, не являются заключительными и могут быть изменены. Информация доступна для вас исключительно ради ознакомления.
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, который Вы используете - когда это свойство устанавливается в истину:
" 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 setListener(Listener). Внешний слушатель получает все события обратного вызова, учитывая более централизованную обработку чем на class определенные методы обратного вызова.
Упорядочьте дерево контента, базированное в jaxbElement в указанный javax.xml.transform.Result.
Все Провайдеры JAXB должны, по крайней мере, поддерживать DOMResult, SAXResult, и StreamResult. Это может поддерживать другие производные классы Result также.
Параметры:
jaxbElement - Корень дерева контента, которое будет упорядочено.
result - XML будет отправлен этому Результату
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
Упорядочьте дерево контента, базированное в jaxbElement в дерево ДОМА.
Параметры:
jaxbElement - Дерево контента, которое будет упорядочено.
node - Узлы ДОМА будут добавлены как дочерние элементы этого узла. Этим параметром должен быть Узел, который принимает дочерние элементы (Document, DocumentFragment, или Element)
Броски:
JAXBException - Если какая-либо неожиданная проблема происходит во время маршалинга.
Получите структурный вид ДОМА (Дополнительного) дерева контента. Если возвращенное дерево ДОМА обновляется, эти изменения также видимы в дереве контента. Использовать marshal(Object, org.w3c.dom.Node) вызвать глубокую копию дерева контента к представлению ДОМА.
Параметры:
contentTree - Представление Java JAXB контента XML
Установите определенное свойство в базовой реализации Marshaller. Этот метод может только использоваться, чтобы установить один из стандартных JAXB определенные свойства выше или провайдер определенное свойство. Попытка установить неопределенное свойство приведет к бросаемому PropertyException. См. Поддерживаемые Свойства.
Параметры:
name - имя свойства, которое будет установлено. Это значение может или быть определено, используя одно из постоянных полей или пользователя предоставленная строка.
value - значение свойства, которое будет установлено
Броски:
PropertyException - когда есть ошибка, обрабатывая данное свойство или значение
Получите определенное свойство в базовой реализации Marshaller. Этот метод может только использоваться, чтобы получить один из стандартных JAXB определенные свойства выше или провайдер определенное свойство. Попытка получить неопределенное свойство приведет к бросаемому PropertyException. См. Поддерживаемые Свойства.
Параметры:
name - имя свойства, чтобы получить
Возвраты:
значение требуемого свойства
Броски:
PropertyException - когда есть ошибка, получая данное свойство или имя свойства значения
Позвольте приложению регистрировать обработчик событий проверки допустимости.
Обработчик событий проверки допустимости вызовет Провайдер JAXB, если с какими-либо ошибками проверки допустимости встретятся во время звонков в какой-либо упорядочивать API. Если клиентское приложение не зарегистрирует обработчик событий проверки допустимости прежде, чем вызвать один из упорядочивать методов, то события проверки допустимости будут обработаны обработчиком стандартного события, который завершит упорядочивать работу после первой ошибки, или с фатальной ошибкой встречаются.
Вызов этого метода с нулевым параметром заставит Marshaller возвращаться назад к обработчику стандартного события значения по умолчанию.
Параметры:
handler - обработчик событий проверки допустимости
Броски:
JAXBException - если с ошибкой встретились, устанавливая обработчик событий
<A extends XmlAdapter> void setAdapter(Class<A> type,
A adapter)
Связывает сконфигурированный экземпляр XmlAdapter с этим marshaller.
Каждый marshaller внутренне поддерживает a Map<Class,XmlAdapter>, который это использует для того, чтобы упорядочить классы, поля/методы которых аннотируются XmlJavaTypeAdapter.
Этот метод позволяет приложениям использовать сконфигурированный экземпляр XmlAdapter. Когда пример адаптера не будет приведен, marshaller создаст один, вызывая его конструктора по умолчанию.
Параметры:
type - Тип адаптера. Указанный экземпляр будет использоваться когда XmlJavaTypeAdapter.value() обращается к этому типу.
adapter - Экземпляр адаптера, который будет использоваться. Если ноль, это незарегистрирует текущий набор адаптера для этого типа.
Свяжите контекст, который позволяет двоичным данным в пределах XML-документа быть переданными как двоичный файл XML оптимизированное присоединение. На присоединение ссылаются от модели контента XML-документа URI идентификатора контента (уголовный розыск) ссылки, сохраненные в пределах xml документа.
Броски:
IllegalStateException - если попытка одновременно вызвать этот метод во время упорядочивать работы.
Определите JAXP 1.3 Schema объект, который должен использоваться, чтобы проверить последующий, упорядочивает операции против. Передача нуля в этот метод отключит проверку допустимости.
Этот метод позволяет вызывающей стороне проверять упорядоченного XML, поскольку это упорядочивается.
Первоначально это свойство устанавливается в null.
Параметры:
schema - Объект схемы проверить упорядочивает операции против или нуль, чтобы отключить проверку допустимости
Броски:
UnsupportedOperationException - мог быть брошен, если этот метод вызывается на Marshaller, создаваемый из JAXBContext, ссылающегося на JAXB 1.0 отображенных класса
Получите JAXP 1.3 Schema объект, используемый, чтобы выполнить, упорядочивает разовую проверку допустимости. Если не будет никакого набора Схемы на marshaller, то этот метод возвратит нуль, указывающий, которые упорядочивают разовую проверку допустимости, не будет выполняться.
Возвраты:
объект Схемы, используемый, чтобы выполнить, упорядочивает разовую проверку допустимости или нуль если не существующий.
Броски:
UnsupportedOperationException - мог быть брошен, если этот метод вызывается на Marshaller, создаваемый из JAXBContext, ссылающегося на JAXB 1.0 отображенных класса
Есть только один Слушатель на Marshaller. Установка Слушателя заменяет предыдущего Слушателя набора. Можно незарегистрировать текущего Слушателя, устанавливая слушателя null.