[jboss-cvs] JBossAS SVN: r92824 - projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Aug 26 06:35:59 EDT 2009
Author: richard.opalka at jboss.com
Date: 2009-08-26 06:35:59 -0400 (Wed, 26 Aug 2009)
New Revision: 92824
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml
Log:
[JBPAPP-2620] documentation review (WIP)
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml 2009-08-26 10:06:17 UTC (rev 92823)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml 2009-08-26 10:35:59 UTC (rev 92824)
@@ -50,187 +50,6 @@
</para>
</section>
- <section><title>JBoss Web Services Attachment support with XOP (XML-binary Optimized Packaging) and SwA</title>
- <para>
- JBoss-WS4EE relied on a deprecated attachments technology called SwA (SOAP with Attachments). SwA required soap/encoding which is disallowed by the WS-I Basic Profile. JBossWS provides support for WS-I AP 1.0, and MTOM instead. <!--There will be no API change for users, however, since this is an updated protocol you will not be able to transfer attachments between older versions of JBoss AS and JBoss AS 4.0.4 or above.-->
- </para>
- <para>
- <ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">WS-I Attachment Profile 1.0</ulink> defines a mechanism to reference MIME attachment parts using swaRef. In this mechanism the content of XML element of type <property>wsi:swaRef</property> is sent as a MIME attachment and the element inside SOAP Body holds the reference to this attachment in the CID URI scheme as defined by RFC 2111.
- </para>
-</section>
- <section><title>Using SwaRef with JAX-WS endpoints</title>
- <para>
- JAX-WS endpoints delegate all marshalling/unmarshalling to the JAXB API. The most simple way to enable SwaRef encoding for DataHandler types is to annotate a payload bean with the <property>@XmlAttachmentRef</property> annotation as shown below:
- </para>
-
-<programlisting role="JAVA">/**
- * Payload bean that will use SwaRef encoding.
- */
- at XmlRootElement
-public class DocumentPayload
-{
- private DataHandler data;
-
- public DocumentPayload()
- {
- }
-
- public DocumentPayload(DataHandler data)
- {
- this.data = data;
- }
-
- @XmlElement
- @XmlAttachmentRef
- public DataHandler getData()
- {
- return data;
- }
-
- public void setData(DataHandler data)
- {
- this.data = data;
- }
-}</programlisting>
- <para>
- With document wrapped endpoints you may even specify the @XmlAttachmentRef annotation on the service endpoint interface:
- </para>
-<programlisting role="JAVA">@WebService
-public interface DocWrappedEndpoint
-{
- @WebMethod
- DocumentPayload beanAnnotation(DocumentPayload dhw, String test);
-
- @WebMethod
- @XmlAttachmentRef
- DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test);
-}</programlisting>
-<para>
- The message would then refer to the attachment part by CID:
-</para>
-<programlisting role="XML"><env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
- <env:Header/>
- <env:Body>
- <ns2:parameterAnnotation xmlns:ns2='http://swaref.samples.jaxws.ws.test.jboss.org/'>
- <arg0>cid:0-1180017772935-32455963 at ws.jboss.org</arg0>
- <arg1>Wrapped test</arg1>
- </ns2:parameterAnnotation>
- </env:Body>
-</env:Envelope></programlisting>
-
-
-
-</section>
-<section><title>MTOM/XOP</title>
-<para>
- This chapter describes Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP), a means of more efficiently serializing XML Infosets that have certain types of content. The related specifications are:
-</para>
- <itemizedlist>
- <listitem>
- <para>
- <ulink url="http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission Optimization Mechanism (MTOM)</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging (XOP)</ulink>
- </para>
- </listitem>
- </itemizedlist>
-<table frame="all"><title>Supported MTOM parameter types</title>
- <tgroup cols="2"><tbody>
- <row>
- <entry>
- <para>image/jpeg </para>
- </entry>
- <entry>
- <para>java.awt.Image </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>text/xml </para>
- </entry>
- <entry>
- <para>javax.xml.transform.Source </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>application/xml </para>
- </entry>
- <entry>
- <para>javax.xml.transform.Source </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>application/octet-stream </para>
- </entry>
- <entry>
- <para>javax.activation.DataHandler </para>
- </entry>
- </row></tbody></tgroup>
-</table>
-<para>
- The above table shows a list of supported endpoint parameter types. The recommended approach is to use the javax.activation.DataHandler classes to represent binary data as service endpoint parameters.
-</para>
-
- <note><para>Microsoft endpoints tend to send any data as application/octet-stream. The only Java type that can easily cope with this ambiguity is javax.activation.DataHandler</para></note>
-
-</section>
-
- <section><title>Enabling MTOM per endpoint</title>
- <para>On the server side MTOM processing is enabled through the @BindingType annotation. JBossWS does handle SOAP1.1 and SOAP1.2. Both come with or without MTOM flavours: MTOM enabled service implementations</para>
-
-<programlisting role="JAVA">package org.jboss.test.ws.jaxws.samples.xop.doclit;
-
-import javax.ejb.Remote;
-import javax.jws.WebService;
-import javax.jws.soap.SOAPBinding;
-import javax.xml.ws.BindingType;
-
- at Remote
- at WebService(targetNamespace = "http://org.jboss.ws/xop/doclit")
- at SOAPBinding(style = SOAPBinding.Style.DOCUMENT, parameterStyle = SOAPBinding.ParameterStyle.BARE)
- at BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true") (1)
-public interface MTOMEndpoint
-{
-[...]
-}</programlisting>
-
-
-
-<section><title>The MTOM enabled SOAP 1.1 binding ID</title>
-<para>
- MTOM enabled clients
-</para>
- <para>
- Web service clients can use the same approach described above or rely on the Binding API to enable MTOM (Excerpt taken from the <literal>org.jboss.test.ws.jaxws.samples.xop.doclit.XOPTestCase</literal>):
- </para>
-
-<programlisting role="JAVA">[...]
-Service service = Service.create(wsdlURL, serviceName);
-port = service.getPort(MTOMEndpoint.class);
-
-// enable MTOM
-binding = (SOAPBinding)((BindingProvider)port).getBinding();
-binding.setMTOMEnabled(true);
-</programlisting>
-
-</section>
-
-<!--<para> to do list</para>
-<para>- JBoss Web Services 2.0.3.GA</para>
-<para>- Attachment Support with XOP and SwA</para>
-<para>- JMS Transport </para>
-<para>- WS-Addressing</para>
-<para>- WS-Security </para>
-<para>- WS-Policy </para>
-<para>- WS-Eventing</para>-->
-
-</section>
-
<section><title>Document/Literal</title>
<para>
With document style web services two business partners agree on the exchange of complex business documents that are well defined in XML schema. For example, one party sends a document describing a purchase order, the other responds (immediately or later) with a document that describes the status of the purchase order. The payload of the SOAP message is an XML document that can be validated against XML schema. The document is defined by the style attribute on the SOAP binding.
@@ -658,7 +477,7 @@
</section>
<section>
<title>Dynamic Proxy</title>
- <para>You can create an instance of a client proxy using one of <methodname>getPort</methodname> methods on the <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Service"><classname>Service</classname></ulink>.</para>
+ <para>You can create an instance of a client proxy using one of <methodname>getPort</methodname> methods on the <ulink url="http://java.sun.com/javaee/5/docs/api/javax/xml/ws/Service.html"><classname>Service</classname></ulink>.</para>
<programlisting role="JAVA">
/**
* The getPort method returns a proxy. A service client
@@ -812,17 +631,6 @@
<section>
<title>Asynchronous Invocations</title>
<para>The <classname>BindingProvider</classname> interface represents a component that provides a protocol binding for use by clients, it is implemented by proxies and is extended by the <classname>Dispatch</classname> interface.</para>
-
- <!--<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Image:Binding-provider.gif">
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="./http://jbws.dyndns.org/mediawiki/images/3/3e/Binding-provider.gif" format="GIF"/>
- </imageobject>
- </inlinemediaobject>
- </ulink>
- </para>-->
-
<para><classname>BindingProvider</classname> instances may provide asynchronous operation capabilities. When used, asynchronous operation invocations are decoupled from the <classname>BindingProvider</classname> instance at invocation time such that the response context is not updated when the operation completes. Instead a separate response context is made available using the <classname>Response</classname> interface.</para>
<programlisting role="JAVA">
@@ -876,17 +684,6 @@
<para>The handler framework is implemented by a JAX-WS protocol binding in both client and server side runtimes. Proxies, and Dispatch instances, known collectively as binding providers, each use protocol bindings to bind their abstract functionality to specific protocols.</para>
<para>Client and server-side handlers are organized into an ordered list known as a handler chain. The handlers within a handler chain are invoked each time a message is sent or received. Inbound messages are processed by handlers prior to binding provider processing. Outbound messages are processed by handlers after any binding provider processing.</para>
<para>Handlers are invoked with a message context that provides methods to access and modify inbound and outbound messages and to manage a set of properties. Message context properties may be used to facilitate communication between individual handlers and between handlers and client and service implementations. Different types of handlers are invoked with different types of message context.</para>
-
- <!--<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Image:Binding-handler.gif">
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="./http://jbws.dyndns.org/mediawiki/images/0/07/Binding-handler.gif" format="GIF"/>
- </imageobject>
- </inlinemediaobject>
- </ulink>
- </para>-->
-
<section>
<title>Logical Handler</title>
<para>Handlers that only operate on message context properties and message payloads. Logical handlers are protocol agnostic and are unable to affect protocol specific parts of a message. Logical handlers are handlers that implement <classname>javax.xml.ws.handler.LogicalHandler</classname>.</para>
@@ -995,6 +792,197 @@
</section>
</section>
<section>
+ <title>Attachments</title>
+ <para>
+ JBoss-WS4EE relied on a deprecated attachments technology called SwA (SOAP with Attachments). SwA required soap/encoding which is disallowed by the WS-I Basic Profile. JBossWS provides support for WS-I AP 1.0, and MTOM instead.
+ </para>
+ <section>
+ <title>MTOM/XOP</title>
+ <para>This section describes Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP), a means of more efficiently serializing XML Infosets that have certain types of content. The related specifications are</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission Optimization Mechanism (MTOM)</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging (XOP)</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Supported MTOM parameter types</title>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="50*"/>
+ <colspec colname="c2" colwidth="50*"/>
+ <tbody>
+ <row>
+ <entry>
+ <para> image/jpeg</para>
+ </entry>
+ <entry>
+ <para> java.awt.Image</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> text/xml</para>
+ </entry>
+ <entry>
+ <para> javax.xml.transform.Source</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> application/xml</para>
+ </entry>
+ <entry>
+ <para> javax.xml.transform.Source</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> application/octet-stream</para>
+ </entry>
+ <entry>
+ <para> javax.activation.DataHandler</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>The above table shows a list of supported endpoint parameter types. The recommended approach is to use the <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/activation/DataHandler.html">javax.activation.DataHandler</ulink> classes to represent binary data as service endpoint parameters.</para>
+ <para>
+ <note><title>Note</title>
+
+ <para>Microsoft endpoints tend to send any data as application/octet-stream. The only Java type that can easily cope with this ambiguity is javax.activation.DataHandler</para>
+ </note>
+ </para>
+ </section>
+ <section>
+ <title>Enabling MTOM per endpoint</title>
+ <para>On the server side MTOM processing is enabled through the <literal>@BindingType</literal> annotation. JBossWS does handle SOAP1.1 and SOAP1.2. Both come with or without MTOM flavours:</para>
+ <para>
+ <emphasis role="bold">MTOM enabled service implementations</emphasis>
+ </para>
+<programlisting role="JAVA">
+package org.jboss.test.ws.jaxws.samples.xop.doclit;
+
+import javax.ejb.Remote;
+import javax.jws.WebService;
+import javax.jws.soap.SOAPBinding;
+import javax.xml.ws.BindingType;
+
+ at Remote
+ at WebService(targetNamespace = "http://org.jboss.ws/xop/doclit")
+ at SOAPBinding(style = SOAPBinding.Style.DOCUMENT, parameterStyle = SOAPBinding.ParameterStyle.BARE)
+ at BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true") (1)
+public interface MTOMEndpoint
+{
+...
+}</programlisting>
+ <orderedlist>
+ <listitem>
+ <para>The MTOM enabled SOAP 1.1 binding ID</para>
+ </listitem>
+ </orderedlist>
+ <para>
+ <emphasis role="bold">MTOM enabled clients</emphasis>
+ </para>
+ <para>Web service clients can use the same approach described above or rely on the <literal>Binding</literal> API to enable MTOM (Excerpt taken from the <literal>org.jboss.test.ws.jaxws.samples.xop.doclit.XOPTestCase</literal>):</para>
+<programlisting role="JAVA">
+...
+Service service = Service.create(wsdlURL, serviceName);
+port = service.getPort(MTOMEndpoint.class);
+
+// enable MTOM
+binding = (SOAPBinding)((BindingProvider)port).getBinding();
+binding.setMTOMEnabled(true);
+</programlisting>
+ <para>
+ <note><title>Note</title>
+
+ <para>You might as well use the JBossWS configuration templates to setup deployment defaults.</para>
+ </note>
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>SwaRef</title>
+ <para><ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">WS-I Attachment Profile 1.0</ulink> defines mechanism to reference MIME attachment parts using <ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html#Referencing_Attachments_from_the_SOAP_Envelope">swaRef</ulink>. In this mechanism the content of XML element of type wsi:swaRef is sent as MIME attachment and the element inside SOAP Body holds the reference to this attachment in the CID URI scheme as defined by <ulink url="http://www.ietf.org/rfc/rfc2111.txt">RFC 2111</ulink>.</para>
+ <section>
+ <title>Using SwaRef with JAX-WS endpoints</title>
+ <para>JAX-WS endpoints delegate all marshalling/unmarshalling to the JAXB API. The most simple way to enable SwaRef encoding for <literal>DataHandler</literal> types is to annotate a payload bean with the <literal>@XmlAttachmentRef</literal> annotation as shown below:</para>
+<programlisting role="JAVA">
+/**
+ * Payload bean that will use SwaRef encoding
+ */
+ at XmlRootElement
+public class DocumentPayload
+{
+ private DataHandler data;
+
+ public DocumentPayload()
+ {
+ }
+
+ public DocumentPayload(DataHandler data)
+ {
+ this.data = data;
+ }
+
+ @XmlElement
+ @XmlAttachmentRef
+ public DataHandler getData()
+ {
+ return data;
+ }
+
+ public void setData(DataHandler data)
+ {
+ this.data = data;
+ }
+}</programlisting>
+ <para>With document wrapped endpoints you may even specify the <literal>@XmlAttachmentRef</literal> annotation on the service endpoint interface:</para>
+<programlisting role="JAVA">
+ at WebService
+public interface DocWrappedEndpoint
+{
+ @WebMethod
+ DocumentPayload beanAnnotation(DocumentPayload dhw, String test);
+
+ @WebMethod
+ @XmlAttachmentRef
+ DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test);
+
+}</programlisting>
+ <para>The message would then refer to the attachment part by CID:</para>
+<programlisting role="XML">
+<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns2:parameterAnnotation xmlns:ns2='http://swaref.samples.jaxws.ws.test.jboss.org/'>
+ <arg0>cid:0-1180017772935-32455963 at ws.jboss.org</arg0>
+ <arg1>Wrapped test</arg1>
+ </ns2:parameterAnnotation>
+ </env:Body>
+</env:Envelope>
+</programlisting>
+ </section>
+ <section>
+ <title>Starting from WSDL</title>
+ <para>If you chose the contract first approach then you need to ensure that any element declaration that should use SwaRef encoding simply refers to wsi:swaRef schema type:</para>
+<programlisting role="XML">
+<element name="data" type="wsi:swaRef"
+xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"/>
+</programlisting>
+ <para>Any wsi:swaRef schema type would then be mapped to DataHandler.</para>
+ </section>
+ </section>
+ </section>
+ <section>
<title>Tools</title>
<para>The JAX-WS tools provided by JBossWS can be used in a variety of ways. First we will look at server-side development strategies, and then proceed to the client. When developing a Web Service Endpoint (the server-side) you have the option of starting from Java (bottom-up development), or from the abstact contract (WSDL) that defines your service (top-down development). If this is a new service (no existing contract), the bottom-up approach is the fastest route; you only need to add a few annotations to your classes to get a service up and running. However, if you are developing a service with an already defined contract, it is far simpler to use the top-down approach, since the provided tool will generate the annotated code for you.</para>
<para>Bottom-up use cases:</para>
@@ -1444,7 +1432,7 @@
<para>This section describes how <ulink url="http://www.w3.org/TR/ws-addr-core">WS-Addressing</ulink> can be used to provide a staful service endpoint.</para>
<section>
<title>Specifications</title>
- <para>WS-Addressing is defined by a combination of the following specifications from the W3C Candidate Recommendation 17 August 2005. The WS-Addressing API is standardized by <ulink url="http://www.jcp.org/en/jsr/detail?id=261">JSR-261 - Java API for XML Web Services Addressing</ulink></para>
+ <para>WS-Addressing is defined by a combination of the following specifications from the W3C Recommendation. The WS-Addressing API is standardized by <ulink url="http://www.jcp.org/en/jsr/detail?id=224">JSR-224 - Java API for XML-Based Web Services (JAX-WS)</ulink></para>
<itemizedlist>
<listitem>
<para>
@@ -1468,19 +1456,19 @@
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class StatefulEndpointImpl implements StatefulEndpoint, ServiceLifecycle
{
- at WebMethod
-public void addItem(String item)
-{ ... }
+ @WebMethod
+ public void addItem(String item)
+ { ... }
- at WebMethod
-public void checkout()
-{ ... }
+ @WebMethod
+ public void checkout()
+ { ... }
- at WebMethod
-public String getItems()
-{ ... }
+ @WebMethod
+ public String getItems()
+ { ... }
}</programlisting>
- <para>It uses the <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Endpoint_Configuration#_Standard_WSAddressing_Endpoint">JAX-WS Endpoint Configuration# Standard WSAddressing Endpoint</ulink> to enable the server side addressing handler. It processes the incomming WS-Addressing header elements and provides access to them through the JSR-261 API.</para>
+ <para>It uses the <ulink url="http://www.jboss.org/community/wiki/JBossWS-NativeUserGuide#Addressing_Endpoint">JAX-WS Endpoint Configuration# Standard WSAddressing Endpoint</ulink> to enable the server side addressing handler. It processes the incomming WS-Addressing header elements and provides access to them through the JSR-261 API.</para>
<para>The endpoint handler chain</para>
<programlisting role="XML">
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1645,10 +1633,10 @@
</itemizedlist>
<section>
<title>Endpoint configuration</title>
- <para>JBossWS uses handlers to identify ws-security encoded requests and invoke the security components to sign and encrypt messages. In order to enable security processing, the client and server side need to include a corressponding handler configuration. The preferred way is to reference a predefined <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Endpoint_Configuration">JAX-WS Endpoint Configuration</ulink> or <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Client_Configuration">JAX-WS Client Configuration</ulink> respectively.</para>
+ <para>JBossWS uses handlers to identify ws-security encoded requests and invoke the security components to sign and encrypt messages. In order to enable security processing, the client and server side need to include a corressponding handler configuration. The preferred way is to reference a predefined <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSEndpointConfiguration">JAX-WS Endpoint Configuration</ulink> or <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSClientConfiguration">JAX-WS Client Configuration</ulink> respectively.</para>
<para>
<note><title>Note</title>
- <para>You need to setup both the endpoint configuration and the WSSE declarations. That's two separate steps.</para>
+ <para>You need to setup both the endpoint configuration and the WSSE declarations i. e. two separate steps.</para>
</note>
</para>
</section>
@@ -1665,11 +1653,11 @@
(3) <trust-store-file>WEB-INF/wsse.truststore</trust-store-file>
(4) <trust-store-password>jbossws</trust-store-password>
(5) <config>
-(6) <sign type="x509v3" alias="wsse"/>
-(7) <requires>
-(8) <signature/>
-</requires>
-</config>
+(6) <sign type="x509v3" alias="wsse"/>
+(7) <requires>
+(8) <signature/>
+ </requires>
+ </config>
</jboss-ws-security>
</programlisting>
<orderedlist>
@@ -1689,7 +1677,7 @@
<para> Here we start our root config block. The root config block is the default configuration for all services in this war file.</para>
</listitem>
<listitem>
- <para> This means that the server must sign the message body of all responses. Type means that we are to use a X.509v3 certificate (a standard certificate). The alias option says that the certificate and key pair to use for signing is in the key store under the "wsse" alias</para>
+ <para> This means that the server must sign the message body of all responses. Type means that we are using X.509v3 certificate (a standard certificate). The alias option says that the certificate and key pair to use for signing is in the key store under the "wsse" alias</para>
</listitem>
<listitem>
<para> Here we start our optional requires block. This block specifies all security requirements that must be met when the server receives a message.</para>
@@ -1698,7 +1686,7 @@
<para> This means that all web services in this war file require the message body to be signed.</para>
</listitem>
</orderedlist>
- <para>By default an endpoint does not use the WS-Security configuration. Use the proprietary @EndpointConfig annotation to set the config name. See <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Endpoint_Configuration">JAX-WS_Endpoint_Configuration</ulink> for the list of available config names.</para>
+ <para>By default an endpoint does not use the WS-Security configuration. Users can use proprietary <literal>@EndpointConfig</literal> annotation to set the config name. See <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSEndpointConfiguration">JAX-WS_Endpoint_Configuration</ulink> for the list of available config names.</para>
<programlisting role="JAVA">
@WebService
@EndpointConfig(configName = "Standard WSSecurity Endpoint")
@@ -1716,11 +1704,11 @@
xsi:schemaLocation="http://www.jboss.com/ws-security/config
http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
(1) <config>
-(2) <sign type="x509v3" alias="wsse"/>
-(3) <requires>
-(4) <signature/>
-</requires>
-</config>
+(2) <sign type="x509v3" alias="wsse"/>
+(3) <requires>
+(4) <signature/>
+ </requires>
+ </config>
</jboss-ws-security>
</programlisting>
<orderedlist>
@@ -1754,7 +1742,7 @@
<para>
<emphasis role="bold">SOAP message exchange</emphasis>
</para>
- <para>Below you see the incomming SOAP message with the details of the security headers ommited. The idea is, that the SOAP body is still plain text, but it is signed in the security header and can therefore not manipulated in transit.</para>
+ <para>Below you see the incomming SOAP message with the details of the security headers ommited. The idea is, that the SOAP body is still plain text, but it is signed in the security header and therefore can not be manipulated in transit.</para>
<para>Incomming SOAPMessage</para>
<programlisting role="XML">
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
@@ -1782,7 +1770,7 @@
</section>
</section>
<section>
- <title>Installing the BouncyCastle JCE provider (JDK 1.4)</title>
+ <title>Installing the BouncyCastle JCE provider</title>
<para>The information below has originaly been provided by <ulink url="http://www.bouncycastle.org/specifications.html#install">The Legion of the Bouncy Castle</ulink>.</para>
<para>The provider can be configured as part of your environment via static registration by adding an entry to the <filename>java.security</filename> properties file (found in <filename>$JAVA_HOME/jre/lib/security/java.security</filename>, where <filename>$JAVA_HOME</filename> is the location of your JDK and JRE distribution). You will find detailed instructions in the file but basically it comes down to adding a line:</para>
<programlisting> <![CDATA[
@@ -1795,25 +1783,12 @@
<para>Issues may arise if the Sun provided providers are not first.</para>
</note>
</para>
- <para>Where you put the jar is mostly up to you, although with jdk1.4 the best (and in some cases only) place to have it is in <filename>$JAVA_HOME/jre/lib/ext</filename>. Under Windows there will normally be a JRE and a JDK install of Java if you think you have installed it correctly and it still doesn't work chances are you have added the provider to the installation not being used.</para>
+ <para>Where users will put the provider jar is mostly up to them, although with jdk5 the best (and in some cases only) place to have it is in <filename>$JAVA_HOME/jre/lib/ext</filename>. Under Windows there will normally be a JRE and a JDK install of Java. If user think he have installed it correctly and it still doesn't work then with high probability the provider installation is not used.</para>
</section>
- <section>
- <title>Keystore, truststore - What?</title>
- <para>
- <note><title>Note</title>
- <para>If you having a hard time understanding how the different trust- and keystore configurations are used for signature and encryption, then read this thread first: <ulink url="http://www.jboss.org/index.html?module=bb&op=viewtopic&t=94406"/></para>
- </note>
- </para>
-
- </section>
</section>
<section>
- <title>WS-Transaction</title>
- <para>Support for the WS-Coordination, WS-AtomicTransaction and WS-BusinessActivity specifications will be provided by technology recently acquired from Arjuna Technologies Ltd. This technology will be present within the JBoss Transactions 4.2.1 release. Further information can be obtained from the <ulink url="http://labs.jboss.org/portal/jbosstm">JBoss Transactions Project</ulink></para>
- </section>
- <section>
<title>XML Registries</title>
- <para>J2EE 1.4 mandates support for Java API for XML Registries (JAXR). Inclusion of a XML Registry with the J2EE 1.4 certified Application Server is optional. Starting jboss-4.0.2, JBoss ships a UDDI v2.0 compliant registry, the Apache jUDDI registry. We also provide support for JAXR Capability Level 0 (UDDI Registries) via integration of Apache Scout.</para>
+ <para>J2EE 5.0 mandates support for Java API for XML Registries (JAXR). Inclusion of a XML Registry with the J2EE 5.0 certified Application Server is optional. JBoss EAP5 ships a UDDI v2.0 compliant registry, the Apache jUDDI registry. We also provide support for JAXR Capability Level 0 (UDDI Registries) via integration of Apache Scout.</para>
<para>This chapter describes how to configure the jUDDI registry in JBoss and some sample code outlines for using JAXR API to publish and query the jUDDI registry.</para>
<section>
<title>Apache jUDDI Configuration</title>
@@ -1821,17 +1796,17 @@
<para>Let us look at the individual configuration items that can be changed.</para>
<para>DataSources configuration</para>
<programlisting role="XML">
-<!-- Datasource to Database-->
-<attribute name="DataSourceUrl">java:/DefaultDS</attribute>
+<!-- Datasource to Database -->
+<attribute name="DataSourceUrl">java:/DefaultDS</attribute>
</programlisting>
<para>Database Tables (Should they be created on start, Should they be dropped on stop, Should they be dropped on start etc)</para>
<programlisting role="XML">
<!-- Should all tables be created on Start-->
- <attribute name="CreateOnStart">false</attribute>
- <!-- Should all tables be dropped on Stop-->
- <attribute name="DropOnStop">true</attribute>
- <!-- Should all tables be dropped on Start-->
- <attribute name="DropOnStart">false</attribute>
+<attribute name="CreateOnStart">false</attribute>
+<!-- Should all tables be dropped on Stop-->
+<attribute name="DropOnStop">true</attribute>
+<!-- Should all tables be dropped on Start-->
+<attribute name="DropOnStart">false</attribute>
</programlisting>
<para>JAXR Connection Factory to be bound in JNDI. (Should it be bound? and under what name?)</para>
<programlisting role="XML"><!-- Should I bind a Context to which JaxrConnectionFactory bound-->
@@ -1858,7 +1833,7 @@
javax.xml.registry.ConnectionFactoryClass=org.apache.ws.scout.registry.ConnectionFactoryImpl
jaxr.query.url=http://localhost:8080/juddi/inquiry
jaxr.publish.url=http://localhost:8080/juddi/publish
-juddi.proxy.transportClass=org.jboss.jaxr.juddi.transport.SaajTransport
+scout.proxy.transportClass=org.jboss.jaxr.scout.transport.SaajTransport
]]> </programlisting>
<para>Please remember to change the hostname from "localhost" to the hostname of the UDDI service/JBoss Server.</para>
<para>You can pass the System Properties to the JVM in the following ways:</para>
@@ -1879,13 +1854,13 @@
<para>There are two categories of API: JAXR Publish API and JAXR Inquiry API. The important JAXR interfaces that any JAXR client code will use are the following.</para>
<itemizedlist>
<listitem>
- <para> <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/RegistryService.html">javax.xml.registry.RegistryService</ulink> From J2EE 1.4 JavaDoc: "This is the principal interface implemented by a JAXR provider. A registry client can get this interface from a Connection to a registry. It provides the methods that are used by the client to discover various capability specific interfaces implemented by the JAXR provider."</para>
+ <para> <ulink url="http://java.sun.com/javaee/5/docs/api/javax/xml/registry/RegistryService.html">javax.xml.registry.RegistryService</ulink> From J2EE 5.0 JavaDoc: "This is the principal interface implemented by a JAXR provider. A registry client can get this interface from a Connection to a registry. It provides the methods that are used by the client to discover various capability specific interfaces implemented by the JAXR provider."</para>
</listitem>
<listitem>
- <para> <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/BusinessLifeCycleManager.html">javax.xml.registry.BusinessLifeCycleManager</ulink> From J2EE 1.4 JavaDoc: "The <classname>BusinessLifeCycleManager</classname> interface, which is exposed by the Registry Service, implements the life cycle management functionality of the Registry as part of a business level API. There is no authentication information provided, because the Connection interface keeps that state and context on behalf of the client."</para>
+ <para> <ulink url="http://java.sun.com/javaee/5/docs/api/javax/xml/registry/BusinessLifeCycleManager.html">javax.xml.registry.BusinessLifeCycleManager</ulink> From J2EE 5.0 JavaDoc: "The <classname>BusinessLifeCycleManager</classname> interface, which is exposed by the Registry Service, implements the life cycle management functionality of the Registry as part of a business level API. There is no authentication information provided, because the Connection interface keeps that state and context on behalf of the client."</para>
</listitem>
<listitem>
- <para> <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/BusinessQueryManager.html">javax.xml.registry.BusinessQueryManager</ulink> From J2EE 1.4 JavaDoc: "The <classname>BusinessQueryManager</classname> interface, which is exposed by the Registry Service, implements the business style query interface. It is also referred to as the focused query interface."</para>
+ <para> <ulink url="http://java.sun.com/javaee/5/docs/api/javax/xml/registry/BusinessQueryManager.html">javax.xml.registry.BusinessQueryManager</ulink> From J2EE 5.0 JavaDoc: "The <classname>BusinessQueryManager</classname> interface, which is exposed by the Registry Service, implements the business style query interface. It is also referred to as the focused query interface."</para>
</listitem>
</itemizedlist>
<para>Let us now look at some of the common programming tasks performed while using the JAXR API:</para>
@@ -1898,8 +1873,8 @@
props.setProperty("javax.xml.registry.queryManagerURL", queryurl);
props.setProperty("javax.xml.registry.lifeCycleManagerURL", puburl);
-String transportClass = System.getProperty("juddi.proxy.transportClass", "org.jboss.jaxr.juddi.transport.SaajTransport");
-System.setProperty("juddi.proxy.transportClass", transportClass);
+String transportClass = System.getProperty("scout.proxy.transportClass", "org.jboss.jaxr.scout.transport.SaajTransport");
+System.setProperty("scout.proxy.transportClass", transportClass);
// Create the connection, passing it the configuration properties
factory = ConnectionFactory.newInstance();
@@ -1909,124 +1884,124 @@
<para>Authentication with the registry.</para>
<programlisting role="JAVA">
/**
-* Does authentication with the uddi registry
-*/
+ * Does authentication with the uddi registry
+ */
protected void login() throws JAXRException
{
-PasswordAuthentication passwdAuth = new PasswordAuthentication(userid, passwd.toCharArray());
-Set creds = new HashSet();
-creds.add(passwdAuth);
+ PasswordAuthentication passwdAuth = new PasswordAuthentication(userid, passwd.toCharArray());
+ Set creds = new HashSet();
+ creds.add(passwdAuth);
-connection.setCredentials(creds);
+ connection.setCredentials(creds);
}
</programlisting>
<para>Save a Business</para>
<programlisting role="JAVA">
/**
-* Creates a Jaxr Organization with 1 or more services
-*/
+ * Creates a Jaxr Organization with 1 or more services
+ */
protected Organization createOrganization(String orgname) throws JAXRException
{
-Organization org = blm.createOrganization(getIString(orgname));
-org.setDescription(getIString("JBoss Inc"));
-Service service = blm.createService(getIString("JBOSS JAXR Service"));
-service.setDescription(getIString("Services of XML Registry"));
-//Create serviceBinding
-ServiceBinding serviceBinding = blm.createServiceBinding();
-serviceBinding.setDescription(blm.createInternationalString("Test Service Binding"));
+ Organization org = blm.createOrganization(getIString(orgname));
+ org.setDescription(getIString("JBoss Inc"));
+ Service service = blm.createService(getIString("JBOSS JAXR Service"));
+ service.setDescription(getIString("Services of XML Registry"));
+ //Create serviceBinding
+ ServiceBinding serviceBinding = blm.createServiceBinding();
+ serviceBinding.setDescription(blm.createInternationalString("Test Service Binding"));
-//Turn validation of URI off
-serviceBinding.setValidateURI(false);
-serviceBinding.setAccessURI("http://testjboss.org");
-..
-// Add the serviceBinding to the service
-service.addServiceBinding(serviceBinding);
+ //Turn validation of URI off
+ serviceBinding.setValidateURI(false);
+ serviceBinding.setAccessURI("http://testjboss.org");
+ ...
+ // Add the serviceBinding to the service
+ service.addServiceBinding(serviceBinding);
-User user = blm.createUser();
-org.setPrimaryContact(user);
-PersonName personName = blm.createPersonName("Anil S");
-TelephoneNumber telephoneNumber = blm.createTelephoneNumber();
-telephoneNumber.setNumber("111-111-7777");
-telephoneNumber.setType(null);
-PostalAddress address = blm.createPostalAddress("111", "My Drive", "BuckHead", "GA", "USA", "1111-111", "");
-Collection postalAddresses = new ArrayList();
-postalAddresses.add(address);
-Collection emailAddresses = new ArrayList();
-EmailAddress emailAddress = blm.createEmailAddress("anil at apache.org");
-emailAddresses.add(emailAddress);
+ User user = blm.createUser();
+ org.setPrimaryContact(user);
+ PersonName personName = blm.createPersonName("Anil S");
+ TelephoneNumber telephoneNumber = blm.createTelephoneNumber();
+ telephoneNumber.setNumber("111-111-7777");
+ telephoneNumber.setType(null);
+ PostalAddress address = blm.createPostalAddress("111", "My Drive", "BuckHead", "GA", "USA", "1111-111", "");
+ Collection postalAddresses = new ArrayList();
+ postalAddresses.add(address);
+ Collection emailAddresses = new ArrayList();
+ EmailAddress emailAddress = blm.createEmailAddress("anil at apache.org");
+ emailAddresses.add(emailAddress);
-Collection numbers = new ArrayList();
-numbers.add(telephoneNumber);
-user.setPersonName(personName);
-user.setPostalAddresses(postalAddresses);
-user.setEmailAddresses(emailAddresses);
-user.setTelephoneNumbers(numbers);
+ Collection numbers = new ArrayList();
+ numbers.add(telephoneNumber);
+ user.setPersonName(personName);
+ user.setPostalAddresses(postalAddresses);
+ user.setEmailAddresses(emailAddresses);
+ user.setTelephoneNumbers(numbers);
-ClassificationScheme cScheme = getClassificationScheme("ntis-gov:naics", "");
-Key cKey = blm.createKey("uuid:C0B9FE13-324F-413D-5A5B-2004DB8E5CC2");
-cScheme.setKey(cKey);
-Classification classification = blm.createClassification(cScheme, "Computer Systems Design and Related Services", "5415");
-org.addClassification(classification);
-ClassificationScheme cScheme1 = getClassificationScheme("D-U-N-S", "");
-Key cKey1 = blm.createKey("uuid:3367C81E-FF1F-4D5A-B202-3EB13AD02423");
-cScheme1.setKey(cKey1);
-ExternalIdentifier ei = blm.createExternalIdentifier(cScheme1, "D-U-N-S number", "08-146-6849");
-org.addExternalIdentifier(ei);
-org.addService(service);
-return org;
+ ClassificationScheme cScheme = getClassificationScheme("ntis-gov:naics", "");
+ Key cKey = blm.createKey("uuid:C0B9FE13-324F-413D-5A5B-2004DB8E5CC2");
+ cScheme.setKey(cKey);
+ Classification classification = blm.createClassification(cScheme, "Computer Systems Design and Related Services", "5415");
+ org.addClassification(classification);
+ ClassificationScheme cScheme1 = getClassificationScheme("D-U-N-S", "");
+ Key cKey1 = blm.createKey("uuid:3367C81E-FF1F-4D5A-B202-3EB13AD02423");
+ cScheme1.setKey(cKey1);
+ ExternalIdentifier ei = blm.createExternalIdentifier(cScheme1, "D-U-N-S number", "08-146-6849");
+ org.addExternalIdentifier(ei);
+ org.addService(service);
+
+ return org;
}
</programlisting>
<para>Query a Business</para>
<programlisting role="JAVA">
/**
-* Locale aware Search a business in the registry
-*/
+ * Locale aware Search a business in the registry
+ */
public void searchBusiness(String bizname) throws JAXRException
{
-try
-{
-// Get registry service and business query manager
-this.getJAXREssentials();
+ try
+ {
+ // Get registry service and business query manager
+ this.getJAXREssentials();
-// Define find qualifiers and name patterns
-Collection findQualifiers = new ArrayList();
-findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC);
-Collection namePatterns = new ArrayList();
-String pattern = "%" + bizname + "%";
-LocalizedString ls = blm.createLocalizedString(Locale.getDefault(), pattern);
-namePatterns.add(ls);
+ // Define find qualifiers and name patterns
+ Collection findQualifiers = new ArrayList();
+ findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC);
+ Collection namePatterns = new ArrayList();
+ String pattern = "%" + bizname + "%";
+ LocalizedString ls = blm.createLocalizedString(Locale.getDefault(), pattern);
+ namePatterns.add(ls);
-// Find based upon qualifier type and values
-BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null);
+ // Find based upon qualifier type and values
+ BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null);
-// check how many organisation we have matched
-Collection orgs = response.getCollection();
-if (orgs == null)
-{
-log.debug(" -- Matched 0 orgs");
+ // check how many organisation we have matched
+ Collection orgs = response.getCollection();
+ if (orgs == null)
+ {
+ log.debug(" -- Matched 0 orgs");
+ }
+ else
+ {
+ log.debug(" -- Matched " + orgs.size() + " organizations -- ");
+ // then step through them
+ for (Iterator orgIter = orgs.iterator(); orgIter.hasNext();)
+ {
+ Organization org = (Organization)orgIter.next();
+ log.debug("Org name: " + getName(org));
+ log.debug("Org description: " + getDescription(org));
+ log.debug("Org key id: " + getKey(org));
+ checkUser(org);
+ checkServices(org);
+ }
+ }
+ }
+ finally
+ {
+ connection.close();
+ }
}
-else
-{
-log.debug(" -- Matched " + orgs.size() + " organizations -- ");
-
-// then step through them
-for (Iterator orgIter = orgs.iterator(); orgIter.hasNext();)
-{
-Organization org = (Organization)orgIter.next();
-log.debug("Org name: " + getName(org));
-log.debug("Org description: " + getDescription(org));
-log.debug("Org key id: " + getKey(org));
-checkUser(org);
-checkServices(org);
-}
-}
-}
-finally
-{
-connection.close();
-}
-}
</programlisting>
<para>For more examples of code using the JAXR API, please refer to the resources in the Resources Section.</para>
</section>
@@ -2040,7 +2015,7 @@
<para><emphasis role="bold">I cannot connect to the jUDDI registry.</emphasis> Please check the jUDDI configuration and see if there are any errors in the server.log. And also remember that the jUDDI registry is available only in the "all" configuration.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">I cannot authenticate to the jUDDI registry.</emphasis>Have you added an authorized user to the jUDDI database, as described earlier in the chapter?</para>
+ <para><emphasis role="bold">I cannot authenticate to the jUDDI registry.</emphasis> Have you added an authorized user to the jUDDI database, as described earlier in the chapter?</para>
</listitem>
<listitem>
<para><emphasis role="bold">I would like to view the SOAP messages in transit between the client and the UDDI Registry.</emphasis> Please use the tcpmon tool to view the messages in transit. <ulink url="http://tcpmon.dev.java.net/">TCPMon</ulink></para>
@@ -2068,291 +2043,133 @@
</itemizedlist>
</section>
</section>
- <section>
- <title>WS-Policy</title>
- <para>Since 2.1</para>
- <para>The Web Services Policy Framework (WS-Policy) provides a general purpose model and corresponding syntax to describe the policies of a Web Service.</para>
- <para>WS-Policy defines a base set of constructs that can be used and extended by other Web services specifications to describe a broad range of service requirements and capabilities.</para>
- <para>Current JBoss implementations can instrument a webservice with policies attached at endpoint, port or port-type scope level only. There are two different methods to attach policies: providing a wsdl decorated with policies and policy attachments as defined by specifications, or using JBoss proprietary annotations. The first way has the advantage of being standard, while the second one is much more simple to implement. Of course the wsdl generated by these annotations conforms to standard defined in specifications and can be used with any ws-policy compliant client.</para>
- <para>ws-policy specifications only define policy requirements and their attachment method to wsdl through specific extensions. It is out of the scope of ws-policy specifications and thus implementation to define and use the content of assertions. The way these assertions (called domain assertions or domain policies) have to be deployed and used is left to other specification like WS-Security-Policy or more generally to domain specific implementation.</para>
- <section>
- <title>Specification</title>
- <para>WS-Policy is defined by the combination of the following specifications:</para>
-<programlisting> <![CDATA[
-* <ulink url="http://www.w3.org/Submission/WS-Policy/"> WS-Policy specification</ulink>
-* <ulink url="http://www.w3.org/Submission/WS-PolicyAttachment/"> WS-Policy-Attachment specification</ulink>
- ]]> </programlisting>
- </section>
- <section>
- <title>Using policies in a user provided WSDL</title>
- <para>To attach policies in this manner, the only thing you have to do in a webservice class is to provide a custom wsdl. This will cause JBossws to skip wsdl generation at deploy time, since the wsdl file you provided will be published. Please refer to specification (WS-Policy-Attachment) to learn how to modify wsdl to attach a policy.</para>
- <para>Here you find an example of a webservice class and provided wsdl with a policy containing a domain assertion for JBoss WS-Security.</para>
-<programlisting role="JAVA">
- at WebService(name = "Hello",
-targetNamespace = "http://org.jboss.ws/samples/wssecuritypolicy",
-wsdlLocation="WEB-INF/wsdl/HelloService.wsdl")
- at SOAPBinding(style = SOAPBinding.Style.RPC)
-public class HelloJavaBean
-{
-private Logger log = Logger.getLogger(HelloJavaBean.class);
-..
- at WebMethod
-public UserType echoUserType(@WebParam(name = "user") UserType in0)
-{
-log.info(in0);
-return in0;
-}
-}
-<?xml version="1.0" encoding="UTF-8"?>
-<definitions name='HelloService' targetNamespace='http://org.jboss.ws/samples/wssecuritypolicy' xmlns='http://schemas.xmlsoap.org/wsdl/' xmlns:ns1='http://org.jboss.ws/samples/wssecurity' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:tns='http://org.jboss.ws/samples/wssecuritypolicy' xmlns:wsp='http://schemas.xmlsoap.org/ws/2004/09/policy' xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
-<types>
-<xs:schema targetNamespace='http://org.jboss.ws/samples/wssecurity' version='1.0' xmlns:xs='http://www.w3.org/2001/XMLSchema'>
-<xs:complexType name='UserType'>
-<xs:sequence>
-<xs:element minOccurs='0' name='msg' type='xs:string'/>
-</xs:sequence>
-</xs:complexType>
-</xs:schema>
-</types>
-<wsp:Policy wsu:Id='X509EndpointPolicy' xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'>
-<wsp:All>
-<sp:jboss-ws-security xmlns:sp='http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd'>
-<sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file>
-<sp:key-store-password>jbossws</sp:key-store-password>
-<sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file>
-<sp:trust-store-password>jbossws</sp:trust-store-password>
-<sp:config>
-<sp:encrypt alias='wsse' type='x509v3'/>
-<sp:requires>
-<sp:encryption/>
-</sp:requires>
-</sp:config>
-</sp:jboss-ws-security>
-</wsp:All>
-</wsp:Policy>
-<message name='Hello_echoUserType'>
-<part name='user' type='ns1:UserType'/>
-</message>
-<message name='Hello_echoUserTypeResponse'>
-<part name='return' type='ns1:UserType'/>
-</message>
-<portType name='Hello'>
-<operation name='echoUserType' parameterOrder='user'>
-<input message='tns:Hello_echoUserType'/>
-<output message='tns:Hello_echoUserTypeResponse'/>
-</operation>
-</portType>
-<binding name='HelloBinding' type='tns:Hello'>
-<wsp:PolicyReference URI='#X509EndpointPolicy'/>
-<soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/>
-<operation name='echoUserType'>
-<soap:operation soapAction=''/>
-<input>
-<soap:body namespace='http://org.jboss.ws/samples/wssecuritypolicy' use='literal'/>
-</input>
-<output>
-<soap:body namespace='http://org.jboss.ws/samples/wssecuritypolicy' use='literal'/>
-</output>
-</operation>
-</binding>
-<service name='HelloService'>
-<port binding='tns:HelloBinding' name='HelloPort'>
-<soap:address location='REPLACE_WITH_ACTUAL_URL'/>
-</port>
-</service>
-</definitions></programlisting>
-
-<para>Please note in the WSDL file the wsp:Policy element and the wsp:PolicyReference in 'HelloBinding' binding Element.</para>
- </section>
- <section>
- <title>Using policies with JBoss annotations</title>
- <para>Using JBoss proprietary annotation you only have to provide the policy xml, leaving wsdl generation to the JBossWS deployer.</para>
- <para>There are two annotations to use, the first one (@PolicyAttachment) containing an array of the second one (@Policy): this lets you have many policies attached to a class or method. In future domain policy implementations might ship domain annotations extending the @Policy annotation to provide needed metadata directly as annotation parameters. The current @Policy annotation takes a reference to a xml file containing a generic policy description written respecting ws-policy specification rules.</para>
-<programlisting role="JAVA">/**
-
- at Target(ElementType.TYPE)
- at Retention(RetentionPolicy.RUNTIME)
-public @interface PolicyAttachment {
-Policy[] value();
-}
-...
- at Retention(RetentionPolicy.RUNTIME)
-public @interface Policy {
-
-public String policyFileLocation();
-
-public PolicyScopeLevel scope();
-}</programlisting>
- <para>And here you have the previous section example re-implemented using annotations and xml policy file:</para>
-<programlisting role="JAVA">
- at WebService(name = "Hello", targetNamespace = "http://org.jboss.ws/samples/wssecurityAnnotatedpolicy")
- at PolicyAttachment({@Policy( policyFileLocation="WEB-INF/Policy.xml", scope = PolicyScopeLevel.WSDL_PORT ) })
- at SOAPBinding(style = SOAPBinding.Style.RPC)
-public class HelloJavaBean
-{
-private Logger log = Logger.getLogger(HelloJavaBean.class);
-
- at WebMethod
-public UserType echoUserType(@WebParam(name = "user") UserType in0)
-{
-log.info(in0);
-return in0;
-}
-}
-<?xml version="1.0" encoding="UTF-8"?>
-...
-<wsp:Policy wsu:Id="X509EndpointPolicy" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
-xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
-<wsp:ExactlyOne>
-<wsp:All>
-<sp:jboss-ws-security xmlns:sp="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
-<sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file>
-<sp:key-store-password>jbossws</sp:key-store-password>
-<sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file>
-<sp:trust-store-password>jbossws</sp:trust-store-password>
-<sp:config>
-<sp:encrypt type="x509v3" alias="wsse"/>
-<sp:requires>
-<sp:encryption/>
-</sp:requires>
-</sp:config>
-</sp:jboss-ws-security>
-</wsp:All>
-</wsp:ExactlyOne>
-</wsp:Policy>
-</programlisting>
- </section>
- </section>
</section>
<section>
<title>JBossWS Extensions</title>
<para>This section describes propriatary JBoss extensions to JAX-WS.</para>
<section>
<title>Proprietary Annotations</title>
- <para>For the set of standard annotations, please have a look at <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Annotations">JAX-WS Annotations</ulink></para>
+ <para>For the set of standard annotations, please have a look at <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSAnnotations">JAX-WS Annotations</ulink></para>
<section>
<title>EndpointConfig</title>
<programlisting role="JAVA">/**
-* Defines an endpoint or client configuration.
-* This annotation is valid on an endpoint implementaion bean or a SEI.
-*
-* @author Heiko.Braun at jboss.org
-* @since 16.01.2007
-*/
+ * Defines an endpoint or client configuration.
+ * This annotation is valid on an endpoint implementaion bean or a SEI.
+ */
@Retention(value = RetentionPolicy.RUNTIME)
@Target(value = { ElementType.TYPE })
-public @interface EndpointConfig {
-...
-/**
-* The optional config-name element gives the configuration name that must be present in
-* the configuration given by element config-file.
-*
-* Server side default: Standard Endpoint
-* Client side default: Standard Client
-*/
-String configName() default "";
-...
-/**
-* The optional config-file element is a URL or resource name for the configuration.
-*
-* Server side default: standard-jaxws-endpoint-config.xml
-* Client side default: standard-jaxws-client-config.xml
-*/
-String configFile() default "";
+public @interface EndpointConfig
+{
+ ...
+ /**
+ * The optional config-name element gives the configuration name that must be present in
+ * the configuration given by element config-file.
+ *
+ * Server side default: Standard Endpoint
+ * Client side default: Standard Client
+ */
+ String configName() default "";
+ ...
+ /**
+ * The optional config-file element is a URL or resource name for the configuration.
+ *
+ * Server side default: standard-jaxws-endpoint-config.xml
+ * Client side default: standard-jaxws-client-config.xml
+ */
+ String configFile() default "";
}</programlisting>
</section>
<section>
<title>WebContext</title>
<programlisting role="JAVA">/**
-* Provides web context specific meta data to EJB based web service endpoints.
-*
-* @author thomas.diesler at jboss.org
-* @since 26-Apr-2005
-*/
+ * Provides web context specific meta data to EJB based web service endpoints.
+ *
+ * @author thomas.diesler at jboss.org
+ * @since 26-Apr-2005
+ */
@Retention(value = RetentionPolicy.RUNTIME)
@Target(value = { ElementType.TYPE })
-public @interface WebContext {
-...
-/**
-* The contextRoot element specifies the context root that the web service endpoint is deployed to.
-* If it is not specified it will be derived from the deployment short name.
-*
-* Applies to server side port components only.
-*/
-String contextRoot() default "";
-...
-/**
-* The virtual hosts that the web service endpoint is deployed to.
-*
-* Applies to server side port components only.
-*/
-String[] virtualHosts() default {};
+public @interface WebContext
+{
+ ...
+ /**
+ * The contextRoot element specifies the context root that the web service endpoint is deployed to.
+ * If it is not specified it will be derived from the deployment short name.
+ *
+ * Applies to server side port components only.
+ */
+ String contextRoot() default "";
+ ...
+ /**
+ * The virtual hosts that the web service endpoint is deployed to.
+ *
+ * Applies to server side port components only.
+ */
+ String[] virtualHosts() default {};
-/**
-* Relative path that is appended to the contextRoot to form fully qualified
-* endpoint address for the web service endpoint.
-*
-* Applies to server side port components only.
-*/
-String urlPattern() default "";
+ /**
+ * Relative path that is appended to the contextRoot to form fully qualified
+ * endpoint address for the web service endpoint.
+ *
+ * Applies to server side port components only.
+ */
+ String urlPattern() default "";
-/**
-* The authMethod is used to configure the authentication mechanism for the web service.
-* As a prerequisite to gaining access to any web service which are protected by an authorization
-* constraint, a user must have authenticated using the configured mechanism.
-*
-* Legal values for this element are "BASIC", or "CLIENT-CERT".
-*/
-String authMethod() default "";
+ /**
+ * The authMethod is used to configure the authentication mechanism for the web service.
+ * As a prerequisite to gaining access to any web service which are protected by an authorization
+ * constraint, a user must have authenticated using the configured mechanism.
+ *
+ * Legal values for this element are "BASIC", or "CLIENT-CERT".
+ */
+ String authMethod() default "";
-/**
-* The transportGuarantee specifies that the communication
-* between client and server should be NONE, INTEGRAL, or
-* CONFIDENTIAL. NONE means that the application does not require any
-* transport guarantees. A value of INTEGRAL means that the application
-* requires that the data sent between the client and server be sent in
-* such a way that it can't be changed in transit. CONFIDENTIAL means
-* that the application requires that the data be transmitted in a
-* fashion that prevents other entities from observing the contents of
-* the transmission. In most cases, the presence of the INTEGRAL or
-* CONFIDENTIAL flag will indicate that the use of SSL is required.
-*/
-String transportGuarantee() default "";
+ /**
+ * The transportGuarantee specifies that the communication
+ * between client and server should be NONE, INTEGRAL, or
+ * CONFIDENTIAL. NONE means that the application does not require any
+ * transport guarantees. A value of INTEGRAL means that the application
+ * requires that the data sent between the client and server be sent in
+ * such a way that it can't be changed in transit. CONFIDENTIAL means
+ * that the application requires that the data be transmitted in a
+ * fashion that prevents other entities from observing the contents of
+ * the transmission. In most cases, the presence of the INTEGRAL or
+ * CONFIDENTIAL flag will indicate that the use of SSL is required.
+ */
+ String transportGuarantee() default "";
-/**
-* A secure endpoint does not by default publish it's wsdl on an unsecure transport.
-* You can override this behaviour by explicitly setting the secureWSDLAccess flag to false.
-*
-* Protect access to WSDL. See http://jira.jboss.org/jira/browse/JBWS-723
-*/
-boolean secureWSDLAccess() default true;
+ /**
+ * A secure endpoint does not by default publish it's wsdl on an unsecure transport.
+ * You can override this behaviour by explicitly setting the secureWSDLAccess flag to false.
+ *
+ * Protect access to WSDL. See http://jira.jboss.org/jira/browse/JBWS-723
+ */
+ boolean secureWSDLAccess() default true;
} </programlisting>
</section>
<section>
<title>SecurityDomain</title>
<programlisting role="JAVA">/**
-* Annotation for specifying the JBoss security domain for an EJB
-*
-* @author <a href="mailto:bill at jboss.org">Bill Burke</a>
-**/
+ * Annotation for specifying the JBoss security domain for an EJB
+ */
@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
public @interface SecurityDomain
{
-/**
-* The required name for the security domain.
-*
-* Do not use the JNDI name
-*
-* Good: "MyDomain"
-* Bad: "java:/jaas/MyDomain"
-*/
-String value();
+ /**
+ * The required name for the security domain.
+ *
+ * Do not use the JNDI name
+ *
+ * Good: "MyDomain"
+ * Bad: "java:/jaas/MyDomain"
+ */
+ String value();
-/**
-* The name for the unauthenticated pricipal
-*/
-String unauthenticatedPrincipal() default "";
+ /**
+ * The name for the unauthenticated pricipal
+ */
+ String unauthenticatedPrincipal() default "";
}</programlisting>
</section>
</section>
@@ -2360,17 +2177,14 @@
<section>
<title>Web Services Appendix</title>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Endpoint_Configuration">JAX-WS Endpoint Configuration</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSEndpointConfiguration">JAX-WS Endpoint Configuration</ulink>
</para>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Client_Configuration">JAX-WS Client Configuration</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSClientConfiguration">JAX-WS Client Configuration</ulink>
</para>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Annotations">JAX-WS Annotations</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-WSAnnotations">JAX-WS Annotations</ulink>
</para>
- <para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Common_features_and_properties">Common features and properties</ulink>
- </para>
</section>
<section>
@@ -2384,12 +2198,6 @@
<para><ulink url="http://jaxb.dev.java.net/">JSR 222 - Java Architecture for XML Binding (JAXB) 2.0</ulink></para>
</listitem>
<listitem>
- <para><ulink url="http://www.jcp.org/en/jsr/detail?id=261">JSR-261 - Java API for XML Web Services Addressing</ulink></para>
- </listitem>
- <listitem>
- <para><ulink url="http://www.w3.org/TR/soap12-part1">SOAP-1.2 - Messaging Framework</ulink></para>
- </listitem>
- <listitem>
<para><ulink url="http://jcp.org/en/jsr/detail?id=250">JSR-250 - Common Annotations for the Java Platform</ulink></para>
</listitem>
<listitem>
@@ -2397,10 +2205,5 @@
</listitem>
</orderedlist>
</section>
-
- <!-- </section>-->
-
-
-
</chapter>
More information about the jboss-cvs-commits
mailing list