Руководство по JAXB

1. введение

Это вводная статья о JAXB (архитектура Java для привязки XML).

Сначала мы покажем, как конвертировать объекты Java в XML и наоборот, а затем сосредоточимся на создании классов Java из XML-схемы и наоборот с помощью плагина JAXB-2 Maven.

2. Обзор

JAXB предоставляет быстрый и удобный способ маршалирования (записи) объектов Java в XML и разбиения (чтения) XML на объекты. Он поддерживает структуру привязки, которая сопоставляет XML-элементы и атрибуты с полями и свойствами Java с помощью аннотаций Java.

Плагин JAXB-2 Maven делегирует большую часть своей работы любому из двух инструментов, поставляемых JDK XJC и Schemagen .

3. Аннотации JAXB

JAXB использует аннотации Java для дополнения созданных классов дополнительной информацией. Добавление таких аннотаций в существующие классы Java подготавливает их к среде выполнения JAXB.

Давайте сначала создадим простой объект Java, чтобы проиллюстрировать сортировку и отмену сортировки:

@XmlRootElement(name = "book")
@XmlType(propOrder = { "id", "name", "date" })
public class Book {
    private Long id;
    private String name;
    private String author;
    private Date date;

    @XmlAttribute
    public void setId(Long id) {
        this.id = id;
    }

    @XmlElement(name = "title")
    public void setName(String name) {
        this.name = name;
    }

    @XmlTransient
    public void setAuthor(String author) {
        this.author = author;
    }
    
    // constructor, getters and setters
}

Приведенный выше класс содержит следующие аннотации:

@XmlRootElement : t имя корневого XML-элемента является производным от имени класса, и мы также можем указать имя корневого элемента XML, используя его атрибут name
@XMLType : определите порядок, в котором поля записываются в XML-файл
@XmlElement : определите фактическое имя XML-элемента, которое будет использоваться
@XmlAttribute : определите, что поле идентификатора отображается как атрибут, а не как элемент
@@XmlTransient : поля аннотаций, которые мы не хотим включать в XML

Для получения более подробной информации об аннотации JAXB вы можете ознакомиться со следующей ссылкой |.

4. Сортировка – Преобразование объекта Java в XML

Маршаллинг предоставляет клиентскому приложению возможность преобразования дерева объектов Java, производного от JAXB, в данные XML. По умолчанию Маршаллер использует кодировку UTF-8 при создании XML-данных. Далее мы сгенерируем XML-файлы из объектов Java.

Давайте создадим простую программу с использованием JAXBContext , которая предоставляет абстракцию для управления информацией о привязке XML/Java, необходимой для реализации операций платформы привязки JAXB:

public void marshal() throws JAXBException, IOException {
    Book book = new Book();
    book.setId(1L);
    book.setName("Book1");
    book.setAuthor("Author1");
    book.setDate(new Date());

    JAXBContext context = JAXBContext.newInstance(Book.class);
    Marshaller mar= context.createMarshaller();
    mar.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    mar.marshal(book, new File("./book.xml"));
}

javax.xml.привязка.Класс JAXBContext предоставляет точку входа клиента в API JAXB. По умолчанию JAXB не форматирует XML-документ. Это экономит место и предотвращает случайную интерпретацию любого пробела как значительного.

Чтобы форматировать выходные данные JAXB, мы просто устанавливаем для свойства Marshaller.JAXB_FORMATTED_OUTPUT значение true в Маршалл . Метод маршала использует объект и выходной файл, в котором в качестве параметров хранится сгенерированный XML.

Когда мы запускаем приведенный выше код, мы можем проверить результат в book.xml чтобы убедиться, что мы успешно преобразуем объект Java в данные XML:



    Book1
    2016-11-12T11:25:12.227+07:00

5. Отмена сортировки – Преобразование XML в объект Java

Несинхронизация предоставляет клиентскому приложению возможность преобразования XML – данных в объекты Java, полученные из JAXB.

Давайте использовать JAXB Унмаршаллер чтобы унмаршал наш book.xml вернуться к объекту Java:

public Book unmarshall() throws JAXBException, IOException {
    JAXBContext context = JAXBContext.newInstance(Book.class);
    return (Book) context.createUnmarshaller()
      .unmarshal(new FileReader("./book.xml"));
}

Когда мы запускаем приведенный выше код, мы можем проверить вывод консоли, чтобы убедиться, что мы успешно преобразовали XML-данные в объект Java:

Book [id=1, name=Book1, author=null, date=Sat Nov 12 11:38:18 ICT 2016]

6. Сложные Типы Данных

При обработке сложных типов данных, которые могут быть недоступны непосредственно в JAXB, мы можем написать адаптер, чтобы указать JAXB, как управлять определенным типом.

Используя JAXB XmlAdapter , мы можем определить пользовательский код для преобразования класса, который невозможно изменить, во что-то, с чем может справиться JAXB. В аннотации @XmlJavaTypeAdapter используется адаптер, который расширяет класс XmlAdapter для пользовательского маршалинга.

