[jbossws-commits] JBossWS SVN: r15598 - stack/cxf/trunk/modules/dist/src/main/doc.

Author: alessio.soldano(a)jboss.com Date: 2012-02-03 10:42:31 -0500 (Fri, 03 Feb 2012) New Revision: 15598 Modified: stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml Log: Updating documentation Modified: stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml 2012-02-03 15:41:00 UTC (rev 15597) +++ stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml 2012-02-03 15:42:31 UTC (rev 15598) @@ -6,7 +6,7 @@ <revhistory> <revision> <revnumber>4.0.0</revnumber> - <date>Mon Dec 19 2012</date> + <date>Mon Dec 19 2011</date> <author> <firstname>Alessio</firstname> <surname>Soldano</surname> @@ -18,6 +18,20 @@ </simplelist> </revdescription> </revision> + <revision> + <revnumber>4.0.1</revnumber> + <date>Fri Feb 03 2012</date> + <author> + <firstname>Alessio</firstname> + <surname>Soldano</surname> + <email&gt;alessio.soldano(a)jboss.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>JBossWS-CXF 4.0.1 documentation</member> + </simplelist> + </revdescription> + </revision> </revhistory> </simpara> </appendix> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml 2012-02-03 15:41:00 UTC (rev 15597) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml 2012-02-03 15:42:31 UTC (rev 15598) @@ -3,7 +3,11 @@ <chapter id="sid-3735860"> <title>Quick Start</title> - <para>JBossWS uses the JBoss Application Server as its target container. The following examples focus on web service deployments that leverage EJB3 service implementations and the JAX-WS programming models. For further information on POJO service implementations and advanced topics you need consult the user guide.</para> + <para> + JBossWS uses the JBoss Application Server as its target container. The following examples focus on web service deployments that leverage EJB3 service implementations and the JAX-WS programming models. For further information on POJO service implementations and advanced topics you need consult the + <link linkend="sid-3866716">user guide</link> + . + </para> <section id="sid-3735860_QuickStart-Developingwebserviceimplementations"> <title>Developing web service implementations</title> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml 2012-02-03 15:41:00 UTC (rev 15597) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml 2012-02-03 15:42:31 UTC (rev 15598) @@ -702,6 +702,53 @@ <para>false</para> </entry> </row> + <row> + <entry> + <para>argLine</para> + </entry> + <entry> + <para> + An optional additional argline to be used when running in fork mode; + + can be used to set endorse dir, enable debugging, etc. + + + <emphasis role="strong"> + <emphasis role="italics">Example</emphasis> + </emphasis> + + <code>&lt;argLine&gt;-Djava.endorsed.dirs=...&lt;/argLine&gt;</code> + </para> + </entry> + <entry> + <para>none</para> + </entry> + </row> + <row> + <entry> + <para>fork</para> + </entry> + <entry> + <para> + Whether or not to run the generation task in a separate VM. + + </para> + </entry> + <entry> + <para>false</para> + </entry> + </row> + <row> + <entry> + <para>target</para> + </entry> + <entry> + <para>A preference for the JAX-WS specification target</para> + </entry> + <entry> + <para>Depends on the underlying stack and endorsed dirs if any</para> + </entry> + </row> </tbody> </tgroup> </informaltable> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml 2012-02-03 15:41:00 UTC (rev 15597) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml 2012-02-03 15:42:31 UTC (rev 15598) @@ -670,7 +670,7 @@ <ulink url="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/ws-secu... specification</ulink> allows for specifying things like asymmetric/symmetric keys, using transports (https) for encryption, which parts/headers to encrypt or sign, whether to sign then encrypt or encrypt then sign, whether to include timestamps, whether to use derived keys, etc. </para> - <para>However some mandatory configuration elements are not covered by WS-SecurityPolicy, basically because they're not meant to be public / part of the published endpoint contract; those include things such as keystore locations, usernames and passwords, etc. Apache CXF allows configuring these elements either through Spring xml descriptors or using the client API. Below is the list of supported configuration properties:</para> + <para>However some mandatory configuration elements are not covered by WS-SecurityPolicy, basically because they're not meant to be public / part of the published endpoint contract; those include things such as keystore locations, usernames and passwords, etc. Apache CXF allows configuring these elements either through Spring xml descriptors or using the client API / annotations. Below is the list of supported configuration properties:</para> <informaltable> <tgroup cols="2"> <thead> @@ -833,11 +833,39 @@ }</programlisting> </informalexample> </section> + <section id="sid-3866795_WS-Security-ApacheCXFannotations"> + + <title>Apache CXF annotations</title> + <para> + The JBossWS configuration additions allow for a descriptor approach to the WS-Security Policy engine configuration. If you prefer to provide the same information through an annotation approach, you can leverage the Apache CXF + <code&gt;(a)org.apache.cxf.annotations.EndpointProperties&lt;/code&gt; + annotation: + </para> + <informalexample> + <programlisting>@WebService( + ... +) +@EndpointProperties(value = { + @EndpointProperty(key = "ws-security.signature.properties", value = "bob.properties"), + @EndpointProperty(key = "ws-security.encryption.properties", value = "bob.properties"), + @EndpointProperty(key = "ws-security.signature.username", value = "bob"), + @EndpointProperty(key = "ws-security.encryption.username", value = "alice"), + @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback") + } +) +public class ServiceImpl implements ServiceIface { + ... +}</programlisting> + </informalexample> + </section> </section> <section id="sid-3866795_WS-Security-Examples"> <title>Examples</title> <para>In this section some sample of WS-Security service endpoints and clients are provided. Please note they're only meant as tutorials; you should really careful isolate the ws-security policies / assertion that best suite your security needs before going to production environment.</para> + <warning> + <para>The following sections provide directions and examples on understanding some of the configuration options for WS-Security engine. Please note the implementor remains responsible for assessing the application requirements and choosing the most suitable security policy for them.</para> + </warning> <section id="sid-3866795_WS-Security-Signatureandencryption"> <title>Signature and encryption</title> @@ -1190,6 +1218,18 @@ </informalexample> <para>The Apache CXF WS-Policy engine will digest the security requirements in the contract and ensure a valid secure communication is in place for interacting with the server endpoint.</para> </section> + <section id="sid-3866795_WS-Security-Endpointservingmultipleclients"> + + <title>Endpoint serving multiple clients</title> + <para> + The server side configuration described above implies the endpoint is configured for serving a given client which a service agreement has been established for. In some real world scenarios though, the same server might be expected to be able to deal with (including decrypting and encrypting) messages coming from and being sent to multiple clients. Apache CXF supports that through the + <code>useReqSigCert</code> + value for the + <code>ws-security.encryption.username</code> + configuration parameter. + </para> + <para>Of course the referenced server side keystore then needs to contain the public key of all the clients that are expected to be served.</para> + </section> </section> <section id="sid-3866795_WS-Security-Authenticationandauthorization">