生成されたクラスにXMLスキーマドキュメントのJavadocを含める方法
https://stackoverflow.com/questions/1650249
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian質問
現在、ほとんどの型と要素に<xsd:annotation> / <xsd:documentation>を含むXMLスキーマを使用しています。このXMLスキーマからJava Beanを生成すると、それらのBeanのJavadocには、タイプ/要素の許可されたコンテンツに関する一般的な生成情報のみが含まれます。
関連する場所で<jxb:javadoc>タグのコンテンツを確認したい（たとえば、complextTypeのタグのコンテンツは、そのcomplexTypeを表すために生成されたクラスのJavadocに表示されるはずです）
これを達成する方法はありますか？
編集：このXMLスキーマはJAX-WSを使用するWSDLで使用されるため、このタグも適切である可能性があります。
編集2 ：xsd:documentation>について読みました。私が理解していることから、別のJAXBバインディングファイルで指定するか、XMLスキーマで直接指定することができます。それは私の問題をほとんど解決するでしょう。ただし、Javadocはドキュメントの主要なターゲットではない（主にデータ構造に関する情報であり、それから生成されるJava Beanに関する情報ではない）ため、既存のcomplexTypeタグを使用し、非JAXBツールからのアクセスを許可する情報も。 simpleTypeと<=> <！> quot; feels <！> quotの両方でドキュメントを提供します。間違っている、私は正当な理由もなくデータを複製している（そして働いている）から。
編集3 ：Pascalの回答のおかげで、すでに半分の解決策があることに気付きました。<=>の<=>はJavadocの先頭に書き込まれます。問題は、 only <=> sが使用され、<=> s（これもクラスになる可能性がある）と要素がJavadocを使用しないことです。
解決
通常のxsd:documentationをJavaソースに配置することができませんでした。ただし、複合型であった場合のみ。要素、単純型、
などは無視されます。
つまり、jxb:javadocを使用することになります。そのためには、xmlns:jxb="http://java.sun.com/xml/ns/jaxb"要素に<xsd:schema>の定義を含めます。
<xsd:complexType>または<xsd: element>または<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>
XXXは<！> quot; class <！> quot;または<！> quot; property <！> quot;。
パッケージの場合、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>
HTMLドキュメントの作成には、<![CDATA[ --- ]]>
（編集：私の答えを書いている間、質問はOPによって編集されているので、それに応じて更新しています）
私の場合、javadocが唯一のターゲットであったため、<=>を使用しても問題ありませんでした。しかし、あなたの更新は完全に理にかなっており、実際、私はあなたに完全に同意します。残念なことに、私はあなたが説明する状況に対する理想的な解決策を見つけられませんでした（したがって、この質問には非常に注意深く従います）。 xframe のようなものを使用して<=>からドキュメントを生成できますが、これはできませんt質問に答えます。
他のヒント
これは、JAXBリファレンス実装では不可能です。 XJCプラグインを記述しようとしても、プラグインAPIにはスキーマ定義への参照が与えられないため、この情報を抽出する方法はありません。
唯一の希望は、JAXBの将来のバージョンで状況が修正されることです。 ここで機能を開くリクエストがあります。
次の手法は、JavaDocヘッダーを（XMLスキーマから生成された）Java要素クラスに追加するのに非常にうまく機能することがわかりました。 jax-b名前空間で定義されたタグにJavaDocをネストし、xmlスキーマアノテーションとappinfoタグ内にネストします。 jaxb名前空間は、ドキュメントタグのタイプを定義します。クラスとプロパティタグの2つを使用します。次のネームスペースで定義されています：xmlns：jxb = <！> quot; http：//java.sun.com/xml/ns/jaxb <！> quot;
1）クラスを文書化するには、jaxb <！> quot; class <！> quot;を使用します。次のシーケンスのタグ：
<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）要素を文書化するには、<！> quot; property <！> quot;を使用します。次のようなタグ：
<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）同じタグのセットを使用して属性を文書化します：
<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）選択を文書化するには、プロパティjaxbタグを使用し、選択を文書化します。
<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>
ここで個々の選択肢を文書化しようとすると失敗します。このタグは 型なしリストを作成します。
特にその場合、XJCプラグインを作成しました xjc-documentation-annotation-plugin 。
機能：<annotation><documentation>-<！> gt; Javaクラスの注釈
このオブジェクトは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>
xjcは次のように実行します：
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd
次のようなクラスを取得しました（ゲッター、セッター、および簡単にするために省略された注釈）：
public class CadastralBlock {
protected String number;
}
しかし、私の場合、クラスとフィールドの方法をソースファイルで指定したかどうかを知りたいです！このプラグインの機能！
次のようになります：
@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;
}
使用方法
コマンドラインでの手動呼び出し
手動で実行する場合は、実行クラスパスにプラグインが含まれるjarクラスを確認し、オプション-XPluginDescriptionAnnotationを追加します。 F.e。：
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd
Java / Groovyからの呼び出し
Driver.run(
[
'-XPluginDescriptionAnnotation'
,'-d', generatedClassesDir.absolutePath
,'-p', 'info.hubbitus.generated.test'
,'CadastralBlock.xsd'
] as String[]
,new XJCListener() {...}
)
たとえば、テストXJCPluginDescriptionAnnotationTestを参照してください。
Gradleから使用
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' ]
}
例のgradle例を完了-project-gradle プロジェクトのディレクトリ。
