24.3. コードに注釈を付ける

@WSDLDocumentation アノテーションは、org.apache.cxf.annotations.WSDLDocumentation インターフェイスによって定義されます。SEI または SEI メソッドに配置できます。

このアノテーションを使用するとドキュメントを追加でき、SEI が WSDL に変換された後に wsdl:documentation 要素内に表示されます。デフォルトでは、ドキュメント要素はポートタイプ内に表示されますが、配置プロパティーを指定して、ドキュメントを WSDL ファイルの他の場所に表示することができます。「@WSDLDocumentation プロパティー」 は @WSDLDocumentation アノテーションがサポートするプロパティーを表示します。

@WSDLDocumentationCollection アノテーションは、org.apache.cxf.annotations.WSDLDocumentationCollection インターフェイスによって定義されます。SEI または SEI メソッドに配置できます。

この注釈は、単一の配置場所またはさまざまな配置場所に複数のドキュメント要素を挿入するために使用されます。

WSDL コントラクトでドキュメントが表示される場所を指定するには、タイプ WSDLDocumentation.Placement の placement プロパティーを指定します。プレースメントには、次のいずれかの値を指定できます。

「@WSDLDocumentation の使用」 に、@WSDLDocumentation アノテーションを SEI およびそのメソッドの 1 つに追加する方法を示します。

「@WSDLDocumentationCollection を使用する」 では 、@WSDLDocumentationCollection アノテーションを SEI に追加する方法を説明します。

@SchemaValidation アノテーションは org.apache.cxf.annotations.SchemaValidation インターフェイスによって定義されます。これは、SEI および個々の SEI メソッドに配置できます。

このアノテーションは、このエンドポイントに送信される XML メッセージのスキーマ検証をオンにします。これは、着信 XML メッセージの形式に問題があると思われる場合のテスト目的に役立ちます。パフォーマンスに大きな影響を与えるため、デフォルトでは検証は無効になっています。

スキーマ検証の動作は、type パラメーターによって制御されます。この値は、org.apache.cxf.annotations.SchemaValidation.SchemaValidationType 型の列挙になります。「スキーマ検証タイプの値」 は使用可能な検証タイプのリストを示します。

次の例は、MyService SEI に基づいてエンドポイントのメッセージのスキーマ検証を有効にする方法を示しています。アノテーションを SEI 全体に適用する方法と、SEI の個々のメソッドに適用する方法に注意してください。

@WebService
@SchemaValidation(type = SchemaValidationType.BOTH)
public interface MyService {
    Foo validateBoth(Bar data);

    @SchemaValidation(type = SchemaValidationType.NONE)
    Foo validateNone(Bar data);

    @SchemaValidation(type = SchemaValidationType.IN)
    Foo validateIn(Bar data);

    @SchemaValidation(type = SchemaValidationType.OUT)
    Foo validateOut(Bar data);

    @SchemaValidation(type = SchemaValidationType.REQUEST)
    Foo validateRequest(Bar data);

    @SchemaValidation(type = SchemaValidationType.RESPONSE)
    Foo validateResponse(Bar data);
}

@DataBinding アノテーションは、org.apache.cxf.annotations.DataBinding インターフェイスによって定義されます。SEI に配置されます。

このアノテーションは、データバインディングを SEI に関連付けるために使用され、デフォルトの JAXB データバインディングを置き換えます。@DataBinding アノテーションの値は、データバインディングを提供するクラス ClassName.class である必要があります。

次のデータバインディングは現在、Apache CXF でサポートされています。

「データバインディングの設定」 SDO バインディングを HelloWorld SEI に関連付ける方法を説明します。

@GZIP アノテーションは org.apache.cxf.annotations.GZIP インターフェイスによって定義されます。SEI に配置されます。

メッセージの GZIP 圧縮を有効にします。GZIP はネゴシエートされた拡張機能です。つまり、クライアントからの最初の要求は gzipped ではありませんが、Accept ヘッダーが追加され、サーバーが GZIP 圧縮をサポートする場合、応答は gzipped になり、後続のリクエストも指定します。

「@GZIP Properties」 は、@GZIP アノテーションでサポートされるオプションのプロパティーを示しています。

@FastInfoset アノテーションは、org.apache.cxf.annotations.FastInfoset インターフェイスによって定義されます。SEI に配置されます。

メッセージに FastInfoset 形式を使用できるようにします。FastInfoset は、XML のバイナリーエンコーディング形式であり、メッセージサイズと XML メッセージの処理パフォーマンスの両方を最適化することを目的としています。詳細については、Fast Infoset に関する次の Sun の記事を参照してください。

FastInfoset は、ネゴシエートされた拡張機能です。つまり、クライアントからの最初のリクエストは FastInfoset 形式では追加されませんが、Accept ヘッダーが追加され、サーバーが FastInfoset をサポートしていると、応答は FastInfoset になり、後続のリクエストも行われます。

「@FastInfoset プロパティー」 は、@FastInfoset アノテーションでサポートされる任意のプロパティーを表示します。

