jaxb2-maven-plugin使用说明

jaxb2-maven-plugin是一个用来代替xjc和schemagen用来完成java类和schema文件之间互相转换的maven插件.
使用说明:官方地址
源码地址:github
首先在pom配置该插件:

<plugin>
                <groupId>org.codehuas.jaxb2</groupId>
                <artifactId>jaxb2-maven-plugin</artifactId>
                <version>2.2</version>
                <configuration>
                    <createJavaDocAnnotations>true</createJavaDocAnnotations>
                    <encoding>utf-8</encoding>
                    <schemaSourceExcludeFilters>
                        <noJaxbIndex implementation="org.codehaus.mojo.jaxb2.shared.filters.pattern.PatternFileFilter">
                            <patterns>
                                <pattern>com.test.*</pattern>
                            </patterns>
                        </noJaxbIndex>
                    </schemaSourceExcludeFilters>
                </configuration>
            </plugin>

主要运行命令为jaxb2:schemagen和jaxb2:xjc,分别用来从Java类生成schema和从schema文件生成Java类.具体配置参考官方文档.

实际使用过程中遇到的问题:

在使用jaxb2:schemagen生成schema文件时,如果Java bean属性名称和指定的name不一样时无法生成doc文档片段,如下:

package com.test;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

/**
 * 人员信息
 * Created by wenjiangchun on 16-3-15.
 */
@XmlAccessorType(XmlAccessType.FIELD)
@XmlRootElement
public class Person {

    /**
     * 人员名称
     */
    @XmlElement(name = "username", required = true)
    private String name;

    /**
     * 住址信息
     */
    private String address;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return "Person{" +
                "name='" + name + '\'' +
                ", address='" + address + '\'' +
                '}';
    }
}

执行jaxb2:schemagen后生成schema文件如下:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" version="1.0">

  <xs:element name="person" type="person"/>

  <xs:complexType name="person">
    <xs:annotation>
      <xs:documentation><![CDATA[人员信息
Created by wenjiangchun on 16-3-15.]]></xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="username" type="xs:string"/>
      <xs:element minOccurs="0" name="address" type="xs:string">
        <xs:annotation>
          <xs:documentation><![CDATA[住址信息]]></xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

可以看到,Person类中属性名称为”name”,指定的schema文档中对应的属性名称为”username”,这种情况下不会将属性注释生成出来.

解决办法:
将插件源码从github上clone出来,查看源码中下面类:

org.codehaus.mojo.jaxb2.schemageneration.postprocessing.javadoc.JavaDocExtractor

从类名称可以知道该类主要用来获取Java Doc描述信息,在类中process方法中找到如下代码片段:

for (JavaField currentField : currentClass.getFields()) {
                    // Add the field-level JavaDoc
                    String currentFieldName = currentField.getName();

                    final FieldLocation fieldLocation = new FieldLocation(
                            packageName,
                            simpleClassName,
                            currentFieldName);
                    addEntry(dataHolder, fieldLocation, currentField);

                    if (log.isDebugEnabled()) {
                        log.debug("Added field-level JavaDoc for [" + fieldLocation + "]");
                    }
                }

将以上代码修改如下:

 for (JavaField currentField : currentClass.getFields()) {
                    // Add the field-level JavaDoc
                    String currentFieldName = currentField.getName();
                    List<JavaAnnotation> list = currentField.getAnnotations();
                    for (JavaAnnotation annotation : list) {
                        if (annotation.getType().getName().equals("XmlAttribute") || annotation.getType().getName().equals("XmlElement")) {
                            if (annotation.getProperty("name") != null) {
                                currentFieldName = annotation.getProperty("name").toString();
                                currentFieldName = currentFieldName.replaceAll("\"", "");
                            }
                        }
                    }
                    final FieldLocation fieldLocation = new FieldLocation(
                            packageName,
                            simpleClassName,
                            currentFieldName);
                    addEntry(dataHolder, fieldLocation, currentField);

                    if (log.isDebugEnabled()) {
                        log.debug("Added field-level JavaDoc for [" + fieldLocation + "]");
                    }
                }

以上代码意思就是如果Java Bean属性上指定了@XmlAttribute或@XmlElement注解,就使用该注解中指定的name作为currentFieldName.
如果注解是加在方法上,同样可以通过以上途径来获取当前name.
最后重新打包执行命令jaxb2:schemagen测试:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" version="1.0">

  <xs:element name="person" type="person"/>

  <xs:complexType name="person">
    <xs:annotation>
      <xs:documentation><![CDATA[人员信息
Created by wenjiangchun on 16-3-15.]]></xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="username" type="xs:string">
        <xs:annotation>
          <xs:documentation><![CDATA[人员名称]]></xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element minOccurs="0" name="address" type="xs:string">
        <xs:annotation>
          <xs:documentation><![CDATA[住址信息]]></xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

注意:每次生成前需要执行下clean命令将原有生成的删除再执行jaxb2:schemagen命令,或者直接执行 clean jaxb2:schemagen.