XSD制限をサポートする自己文書化JAX-WS

この記事では、XSD Restrictions要素を使用する自己文書化Webサービス（jax-ws）の作成について説明します。

タスクの説明

「Programmer pragmatist」という本には、ドキュメントに関する章があります。 情報のソースは1つだけである必要があり、それに基づいて、この情報の派生形式が生成されます。 たとえば、テーブルの構造に関するすべての情報は1つの形式（任意の適切または独自の形式のファイル）で保存され、それに基づいてテーブル自体が生成されます。これらのテーブルのドキュメント、テーブルを操作するためのDAOオブジェクト。 このアプローチの利点は、情報を編集する唯一の場所がその元のソースであるため、情報を提示する派生的な形式の間に非同期化がないことです。

欠点は、関心のあるすべての人がこのファイルを編集できなければならず、目的の形式へのコンバータが必要になることです。

Webサービスでは、これらの概念は最初に契約と呼ばれ、最後に契約と呼ばれます。 最初に契約-wsdlが最初に作成され、Javaコードがそこから生成されるとき。 最後に契約-反対に、最初のJavaコード、それに応じたwsdl。

次のリンクで長所と短所について読むことができます： docs.spring.io/spring-ws/sites/1.5/reference/html/why-contract-first.html stackoverflow.com/questions/763827/which-is-the-better- Webサービスへのアプローチ契約の最初または最後の契約



この記事では、同様のソリューションを得るために、自己文書化を使用してSOAP Webサービスを作成することを検討します。Webサービスに関するすべての情報が含まれます。 それは一種の「契約最後」であることがわかります-最初にコードが記述され、次にこのWebサービスに関する最大の情報を含むwsdl形式のドキュメントが取得されます-サービスが機能するすべてのメソッドとタイプに関するコメント、およびデータの正確性をチェックするロジックのほとんど このソリューションが役立つのはなぜですか？ すべての開発がコードの記述に焦点を合わせ、wsdlがそれに基づいて生成され、その逆ではない場合。 または、最初にwsdlでドキュメントを管理することが困難な場合。 ただし、Webメソッドが分析用に作成されている場合は、この分析をwsdlに保存することをお勧めします。 つまり 最初にwsdlが作成され、そこからメソッド、クラス、読み取り可能なドキュメントが生成されます。 そうしないと、すでに作成されているサービスのコンプライアンスをチェックする際に問題が発生します。 タスク。

また、xsd側で入力データの有効性を確認することをお勧めします。これにより、Webサービスに接続せずにリクエストを確認でき、このロジックが（xsdで）表示され、サービスのどこかに配線されません。

ソリューションオプション

現在、jax-wsアプリケーションからwsdlを取得できます。 ただし、標準のjax-ws / jaxbアノテーションは、Webサービスのドキュメントをサポートしていません-このため、サードパーティのフレームワークが提供する機能を使用する必要があります。 具体的には、Apache CXF（jax-ws）はWSDLDocumentationアノテーションを提供します。これは、Webメソッドに適用され、その後wsdlで終わるWebメソッドを記述します。 jaxb-facetsライブラリ（ dsg.tuwien.ac.at/staff/hummer/tools/jaxb-facets.html、github.com/whummer/jaxb-facets ）は、Webメソッドで使用されるxmlエンティティを文書化するために使用されます。 WebメソッドのCXFと同様に、XML Beanのクラスとフィールドを文書化できます。 さらに、XSD制限のサポートを追加します-xmlフィールドの値に対する追加の制限。 （XSD制限の説明はこちらwww.w3schools.com/schema/schema_facets.asp ）これは、値の正確性をチェックするロジックが必須/オプションよりも複雑である場合に便利です。 jaxbは、xsdの検証機能を完全にはサポートしていません。 具体的には、最小値、最大値の制限を指定し、正規表現を使用し、空の値で文字列を処理するさまざまな方法を使用し、値の長さに制限を設定できます。

実装

例として、いくつかのメソッドを持つ単純なWebサービスを作成しましょう。