「GZIP の有効化」 は、HelloWorld SEI で GZIP 圧縮を有効にする方法を示します。

「FastInfoset の有効化」 は、HelloWorld SEI の FastInfoset 形式を有効にする方法を示します。

@Logging アノテーションは、org.apache.cxf.annotations.Logging インターフェイスによって定義されます。SEI に配置されます。

このアノテーションにより、SEI に関連付けられているすべてのエンドポイントのロギングが可能になります。「@Logging Properties」 は、このアノテーションで設定できるオプションのプロパティーを示しています。

「注釈を使用した設定のロギング」で、HelloWorld SEI でロギングを有効にする方法を説明します。ここでは、受信メッセージは <stdout> に送信され、発信メッセージは <logger> に送信されます。

@EndpointProperty アノテーションは、org.apache.cxf.annotations.EndpointProperty インターフェイスによって定義されます。SEI に配置されます。

このアノテーションは、Apache CXF 固有の設定をエンドポイントに追加します。エンドポイントのプロパティーは、Spring 設定ファイルで指定することもできます。たとえば、エンドポイントに WS-Security を設定するには、以下のように Spring 設定ファイルの jaxws:properties 要素を使用してエンドポイントプロパティーを追加できます。

<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:jaxws="http://cxf.apache.org/jaxws"
   ... >

   <jaxws:endpoint
      id="MyService"
      address="https://localhost:9001/MyService"
      serviceName="interop:MyService"
      endpointName="interop:MyServiceEndpoint"
      implementor="com.foo.MyService">

      <jaxws:properties>
         <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
         <entry key="ws-security.signature.properties" value="etc/keystore.properties"/>
         <entry key="ws-security.encryption.properties" value="etc/truststore.properties"/>
         <entry key="ws-security.encryption.username" value="useReqSigCert"/>
      </jaxws:properties>

   </jaxws:endpoint>
</beans>

あるいは、「@EndpointProperty アノテーションを使用した WS-Security の設定」に示すように、@EndpointProperty アノテーションを SEI に追加して、Java で前述の設定を指定できます。

@EndpointProperties アノテーションは、org.apache.cxf.annotations.EndpointProperties インターフェイスによって定義されます。SEI に配置されます。

このアノテーションは、複数の @EndpointProperty アノテーションをリストにグループ化する方法を提供します。@EndpointProperties を使用すると、「@EndpointProperties アノテーションを使用した WS-Security の設定」 に示すように 「@EndpointProperty アノテーションを使用した WS-Security の設定」 を再書き込みできます。

@Policy アノテーションは org.apache.cxf.annotations.Policy インターフェイスによって定義されます。SEI または SEI メソッドに配置できます。

このアノテーションは、WSDL ポリシーを SEI または SEI メソッドに関連付けるために使用されます。ポリシーは、標準の wsdl:policy 要素を含む XML ファイルを参照する URI を提供することにより指定されます。SEI から WSDL コントラクトが生成される場合は (たとえば、java2ws コマンドラインツールを使用して)、WSDL にこのポリシーを追加するかどうかを指定できます。

「@Policy プロパティー」 に、@Policy アノテーションでサポートされるプロパティーを示します。

@Policies アノテーションは org.apache.cxf.annotations.Policies インターフェイスで定義されます。SEI または SEI メソッドに配置できます。

このアノテーションは、複数の @Policy アノテーションをリストにグループ化する方法を提供します。

ポリシーが WSDL コントラクトのどこに表示されるかを指定するには、Policy.Placement 型である placement プロパティーを指定します。プレースメントには、次のいずれかの値を指定できます。

Policy.Placement.BINDING
Policy.Placement.BINDING_OPERATION
Policy.Placement.BINDING_OPERATION_FAULT
Policy.Placement.BINDING_OPERATION_INPUT
Policy.Placement.BINDING_OPERATION_OUTPUT
Policy.Placement.DEFAULT
Policy.Placement.PORT_TYPE
Policy.Placement.PORT_TYPE_OPERATION
Policy.Placement.PORT_TYPE_OPERATION_FAULT
Policy.Placement.PORT_TYPE_OPERATION_INPUT
Policy.Placement.PORT_TYPE_OPERATION_OUTPUT
Policy.Placement.SERVICE
Policy.Placement.SERVICE_PORT

以下の例は、WSDL ポリシーを HelloWorld SEI に関連付け、ポリシーを sayHi メソッドに関連付ける方法を示しています。ポリシー自体は、annotationpolicies ディレクトリーの下に、ファイルシステムの XML ファイルに保存されます。

@WebService
@Policy(uri = "annotationpolicies/TestImplPolicy.xml",
        placement = Policy.Placement.SERVICE_PORT),
@Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
        placement = Policy.Placement.PORT_TYPE)
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}

以下の例のように、@Policies アノテーションを使用して、複数の @Policy アノテーションをリストにグループ化できます。

@WebService
@Policies({
    @Policy(uri = "annotationpolicies/TestImplPolicy.xml",
            placement = Policy.Placement.SERVICE_PORT),
    @Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
            placement = Policy.Placement.PORT_TYPE)
})
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}