Como fazer classes geradas conter Javadoc de documentação XML Schema
https://stackoverflow.com/questions/1650249
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianPergunta
Atualmente estou trabalhando com um esquema XML que tem <xsd:annotation> / <xsd:documentation> na maioria dos tipos e elementos. Quando eu gerar Java Beans deste XML Schema, então o Javadoc desses Beans contém apenas algumas informações geradas genérica sobre o conteúdo permitido do tipo / elemento.
Eu gostaria de ver o conteúdo da tag <xsd:documentation> nos lugares relevantes (por exemplo, o conteúdo dessa tag para uma complextType deve aparecer no Javadoc da classe gerada para representar que complexType).
Existe alguma maneira de conseguir isso?
Editar :. Este XML Schema será usado em um WSDL com JAX-WS, assim que esta tag pode ser apropriado, bem
Editar 2 : Eu li sobre <jxb:javadoc>. Pelo que eu entendo que eu posso especificar que em um arquivo de ligação JAXB separado ou diretamente no XML Schema. Isso seria quase resolver o meu problema. Mas eu prefiro usar a tag <xsd:documentation> existente, desde Javadoc não é o alvo principal da documentação (é informações sobre a estrutura de dados primariamente e não sobre os Java Beans gerados a partir dele) e para permitir que as ferramentas não-JAXB para acessar as informações também. Fornecendo a documentação, tanto <jxb:javadoc> e xsd:documentation> "sente" errado, porque eu estou duplicação de dados (e trabalho) sem uma boa razão.
Editar 3 : Graças à resposta por Pascal percebi que já tem metade uma solução: O <xsd:documentation> de complexTypes é gravado no início de sua Javadoc! O problema ainda é que única que complexTypes é usado e simpleTypes (que também pode resultar em uma classe) e elementos ainda são Javadoc-less.
Solução
Eu nunca fui capaz de obter xsd:documentation regular para ser colocado na fonte java, exceto se e só se que era um tipo complexo. Documentação para elementos, tipos simples,
etc são ignorados.
Assim, acabo usando jxb:javadoc. Para fazer isso, incluir a definição de xmlns:jxb="http://java.sun.com/xml/ns/jaxb" em sua elemento <xsd:schema>.
Adicionar uma criança a <xsd:complexType> ou <xsd: element> ou <xsd:attribute>:
<xsd:annotation><xsd:appinfo><jxb:XXX><jxb:javadoc>
This is my comment for a class/property
</jxb:javadoc></jxb:XXX></xsd:appinfo></xsd:annotation>
Onde XXX é ou "classe" ou "propriedade".
Para um pacote que você escrever uma criança a xsd:schema
<xsd:annotation><xsd:appinfo><jxb:schemaBindings><jxb:package name="com.acme"><jxb:javadoc>
This is my comment for a package
</jxb:javadoc></jxb:package></jxb:schemaBindings></xsd:appinfo></xsd:annotation>
documento Escrita HTML requer Bracketing com <![CDATA[ --- ]]>
(EDIT: Ao escrever a minha resposta, a pergunta foi editado pela OP então eu estou atualizando-a em conformidade)
No meu caso, javadoc foi o único alvo por isso era aceitável usar jxb:javadoc. Mas sua atualização faz todo o sentido e, na verdade, eu concordo totalmente com você. Infelizmente, eu nunca encontrei uma solução ideal para a situação que você descreve (então eu vou seguir esta questão com muito cuidado). Talvez você poderia usar algo como Xframe para gerar a documentação de xsd:documentation, mas isso não responde a questão.
Outras dicas
Isso não é possível com a implementação de referência JAXB. Mesmo se estivesse a tentar escrever um plugin XJC, você acharia que a API plugin é dada nenhuma referência à definição de esquema, então não há nenhuma maneira de extrair essas informações.
A nossa única esperança é que uma versão futura do JAXB corrige a situação. Há um pedido de recurso aberta aqui .
I encontrar as seguintes técnicas funcionam muito bem para adicionar cabeçalhos JavaDoc para classes de elemento Java (gerados a partir de esquemas XML). ninho I do JavaDoc em tags definidas no JAX-b namespace, aninhada dentro a anotação esquema XML e appInfo tags. Observe as define jaxb namespace tipos de tags de documentação; Eu uso dois de lá: a classe e as marcas de propriedade. definido da seguinte namespace: xmlns: JXB = "http://java.sun.com/xml/ns/jaxb"
1) Para documentar uma classe, eu uso um jaxb tag "classe" na seguinte seqüência:
<xs:complexType name="Structure">
<xs:annotation>
<xs:appinfo>
<jxb:class>
<jxb:javadoc>
Documentation text goes here. Since parsing the schema
into Java involves evaluating the xml, I escape all
the tags I use as follows <p> for <p>.
</jxb:javadoc>
</jxb:class>
</xs:appinfo>
</xs:annotation>
.
.
.
</xs:complexType>
2) Para documentar um elemento, eu uso a tag "propriedade" da seguinte forma:
<xs:element name="description" type="rep:NamedString">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:element>
3) Eu uso o mesmo conjunto de tags para atributos do documento:
<xs:attribute name="name" type="xs:NCName" use="required">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
4) Para documentar uma escolha, eu uso o tag propriedade jaxb, e eu documentar a escolha.
<xs:choice maxOccurs="unbounded">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
<xs:element name="value" type="rep:NamedValue" />
<xs:element name="list" type="rep:NamedList" />
<xs:element name="structure" type="rep:NamedStructure" />
</xs:choice>
A tentativa de documentar as escolhas individuais aqui seria um fracasso, uma vez que esta tag produz uma lista sem tipo.
Especialmente para esse caso eu escrevi XJC plug-in xjc-documentação de anotação-plugin .
O que faz: <annotation><documentation> -> anotações de classe Java
disse que nós temos este objeto descrito no XSD:
<xs:complexType name="CadastralBlock">
<xs:annotation>
<xs:documentation>Cadastral quarter</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="number" type="xs:string">
<xs:annotation>
<xs:documentation>Cadastral number</xs:documentation>
</xs:annotation>
</xs:element>
</xs:complexType>
Corremos xjc como:
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd
E tem classe como (getters, setters e quaisquer anotações omitidos por simplicidade):
public class CadastralBlock {
protected String number;
}
Mas no meu caso eu quero conhecida como classe e campos foi nomeado em arquivo de origem! Assim que este plugin faz!
Assim que você começa:
@XsdInfo(name = "Cadastral quarter", xsdElementPart = "<complexType name=\"CadastralBlock\">\n <complexContent>\n <restriction base=\"{http://www.w3.org/2001/XMLSchema}anyType\">\n <sequence>\n <element name=\"number\" type=\"{http://www.w3.org/2001/XMLSchema}string\"/></sequence>\n </restriction>\n </complexContent></complexType>")
public class CadastralBlock {
@XsdInfo(name = "Cadastral number")
protected String number;
}
Como usar
chamada manual na linha de comando
Se você quiser executá-lo manualmente garantir classe frasco com o plugin no classpath prazo e apenas adicionar opção -XPluginDescriptionAnnotation. F.E.:.
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd
Chamada de Java / Groovy
Driver.run(
[
'-XPluginDescriptionAnnotation'
,'-d', generatedClassesDir.absolutePath
,'-p', 'info.hubbitus.generated.test'
,'CadastralBlock.xsd'
] as String[]
,new XJCListener() {...}
)
Veja teste XJCPluginDescriptionAnnotationTest por exemplo.
Uso de Gradle
Com Gradle-xjc-plugin :
plugins {
id 'java'
id 'org.unbroken-dome.xjc' version '1.4.1' // https://github.com/unbroken-dome/gradle-xjc-plugin
}
...
dependencies {
xjcClasspath 'info.hubbitus:xjc-documentation-annotation-plugin:1.0'
}
// Results by default in `build/xjc/generated-sources`
xjcGenerate {
source = fileTree('src/main/resources') { include '*.xsd' }
packageLevelAnnotations = false
targetPackage = 'info.hubbitus.xjc.plugin.example'
extraArgs = [ '-XPluginDescriptionAnnotation' ]
}
exemplo gradle completo em exemplo-project diretório -gradle do projeto.