Давайте создадим адаптер для указания формата даты при маршалинге:

public class DateAdapter extends XmlAdapter {

    private static final ThreadLocal dateFormat 
      = new ThreadLocal() {

        @Override
        protected DateFormat initialValue() {
            return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        }
    };

    @Override
    public Date unmarshal(String v) throws Exception {
        return dateFormat.get().parse(v);
    }

    @Override
    public String marshal(Date v) throws Exception {
        return dateFormat.get().format(v);
    }
}

Мы используем формат даты ” гггг-ММ-дд ЧЧ:мм:сс ” для преобразования Даты в Строку при сортировке и Локальную , чтобы сделать наш Формат даты потокобезопасным.

Давайте применим Адаптер данных к нашей Книге :

@XmlRootElement(name = "book")
@XmlType(propOrder = { "id", "name", "date" })
public class Book {
    private Long id;
    private String name;
    private String author;
    private Date date;

    @XmlAttribute
    public void setId(Long id) {
        this.id = id;
    }

    @XmlTransient
    public void setAuthor(String author) {
        this.author = author;
    }

    @XmlElement(name = "title")
    public void setName(String name) {
        this.name = name;
    }

    @XmlJavaTypeAdapter(DateAdapter.class)
    public void setDate(Date date) {
        this.date = date;
    }
}

Когда мы запускаем приведенный выше код, мы можем проверить результат в book.xml чтобы убедиться, что мы успешно преобразовали наш объект Java в XML с использованием нового формата даты ” гггг-ММ-дд ЧЧ:мм:сс “:



    Book1
    2016-11-10 23:44:18final

7. Плагин JAXB-2 Maven

Этот плагин использует Java API для привязки XML (JAXB), версия 2+, для создания классов Java из XML-схем (и, возможно, файлов привязки) или для создания XML-схемы из аннотированного класса Java.

Обратите внимание, что существует два основных подхода к созданию веб-сервисов: Последний контракт и Первый контракт . Для получения более подробной информации об этих подходах вы можете ознакомиться со следующей ссылкой |.

7.1. Создание класса Java из XSD

Плагин JAXB-2 Maven использует поставляемый JDK инструмент XJC, инструмент компилятора привязки JAXB, который генерирует классы Java из XSD (определение схемы XML).

Давайте создадим простой файл user.xsd и используем плагин JAXB-2 Maven для создания классов Java из этой схемы XSD:

Давайте настроим плагин Maven JAXB-2:


    org.codehaus.mojo
    jaxb2-maven-plugin
    2.3
    
        
            xjc
            
                xjc
            
        
    
    
        
            src/main/resources/global.xjb
        
        
            src/main/resources/user.xsd
        
        ${basedir}/src/main/java
        false

По умолчанию этот плагин находит XSD-файлы в src/main/xsd . Мы можем настроить поиск XSD, изменив раздел конфигурации этого плагина в pom.xml соответственно.

По умолчанию эти классы Java создаются в папке target/generated-resources/jaxb . Мы можем изменить выходной каталог, добавив элемент выходной каталог в конфигурацию плагина. Мы также можем добавить элемент clearOutputDir со значением false, чтобы предотвратить удаление файлов в этом каталоге.

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

global.xjb выше переопределяет тип DateTime для java.util.Календарь тип.
Когда мы создаем проект, он генерирует файлы классов в папке src/main/java
и пакете com.baeldung.jaxb.gen
.

7.2. Создание схемы XSD из Java

Тот же плагин использует инструмент, поставляемый JDK Schemagen . Это инструмент компилятора привязки JAXB, который может генерировать схему XSD из классов Java. Чтобы класс Java соответствовал кандидату на схему XSD, класс должен быть аннотирован аннотацией @XMLType .

Мы повторно используем файлы классов Java из предыдущего примера. Давайте настроим плагин:


    org.codehaus.mojo
    jaxb2-maven-plugin
    2.3
    
        
            schemagen
            
                schemagen
            
        
    
    
        
            src/main/java/com/baeldung/jaxb/gen
        
        src/main/resources
        false
        
            
                /jaxb/gen
                user
                user-gen.xsd

По умолчанию JAXB рекурсивно сканирует все папки в src/main/java на наличие аннотированных классов JAXB. Мы можем указать другую папку source для ваших аннотированных классов JAXB, добавив элемент source в конфигурацию плагина.

Мы также можем зарегистрировать схемы преобразования , постпроцессор, ответственный за присвоение имен схеме XSD. Он работает путем сопоставления пространства имен с пространством имен @XMLType вашего класса Java.

Когда мы создаем проект, он создает файл user-gen.xsd в каталоге src/main/resources .

8. Заключение

В этой статье мы рассмотрели вводные концепции JAXB. Для получения более подробной информации мы можем взглянуть на домашнюю страницу JAXB .

Мы можем найти исходный код этой статьи на GitHub .