この記事では、特定の例とコードを説明します。 サービス全体はdl.dropboxusercontent.com/u/7519092/jax-ws-example.zipからダウンロードできます。これはIDEA mavenプロジェクトです。 IDEAでは、IDEAプロジェクトをインポートするか、Mavenプロジェクトをインポートすることで開くことができます。 Pom.xmlはwsdlファイルを生成し、xsltを使用してhtmlに変換するように構成されていますが、残念ながらこのwsdlにはjaxb-facetsのドキュメントタグが含まれていませんが、wsdlによって生成されます（リンク<application path> / web_service / WebService？ wsdl）このタグは。 また、プロジェクトでは、アノテーションの使用方法が異なります。アノテーションはgetメソッドに適用され、これらの例ではクラスのフィールドに適用されます。 これは、記事を短くするために行われます。 クラスのフィールドに注釈を適用するには、メソッドを取得しないか、@ XmlAccessorType（XmlAccessType.FIELD）を指定する必要があります。

例

例として、いくつかの特定のタスクを検討します

日付と時刻の最大値と最小値の制限。

日付の場合：

@XmlSchemaType(name = "date") @Facets(minInclusive = "1900-01-01", maxInclusive = "9999-12-31Z") Date date;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

生成されたxsd回路：

 <xs:element minOccurs="0" name="date"> <xs:simpleType> <xs:restriction base="xs:date"> <xs:maxInclusive value="9999-12-31Z"/> <xs:minInclusive value="1900-01-01"/> </xs:restriction> </xs:simpleType> </xs:element>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 @XmlSchemaType(name = "dateTime") @Facets(minInclusive = "1900-01-01T00:00:00", maxInclusive = "9999-12-31T23:59:59") Date dateTime;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 <xs:element minOccurs="0" name="dateTime"> <xs:simpleType> <xs:restriction base="xs:dateTime"> <xs:maxInclusive value="9999-12-31T23:59:59"/> <xs:minInclusive value="1900-01-01T00:00:00"/> </xs:restriction> </xs:simpleType> </xs:element>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

（jaxb-facetsライブラリのFacetsによる要約）



使用しなければならなかったのは DBMSは、Javaで使用可能な日付範囲をサポートしていませんでした。 つまり Webサービスでは、たとえば1000-01-01などの日付を転送できます。Javaでは正しく解析されますが、DBMSへの書き込み時にエラーが発生します。 この日付範囲はサポートされていません。 また、受け入れられる値を制限するために、この制限が導入されています。

日付については、タイムゾーンを考慮して最大日付が与えられます。 タイムゾーン付きの出力日付9999-12-31がサポートされている必要があります（たとえば、9999-12-31 + 04：00）。 これが行われない場合、この値をシリアル化するとき（クライアントに戻るとき）、xsd検証エラーが発生します。

特定のフィールド長の制限

 @Facets(length = 16) String id;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 <xs:element minOccurs="0" name="id"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:length value="16"/> </xs:restriction> </xs:simpleType> </xs:element>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

たとえば、フィールドが特定の長さの一意の識別子または特定の長さの他の識別子（パスポート、カードの番号）である場合に必要です。



