Come rendere le classi generate contengono Javadoc dalla documentazione dello schema XML

Question

Attualmente sto lavorando con uno schema XML che ha <xsd:annotation> / <xsd:documentation> sulla maggior parte dei tipi e degli elementi. Quando generi Java Beans da questo schema XML, il Javadoc di quei bean contiene solo alcune informazioni generiche generate sul contenuto consentito del tipo / elemento.

Mi piacerebbe vedere il contenuto del tag <jxb:javadoc> nelle posizioni pertinenti (ad esempio, il contenuto di quel tag per un tipo di complext dovrebbe essere visualizzato nel Javadoc della classe generata per rappresentare quel tipo complesso).

C'è un modo per raggiungere questo obiettivo?

Modifica : questo schema XML verrà utilizzato in un WSDL con JAX-WS, quindi anche questo tag potrebbe essere appropriato.

Modifica 2 : ho letto di xsd:documentation>. Da quanto ho capito, posso specificare che in un file di associazione JAXB separato o direttamente nello schema XML. Questo quasi risolverebbe il mio problema. Ma preferirei usare il tag complexType esistente, poiché Javadoc non è la destinazione principale della documentazione (sono le informazioni sulla struttura dei dati principalmente e non sui Java Beans generati da esso) e per consentire agli strumenti non JAXB di accedere anche l'informazione. Fornire la documentazione in simpleType e <=> & Quot; feel & Quot; sbagliato, perché sto duplicando i dati (e funzionando) senza una buona ragione.

Modifica 3 : grazie alla risposta di Pascal mi sono reso conto che ho già mezza soluzione: il <=> di <=> s è scritto all'inizio del suo Javadoc! Il problema è ancora che solo viene utilizzato <=> s e <=> s (che può anche provocare una classe) e gli elementi sono ancora senza Javadoc.

Answer 1

Non sono mai stato in grado di ottenere un xsd:documentation normale da inserire nella fonte java tranne se e solo se era un tipo complesso. Documentazione per elementi, tipi semplici, ecc. vengono ignorati.

Quindi, finisco con jxb:javadoc. Per fare ciò, includi la definizione di xmlns:jxb="http://java.sun.com/xml/ns/jaxb" nel tuo <xsd:schema> elemento.

Aggiungi un bambino a <xsd:complexType> o <xsd: element> o <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>

Dove XXX è " class " o " proprietà " ;.

Per un pacchetto scrivi un figlio in 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>

La scrittura di documenti HTML richiede il bracketing con <![CDATA[ --- ]]>

(EDIT: mentre scrivo la mia risposta, la domanda è stata modificata dall'OP, quindi la sto aggiornando di conseguenza)

Nel mio caso, javadoc era l'unico obiettivo, quindi era accettabile usare <=>. Ma il tuo aggiornamento ha perfettamente senso e, in realtà, sono totalmente d'accordo con te. Purtroppo, non ho mai trovato una soluzione ideale per la situazione che descrivi (quindi seguirò molto attentamente questa domanda). Forse potresti usare qualcosa come xframe per generare documentazione da <=>, ma non t rispondi alla domanda.

Answer 2

Questo non è proprio possibile con l'implementazione di riferimento JAXB. Anche se dovessi provare a scrivere un plugin XJC, scopriresti che all'API del plugin non viene dato alcun riferimento alla definizione dello schema, quindi non c'è modo di estrarre queste informazioni.

La nostra unica speranza è che una versione futura di JAXB risolva la situazione. C'è una richiesta di funzionalità aperta qui .

Answer 3

Trovo che le seguenti tecniche funzionino piuttosto bene per aggiungere intestazioni JavaDoc alle classi di elementi Java (generate da schemi XML). Nido di JavaDoc nei tag definiti nello spazio dei nomi jax-b, nidificati all'interno dei tag annotazione dello schema xml e appinfo. Nota lo spazio dei nomi jaxb definisce i tipi di tag della documentazione; Ne uso due: la classe e i tag proprietà. definito nel seguente spazio dei nomi: xmlns: jxb = " http: //java.sun.com/xml/ns/jaxb "

1) Per documentare una classe, uso un jaxb " class " tag nella seguente sequenza:

  <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 &lt;p&gt; for <p>.
              </jxb:javadoc>
           </jxb:class>
        </xs:appinfo>
     </xs:annotation>

     .
     .
     .
  </xs:complexType>

2) Per documentare un elemento, uso la " proprietà " tag come segue:

       <xs:element name="description" type="rep:NamedString">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>
       </xs:element>

3) Uso lo stesso set di tag per documentare gli attributi:

      <xs:attribute name="name" type="xs:NCName" use="required">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>
       </xs:attribute>

4) Per documentare una scelta, utilizzo il tag proprietà jaxb e documento la scelta.

    <xs:choice maxOccurs="unbounded">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </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>

Tentare di documentare le singole scelte qui fallirebbe, dato che questo tag produce un elenco non tipizzato.

Answer 4

Soprattutto per quel caso ho scritto plugin XJC xjc-documentazione-annotazione-plugin .

Cosa fa: <annotation><documentation> - > Annotazioni di classe Java

Abbiamo detto che questo oggetto è descritto in 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>

Eseguiamo xjc come:

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd

E ha classe come (getter, setter ed eventuali annotazioni omesse per semplicità):

public class CadastralBlock {
    protected String number;
}

Ma nel mio caso voglio sapere come classificare e i campi sono stati nominati nel file sorgente! Quindi cosa fa questo plugin!

Quindi ottieni:

@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;
}

Come usare

Chiamata manuale nella riga di comando

Se vuoi eseguirlo manualmente, assicurati che la classe jar con il plugin sia in run classpath e aggiungi l'opzione -XPluginDescriptionAnnotation. F.e:.

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd

Chiama da Java / Groovy

Driver.run(
    [
        '-XPluginDescriptionAnnotation'
        ,'-d', generatedClassesDir.absolutePath
        ,'-p', 'info.hubbitus.generated.test'
        ,'CadastralBlock.xsd'
    ] as String[]
    ,new XJCListener() {...}
)

Vedi test XJCPluginDescriptionAnnotationTest per esempio.

Usa da Gradle

Con 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' ]
}

Completa gradle esempio nell'esempio -project-gradle directory del progetto.