idの場合、個別のタイプのIdを区別できます：

 public class Id { @Facets(length = 16) @XmlAttribute String attr; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そして、次のように使用します。

 Id id;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

したがって、これは変数であることを明確に示します-すべての制限は機能しますが、一意の識別子です。

フィールドのリセット

一部のオプションフィールドはクリアする必要があります。 文字列の場合、これは非常に簡単に行われます-空のタグが送信され（たとえば<name />）、非整列化（xmlリクエストをJavaオブジェクトに変換）すると、空の文字列のみが取得されます（String.isEmpty（）== true）。 また、nullに設定する必要がある文字列として完全に解釈できます。



ただし、数値または日付をリセットする必要がある場合、空のタグを渡すとエラーが発生します。

非整列化エラー：cvc-datatype-valid.1.2.1： ''は 'integer'の有効な値ではありません



これは理解できる-空のタグは数字として表すことができません（nullは考慮されません-nullはタグがないことを意味します）。



これは、フィールドのデフォルト値を使用して解決できます。

 @XmlElement(defaultValue = "-2147483648") Integer id;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 <xs:element default="-2147483648" minOccurs="0" name="id" type="xs:int"/>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

さらに、Javaで空のタグ（<id />）を渡すと、id変数の値は-2147483648になります（これはInteger.MIN_VALUEです）。 このソリューションは、Nullオブジェクトパターンに少し似ています-null値が明示的に渡されることを示す必要がある場合（値を指定しなかっただけでなく）、特別なnullオブジェクトを渡します。

en.wikipedia.org/wiki/Null_Object_pattern



日付の場合、同じアプローチは次のようになります。

 @XmlSchemaType(name = "date") @XmlElement(defaultValue = "1900-01-01") Date date;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 <xs:element default="1900-01-01" minOccurs="0" name="date" type="xs:date"/>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 @XmlSchemaType(name = "dateTime") @XmlElement(defaultValue = "1900-01-01T00:00:00") Date dateTime;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 <xs:element default="1900-01-01T00:00:00" minOccurs="0" name="dateTime" type="xs:dateTime"/>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ドキュメンテーション

フィールドのドキュメント化は、ドキュメントアノテーション（jaxb-facetsライブラリから）を使用して行われます。

 @XmlSchemaType(name = "date") @Documentation("  ") @Facets(minInclusive = "1900-01-01", maxInclusive = "9999-12-31Z") Date date;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 <xs:element minOccurs="0" name="date"> <xs:annotation> <xs:documentation>  </xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:date"> <xs:maxInclusive value="9999-12-31Z"/> <xs:minInclusive value="1900-01-01"/> </xs:restriction> </xs:simpleType> </xs:element>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Webサービスメソッドのドキュメント化は、CXFのWSDLDocumentationアノテーションを使用して行われます。

 @WSDLDocumentation("   .     XML Schema Restrictions") String facetsExampleMethod(FacetsExample request);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

 <wsdl:operation name="facetsExampleMethod"> <wsdl:documentation>    .     XML Schema Restrictions </wsdl:documentation> <wsdl:input message="tns:facetsExampleMethod" name="facetsExampleMethod"/> <wsdl:output message="tns:facetsExampleMethodResponse" name="facetsExampleMethodResponse"/> </wsdl:operation>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これらのフィールドとメソッドの詳細については、wsdlを参照してください。

サービスドキュメントの生成（wsdlからhtml）

生成されたwsdlを読み取り可能なビューに変換するには、xsltファイルtomi.vanek.sk/index.php?page=wsdl-viewerを使用します。SoapUIは読み取り可能なhtmlも生成できます。 これはすべてStackOverflowで説明されています。

stackoverflow.com/questions/686103/generated-html-documentation-from-wsdlビルド段階でのhtmlへの変換はpom.xmlで実装されています次に、このページは<application path> /WebService.htmlで利用できます

いくつかのHTML生成ノート：

Webメソッドのパラメーターは、@ SOAPBinding（style = SOAPBinding.Style.RPC）が指定されている場合にのみ正しく表示されます。

ドキュメントアノテーションは、ランタイムが実行中のサービスからwsdlを生成している場合にのみ、wsdlに、したがってHTMLドキュメントに取得されます。 wsdlをビルドするとき、ドキュメントは含まれません。 なぜそう-私は知りません。 最も可能性が高いのは、WSDLジェネレーターのエラーです。

jaxb-facetsのその他の機能

使用したjaxb-facetsのその他の機能について簡単に説明します。

正規表現による値の確認-Facets.pattern。

空白処理ロジックの設定-Facets.whiteSpace。 空白は考慮され、削除され、スペースに置き換えられます（タブおよび改行用）。 xsd、つまり Javaコードは、空白文字を使用して値をそのまま取得します。 スペースで満たされたフィールドも空として解釈される必要がある場合、文字列フィールドが必須であることを確認すると便利です。



一般に、jaxb-facetsはすべてのxsd制限をサポートしています。 ページwww.w3schools.com/schema/schema_facets.aspの最後でそれらに慣れることができます。最新バージョン（2.2.6）でもxs：assertサポートが登場しました。 例xs：IBM Webサイト（ www.ibm.com/developerworks/en/library/x-xml11pt2 ）からアサートします。

 <xs:element name="dimension"> <xs:complexType> <xs:attribute name="height" type="xs:int"/> <xs:attribute name="width" type="xs:int"/> <xs:assert test="@height < @width"/> </xs:complexType> </xs:element>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

備考

一般に、サービスが「ゼロから」記述されている場合は、正しいwsdlを作成し、それからJavaコードとドキュメントを既に生成している方が良いと繰り返します。 ただし、すでにWebサービスを作成している場合は、XSD制限を追加すると、クライアント側から透過的になります-入力値をチェックするロジックが表示されます（もちろん、すべてではありません-場合によっては、DBMSにアクセスせずにクエリの正確性をチェックすることは不可能です）関連リソース）。 さらに、ドキュメントの生成により、実際のWebメソッドとパラメーター、技術との対応を簡単に比較できます。 割り当て。 これがないと、入力するか、Webメソッドの要求と回答を確認するか、生成されたwsdlの複雑さを理解する必要があります。