[jboss-cvs] JBossAS SVN: r92792 - 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
Tue Aug 25 10:20:06 EDT 2009
Author: richard.opalka at jboss.com
Date: 2009-08-25 10:20:06 -0400 (Tue, 25 Aug 2009)
New Revision: 92792
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-25 13:15:04 UTC (rev 92791)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Web_Services.xml 2009-08-25 14:20:06 UTC (rev 92792)
@@ -23,7 +23,7 @@
Enterprise systems communication may benefit from a wise adoption of web service technologies. Focusing attention on well designed contracts allows developers to establish an abstract view of their service capabilities. Considering the standardized way contracts are written, this definitely helps communication with third-party systems and eventually supports business-to-business integration; everything is clear and standardized in the contract the provider and consumer agree on. This also reduces the dependencies between implementations allowing other consumers to easily use the provided service without major changes.
</para>
<para>
- Other benefits exist for enterprise systems that incorporate web service technologies for internal heterogenous subsystems communication as web service interoperability boosts service reuse and composition. Web services elimenates the need to rewrite whole functionalities because they were developed by another enterprise department using a different software language.
+ Other benefits exist for enterprise systems that incorporate web service technologies for internal heterogenous subsystems communication as web service interoperability boosts service reuse and composition. Web services eliminates the need to rewrite whole functionalities because they were developed by another enterprise department using a different software language.
</para>
</section>
@@ -50,12 +50,12 @@
</para>
</section>
- <section><title>Jboss Web Services Attachment support with XOP (XML-binary Optimized Packaging) and SwA</title>
+ <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>
- WS-I Attachment Profile 1.0 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.
+ <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>
@@ -63,60 +63,60 @@
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;
-}
+<programlisting role="JAVA">/**
+ * Payload bean that will use SwaRef encoding.
+ */
+ at XmlRootElement
+public class DocumentPayload
+{
+ private DataHandler data;
- at XmlElement
- at XmlAttachmentRef
-public DataHandler getData()
-{
-return data;
- }
-
-public void setData(DataHandler data)
-{
- this.data = data;
- }
-}
-
- With document wrapped endpoints you may even specify the @XmlAttachmentRef annotation on the service endpoint interface:
+ public DocumentPayload()
+ {
+ }
- at WebService
-public interface DocWrappedEndpoint
- {
- @WebMethod
- DocumentPayload beanAnnotation(DocumentPayload dhw, String test);
-
- @WebMethod
- @XmlAttachmentRef
- DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test);
-
- }</programlisting>
+ 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:
+ 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>
+<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>
@@ -125,13 +125,18 @@
<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>SOAP Message Transmission Optimization Mechanism ((MTOM) <ulink url="http://www.w3.org/TR/soap12-mtom/"/>)</para>
- </listitem>
- <listitem>
- <para>XML-binary Optimized Packaging (XOP) (<ulink url="http://www.w3.org/TR/xop10/"/>)</para>
- </listitem>
-</itemizedlist>
+ <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>
@@ -178,23 +183,23 @@
<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;
-
- @Remote
- @WebService(targetNamespace = "http://org.jboss.ws/xop/doclit")
- @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, parameterStyle = SOAPBinding.ParameterStyle.BARE)
- @BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true") (1)
- public interface MTOMEndpoint {
-
- [...]
- } </programlisting>
+<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>
@@ -204,13 +209,13 @@
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 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>
@@ -232,17 +237,17 @@
</para>
<programlisting role="XML"><binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
- <soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/>
-<operation name='concat'>
- <soap:operation soapAction=''/>
-<input>
- <soap:body use='literal'/>
-</input>
- <output>
- <soap:body use='literal'/>
-</output>
- </operation>
- </binding>
+ <soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/>
+ <operation name='concat'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation>
+</binding>
</programlisting>
@@ -250,20 +255,24 @@
With document style web services the payload of every message is defined by a complex type in XML schema.
</para>
<programlisting role="XML"><complexType name='concatType'>
- <sequence>
- <element name='String_1' nillable='true' type='string'/>
- <element name='long_1' type='long'/>
- </sequence>
- </complexType>
- <element name='concat' type='tns:concatType'/>
- Therefore, message parts must refer to an element from the schema.
- <message name='EndpointInterface_concat'>
- <part name='parameters' element='tns:concat'/>
- </message>
-The following message definition is invalid.
-<message name='EndpointInterface_concat'>
- <part name='parameters' type='tns:concatType'/>
+ <sequence>
+ <element name='String_1' nillable='true' type='string'/>
+ <element name='long_1' type='long'/>
+ </sequence>
+</complexType>
+<element name='concat' type='tns:concatType'/></programlisting>
+ <para>
+ Therefore, message parts must refer to an element from the schema.
+ </para>
+<programlisting role="XML"><message name='EndpointInterface_concat'>
+ <part name='parameters' element='tns:concat'/>
</message></programlisting>
+ <para>
+ The following message definition is invalid.
+ </para>
+<programlisting role="XML"><message name='EndpointInterface_concat'>
+ <part name='parameters' type='tns:concatType'/>
+</message></programlisting>
</section>
@@ -276,11 +285,11 @@
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
public class DocBareServiceImpl
{
- at WebMethod
-public SubmitBareResponse submitPO(SubmitBareRequest poRequest)
-{
- ...
-}
+ @WebMethod
+ public SubmitBareResponse submitPO(SubmitBareRequest poRequest)
+ {
+ ...
+ }
}</programlisting>
@@ -288,14 +297,14 @@
The trick is that the Java beans representing the payload contain JAXB annotations that define how the payload is represented on the wire.
</para>
<programlisting role="JAVA">@XmlAccessorType(XmlAccessType.FIELD)
- @XmlType(name = "SubmitBareRequest", namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", propOrder = { "product" })
- @XmlRootElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", name = "SubmitPO")
- public class SubmitBareRequest
- {
- @XmlElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", required = true)
- private String product;
-
- ...
+ at XmlType(name = "SubmitBareRequest", namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", propOrder = { "product" })
+ at XmlRootElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", name = "SubmitPO")
+public class SubmitBareRequest
+{
+ @XmlElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", required = true)
+ private String product;
+
+ ...
}</programlisting>
</section>
@@ -306,15 +315,15 @@
</para>
<programlisting role="JAVA">@WebService
public class DocWrappedServiceImpl
- {
- @WebMethod
- @RequestWrapper (className="org.somepackage.SubmitPO")
- @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
- public String submitPO(String product, int quantity)
- {
- ...
- }
- }</programlisting>
+{
+ @WebMethod
+ @RequestWrapper (className="org.somepackage.SubmitPO")
+ @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
+ public String submitPO(String product, int quantity)
+ {
+ ...
+ }
+}</programlisting>
<note><para>
With JBossWS the request and response wrapper annotations are not required, they will be generated on demand using sensible defaults.
@@ -343,17 +352,17 @@
</para>
<programlisting role="XML">
- <binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
- <soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/>
- <operation name='echo'>
- <soap:operation soapAction=''/>
- <input>
- <soap:body namespace='http://org.jboss.ws/samples/jsr181pojo' use='literal'/>
- </input>
- <output>
- <soap:body namespace='http://org.jboss.ws/samples/jsr181pojo' use='literal'/>
- </output>
- </operation>
+<binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
+ <soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/>
+ <operation name='echo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='http://org.jboss.ws/samples/jsr181pojo' use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='http://org.jboss.ws/samples/jsr181pojo' use='literal'/>
+ </output>
+ </operation>
</binding></programlisting>
@@ -361,40 +370,41 @@
With RPC style web services the portType names the operation (i.e. the java method on the endpoint)
</para>
-<programlisting role="XML"><portType name='EndpointInterface'>
- <operation name='echo' parameterOrder='String_1'>
- <input message='tns:EndpointInterface_echo'/>
-<output message='tns:EndpointInterface_echoResponse'/>
- </operation>
- </portType></programlisting>
+<programlisting role="XML">
+<portType name='EndpointInterface'>
+ <operation name='echo' parameterOrder='String_1'>
+ <input message='tns:EndpointInterface_echo'/>
+ <output message='tns:EndpointInterface_echoResponse'/>
+ </operation>
+</portType></programlisting>
<para>
Operation parameters are defined by individual message parts.
</para>
<programlisting role="XML">
- <message name='EndpointInterface_echo'>
- <part name='String_1' type='xsd:string'/>
- </message>
- <message name='EndpointInterface_echoResponse'>
- <part name='result' type='xsd:string'/>
- </message></programlisting>
+<message name='EndpointInterface_echo'>
+ <part name='String_1' type='xsd:string'/>
+</message>
+<message name='EndpointInterface_echoResponse'>
+ <part name='result' type='xsd:string'/>
+</message></programlisting>
<note><para>
There is no complex type in XML schema that could validate the entire SOAP message payload.
</para></note>
<programlisting role="JAVA">
- @WebService
- @SOAPBinding(style = SOAPBinding.Style.RPC)
- public class JSEBean01
- {
- @WebMethod
- @WebResult(name="result")
- public String echo(@WebParam(name="String_1") String input)
- {
- ...
- }
+ at WebService
+ at SOAPBinding(style = SOAPBinding.Style.RPC)
+public class JSEBean01
+{
+ @WebMethod
+ @WebResult(name="result")
+ public String echo(@WebParam(name="String_1") String input)
+ {
+ ...
+ }
} </programlisting>
<para>
@@ -436,18 +446,18 @@
<section><title>Plain old Java Object (POJO)</title>
- <para>Let us take a look at simple POJO endpoint implementation. All endpoint associated metadata is provided via JSR-181 annotations
+ <para>Let us take a look at simple POJO endpoint implementation. All endpoint associated metadata are provided via JSR-181 annotations
</para>
<programlisting role="JAVA">@WebService
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class JSEBean01
+{
+ @WebMethod
+ public String echo(String input)
{
- @WebMethod
- public String echo(String input)
- {
...
- }
- } </programlisting>
+ }
+} </programlisting>
@@ -458,14 +468,14 @@
A JAX-WS java service endpoint (JSE) is deployed as a web application.
</para>
<programlisting><web-app ...>
- <servlet>
- <servlet-name>TestService</servlet-name>
- <servlet-class>org.jboss.test.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class>
- </servlet>
- <servlet-mapping>
-<servlet-name>TestService</servlet-name>
- <url-pattern>/*</url-pattern>
- </servlet-mapping>
+ <servlet>
+ <servlet-name>TestService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>TestService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
</web-app></programlisting>
</section>
@@ -476,9 +486,9 @@
</para>
<programlisting role="XML"><war warfile="${build.dir}/libs/jbossws-samples-jsr181pojo.war" webxml="${build.resources.dir}/samples/jsr181pojo/WEB-INF/web.xml">
- <classes dir="${build.dir}/classes">
-<include name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/>
- </classes>
+ <classes dir="${build.dir}/classes">
+ <include name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/>
+ </classes>
</war> </programlisting>
<note><para>
@@ -498,26 +508,26 @@
<screen>http://yourhost:8080/jbossws/services</screen>
<para>
-It is also possible to generate the abstract contract off line using jboss tools. For details of that see <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Top_Down_.28Java_to_WSDL.29">#Top Down (Java to WSDL)</ulink></para>
+It is also possible to generate the abstract contract off line using jboss tools. For details of that see <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e741">#Top Down (Using wsconsume)</ulink></para>
</section>
<section>
<title>EJB3 Stateless Session Bean (SLSB)</title>
- <para>The JAX-WS programming model support the same set of annotations on EJB3 stateless session beans as on <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#_Plain_old_Java_Object_.28POJO.29"># Plain old Java Object (POJO)</ulink> endpoints. EJB-2.1 endpoints are supported using the JAX-RPC progamming model.</para>
+ <para>The JAX-WS programming model support the same set of annotations on EJB3 stateless session beans as on <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e213"># Plain old Java Object (POJO)</ulink> endpoints. EJB-2.1 endpoints are supported using the JAX-RPC progamming model.</para>
<programlisting role="JAVA">
- @Stateless
- @Remote(EJB3RemoteInterface.class)
- @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface")
+ at Stateless
+ at Remote(EJB3RemoteInterface.class)
+ at RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface")
- @WebService
- @SOAPBinding(style = SOAPBinding.Style.RPC)
- public class EJB3Bean01 implements EJB3RemoteInterface
- {
- @WebMethod
- public String echo(String input)
- {
- ...
- }
- } </programlisting>
+ at WebService
+ at SOAPBinding(style = SOAPBinding.Style.RPC)
+public class EJB3Bean01 implements EJB3RemoteInterface
+{
+ @WebMethod
+ public String echo(String input)
+ {
+ ...
+ }
+}</programlisting>
<para>Above you see an EJB-3.0 stateless session bean that exposes one method both on the remote interface and as an endpoint operation.</para>
<formalpara>
@@ -527,10 +537,10 @@
</para>
</formalpara>
<programlisting role="XML"><jar jarfile="${build.dir}/libs/jbossws-samples-jsr181ejb.jar">
-<fileset dir="${build.dir}/classes">
-<include name="org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01.class"/>
-<include name="org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface.class"/>
-</fileset>
+ <fileset dir="${build.dir}/classes">
+ <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01.class"/>
+ <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface.class"/>
+ </fileset>
</jar> </programlisting>
<formalpara>
<title>Accessing the generated WSDL</title>
@@ -538,7 +548,7 @@
</formalpara>
<programlisting> <![CDATA[
http://yourhost:8080/jbossws/services]]> </programlisting>
- <para>It is also possible to generate the abstract contract offline using JbossWS tools. For details of that please see <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Top_Down_.28Java_to_WSDL.29">#Top Down (Java to WSDL)</ulink></para>
+ <para>It is also possible to generate the abstract contract offline using JbossWS tools. For details of that please see <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e741">#Top Down (Using wsconsume)</ulink></para>
</section>
<section>
<title>Endpoint Provider</title>
@@ -550,11 +560,11 @@
@ServiceMode(value = Service.Mode.PAYLOAD)
public class ProviderBeanPayload implements Provider<Source>
{
-public Source invoke(Source req)
-{
-// Access the entire request PAYLOAD and return the response PAYLOAD
- }
-} </programlisting>
+ public Source invoke(Source req)
+ {
+ // Access the entire request PAYLOAD and return the response PAYLOAD
+ }
+}</programlisting>
<para><property>Service.Mode.PAYLOAD</property> is the default and does not have to be declared explicitly. You can also use <property>Service.Mode.MESSAGE</property> to access the entire SOAP message (for example, with <property>MESSAGE</property> the Provider can also see SOAP Headers)</para>
</section>
<section>
@@ -564,28 +574,28 @@
@WebService
public class EndpointJSE
{
- at Resource
-WebServiceContext wsCtx;
+ @Resource
+ WebServiceContext wsCtx;
- at WebMethod
-public String testGetMessageContext()
-{
-SOAPMessageContext jaxwsContext = (SOAPMessageContext)wsCtx.getMessageContext();
-return jaxwsContext != null ? "pass" : "fail";
-}
-..
- at WebMethod
-public String testGetUserPrincipal()
-{
-Principal principal = wsCtx.getUserPrincipal();
-return principal.getName();
-}
+ @WebMethod
+ public String testGetMessageContext()
+ {
+ SOAPMessageContext jaxwsContext = (SOAPMessageContext)wsCtx.getMessageContext();
+ return jaxwsContext != null ? "pass" : "fail";
+ }
+ ...
+ @WebMethod
+ public String testGetUserPrincipal()
+ {
+ Principal principal = wsCtx.getUserPrincipal();
+ return principal.getName();
+ }
- at WebMethod
-public boolean testIsUserInRole(String role)
-{
-return wsCtx.isUserInRole(role);
-}
+ @WebMethod
+ public boolean testIsUserInRole(String role)
+ {
+ return wsCtx.isUserInRole(role);
+ }
}</programlisting>
</section>
<section>
@@ -606,22 +616,23 @@
<programlisting role="JAVA">
// Generated Service Class
- @WebServiceClient(name="StockQuoteService", targetNamespace="http://example.com/stocks", wsdlLocation="http://example.com/stocks.wsdl")
+ at WebServiceClient(name="StockQuoteService", targetNamespace="http://example.com/stocks", wsdlLocation="http://example.com/stocks.wsdl")
public class StockQuoteService extends javax.xml.ws.Service
{
-public StockQuoteService()
-{
-super(new URL("http://example.com/stocks.wsdl"), new QName("http://example.com/stocks", "StockQuoteService"));
-}
+
+ public StockQuoteService()
+ {
+ super(new URL("http://example.com/stocks.wsdl"), new QName("http://example.com/stocks", "StockQuoteService"));
+ }
-public StockQuoteService(String wsdlLocation, QName serviceName)
-{
-super(wsdlLocation, serviceName);
-}
+ public StockQuoteService(String wsdlLocation, QName serviceName)
+ {
+ super(wsdlLocation, serviceName);
+ }
-...
+ ...
}</programlisting>
- <para>Section <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Dynamic_Proxy">#Dynamic Proxy</ulink> explains how to obtain a port from the service and how to invoke an operation on the port. If you need to work with the XML payload directly or with the XML representation of the entire SOAP message, have a look at <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Dispatch">#Dispatch</ulink>.</para>
+ <para>Section <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e401">#Dynamic Proxy</ulink> explains how to obtain a port from the service and how to invoke an operation on the port. If you need to work with the XML payload directly or with the XML representation of the entire SOAP message, have a look at <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e468">#Dispatch</ulink>.</para>
<formalpara>
<title>Dynamic case</title>
<para>In the dynamic case, when nothing is generated, a web service client uses <literal>Service.create</literal> to create Service instances, the following code illustrates this process.</para>
@@ -635,7 +646,7 @@
</section>
<section>
<title>Handler Resolver</title>
- <para>JAX-WS provides a flexible plug-in framework for message processing modules, known as handlers, that may be used to extend the capabilities of a JAX-WS runtime system. <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Handler_Framework">Handler Framework</ulink> describes the handler framework in detail. A <classname>Service</classname> instance provides access to a <classname>HandlerResolver</classname> via a pair of <methodname>getHandlerResolver</methodname> and <methodname>setHandlerResolver</methodname> methods that may be used to configure a set of handlers on a per-service, per-port or per-protocol binding basis.</para>
+ <para>JAX-WS provides a flexible plug-in framework for message processing modules, known as handlers, that may be used to extend the capabilities of a JAX-WS runtime system. <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e528">Handler Framework</ulink> describes the handler framework in detail. A <classname>Service</classname> instance provides access to a <classname>HandlerResolver</classname> via a pair of <methodname>getHandlerResolver</methodname> and <methodname>setHandlerResolver</methodname> methods that may be used to configure a set of handlers on a per-service, per-port or per-protocol binding basis.</para>
<para>When a <classname>Service</classname> instance is used to create a proxy or a <classname>Dispatch</classname> instance then the handler resolver currently registered with the service is used to create the required handler chain. Subsequent changes to the handler resolver configured for a <classname>Service</classname> instance do not affect the handlers on previously created proxies, or <classname>Dispatch</classname> instances.</para>
<!--<para>[TODO] <ulink url="http://jira.jboss.org/jira/browse/JBWS-1512">(JBWS-1512) Provide a sample for Service HandlerResolver</ulink></para>-->
</section>
@@ -649,19 +660,19 @@
<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>
<programlisting role="JAVA">
- /**
+/**
* The getPort method returns a proxy. A service client
* uses this proxy to invoke operations on the target
* service endpoint. The <code>serviceEndpointInterface</code>
* specifies the service endpoint interface that is supported by
* the created dynamic proxy instance.
- **/
- public <T> T getPort(QName portName, Class<T> serviceEndpointInterface)
- {
- ...
- }
+ */
+public <T> T getPort(QName portName, Class<T> serviceEndpointInterface)
+{
+...
+}
- /**
+/**
* The getPort method returns a proxy. The parameter
* <code>serviceEndpointInterface</code> specifies the service
* endpoint interface that is supported by the returned proxy.
@@ -670,31 +681,30 @@
* binding (and a port) and configuring the proxy accordingly.
* The returned proxy should not be reconfigured by the client.
*
- **/
- public <T> T getPort(Class<T> serviceEndpointInterface)
- {
- ...
- }</programlisting>
-<para>The <emphasis>Service Endpoint Interface</emphasis> (SEI) is usually generated using tools. For details see <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#_Top_Down_.28WSDL_to_Java.29">Top Down (WSDL to Java)</ulink>.</para>
-<para>A generated static <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Service"><classname>Service</classname></ulink> usually also offers typed methods to get ports. These methods also return dynamic proxies that implement the SEI.</para>
+ */
+public <T> T getPort(Class<T> serviceEndpointInterface)
+{
+...
+}</programlisting>
+<para>The <emphasis>Service Endpoint Interface</emphasis> (SEI) is usually generated using tools. For details see <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e741">Top Down (Using wsconsume)</ulink>.</para>
+<para>A generated static <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e330"><classname>Service</classname></ulink> usually also offers typed methods to get ports. These methods also return dynamic proxies that implement the SEI.</para>
<programlisting role="JAVA">
@WebServiceClient(name = "TestEndpointService", targetNamespace = "http://org.jboss.ws/wsref",
wsdlLocation = "http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl")
-
- public class TestEndpointService extends Service
- {
- ...
+public class TestEndpointService extends Service
+{
+ ...
- public TestEndpointService(URL wsdlLocation, QName serviceName) {
- super(wsdlLocation, serviceName);
- }
+ public TestEndpointService(URL wsdlLocation, QName serviceName) {
+ super(wsdlLocation, serviceName);
+ }
- @WebEndpoint(name = "TestEndpointPort")
- public TestEndpoint getTestEndpointPort()
- {
- return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
- }
- }</programlisting>
+ @WebEndpoint(name = "TestEndpointPort")
+ public TestEndpoint getTestEndpointPort()
+ {
+ return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
+ }
+}</programlisting>
</section>
<section>
@@ -712,15 +722,15 @@
<programlisting role="XML">
public class EJB3Client implements EJB3Remote
{
- @WebServiceRef
- public TestEndpointService service4;
+ @WebServiceRef
+ public TestEndpointService service4;
- @WebServiceRef
- public TestEndpoint port3;
-</programlisting>
+ @WebServiceRef
+ public TestEndpoint port3;
+}</programlisting>
<formalpara>
<title>WebServiceRef Customization</title>
- <para>In Jboss Enterprise Application Platform 5.0 we offer a number of overrides and extensions to the <classname>WebServiceRef</classname> annotation. These include</para>
+ <para>In JBoss Enterprise Application Platform 5.0 we offer a number of overrides and extensions to the <classname>WebServiceRef</classname> annotation. These include:</para>
</formalpara>
<itemizedlist>
<listitem>
@@ -736,40 +746,40 @@
<para>Example:</para>
<programlisting role="XML">
<service-ref>
-<service-ref-name>OrganizationService</service-ref-name>
-<wsdl-override>file:/wsdlRepository/organization-service.wsdl</wsdl-override>
+ <service-ref-name>OrganizationService</service-ref-name>
+ <wsdl-override>file:/wsdlRepository/organization-service.wsdl</wsdl-override>
</service-ref>
..
<service-ref>
-<service-ref-name>OrganizationService</service-ref-name>
-<config-name>Secure Client Config</config-name>
-<config-file>META-INF/jbossws-client-config.xml</config-file>
-<handler-chain>META-INF/jbossws-client-handlers.xml</handler-chain>
+ <service-ref-name>OrganizationService</service-ref-name>
+ <config-name>Secure Client Config</config-name>
+ <config-file>META-INF/jbossws-client-config.xml</config-file>
+ <handler-chain>META-INF/jbossws-client-handlers.xml</handler-chain>
</service-ref>
<service-ref>
-<service-ref-name>SecureService</service-ref-name>
-<service-class-name>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpointService</service-class-name>
-<service-qname>{http://org.jboss.ws/wsref}SecureEndpointService</service-qname>
-<port-info>
-<service-endpoint-interface>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpoint</service-endpoint-interface>
-<port-qname>{http://org.jboss.ws/wsref}SecureEndpointPort</port-qname>
-<stub-property>
-<name>javax.xml.ws.security.auth.username</name>
-<value>kermit</value>
-</stub-property>
-<stub-property>
-<name>javax.xml.ws.security.auth.password</name>
-<value>thefrog</value>
-</stub-property>
-</port-info>
+ <service-ref-name>SecureService</service-ref-name>
+ <service-class-name>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpointService</service-class-name>
+ <service-qname>{http://org.jboss.ws/wsref}SecureEndpointService</service-qname>
+ <port-info>
+ <service-endpoint-interface>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpoint</service-endpoint-interface>
+ <port-qname>{http://org.jboss.ws/wsref}SecureEndpointPort</port-qname>
+ <stub-property>
+ <name>javax.xml.ws.security.auth.username</name>
+ <value>kermit</value>
+ </stub-property>
+ <stub-property>
+ <name>javax.xml.ws.security.auth.password</name>
+ <value>thefrog</value>
+ </stub-property>
+ </port-info>
</service-ref></programlisting>
<!--<para>For details, see <emphasis role="bold">service-ref_5_0.dtd</emphasis> in the jboss documentation directory.</para> -->
</section>
<section>
<title>Dispatch</title>
- <para>XMLWeb Services use XML messages for communication between services and service clients. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The Dispatch interface provides support for this mode of interaction.</para>
+ <para>XML Web Services use XML messages for communication between services and service clients. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The Dispatch interface provides support for this mode of interaction.</para>
<para>Dispatch supports two usage modes, identified by the constants <property>javax.xml.ws.Service.Mode.MESSAGE</property> and <property>javax.xml.ws.Service.Mode.PAYLOAD</property> respectively:</para>
<formalpara>
@@ -818,16 +828,16 @@
<programlisting role="JAVA">
public void testInvokeAsync() throws Exception
{
-URL wsdlURL = new URL("http://" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl");
-QName serviceName = new QName(targetNS, "TestEndpointService");
-Service service = Service.create(wsdlURL, serviceName);
-TestEndpoint port = service.getPort(TestEndpoint.class);
+ URL wsdlURL = new URL("http://" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl");
+ QName serviceName = new QName(targetNS, "TestEndpointService");
+ Service service = Service.create(wsdlURL, serviceName);
+ TestEndpoint port = service.getPort(TestEndpoint.class);
-Response response = port.echoAsync("Async");
+ Response response = port.echoAsync("Async");
-// access future
-String retStr = (String) response.get();
-assertEquals("Async", retStr);
+ // access future
+ String retStr = (String) response.get();
+ assertEquals("Async", retStr);
}
</programlisting>
</section>
@@ -839,28 +849,28 @@
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class PingEndpointImpl
{
- private static String feedback;
-..
- at WebMethod
- at Oneway
-public void ping()
-{
-log.info("ping");
-feedback = "ok";
-}
-..
- at WebMethod
-public String feedback()
-{
-log.info("feedback");
-return feedback;
-}
+ private static String feedback;
+ ...
+ @WebMethod
+ @Oneway
+ public void ping()
+ {
+ log.info("ping");
+ feedback = "ok";
+ }
+ ...
+ @WebMethod
+ public String feedback()
+ {
+ log.info("feedback");
+ return feedback;
+ }
}</programlisting>
</section>
</section>
<section>
<title>Common API</title>
- <para>This sections describes concepts that apply equally to <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Web_Service_Endpoints">#Web Service Endpoints</ulink> and <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Web_Service_Clients">#Web Service Clients</ulink></para>
+ <para>This sections describes concepts that apply equally to <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e208">#Web Service Endpoints</ulink> and <ulink url="http://labs.jboss.com/jbossws/docs/jaxws_userguide-2.0/index.html#d0e327">#Web Service Clients</ulink></para>
<section>
<title>Handler Framework</title>
<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>
@@ -918,35 +928,31 @@
<section>
<title>Message Context</title>
<para>MessageContext is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.</para>
- <para>Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of an MEP on a particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution of an MEP instance. APPLICATION scoped properties are also made available to client applications (see section 4.2.1) and service endpoint implementations. The defaultscope for a property is HANDLER.</para>
+ <para>Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers associated with particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution. APPLICATION scoped properties are also made available to client applications and service endpoint implementations. The default scope for a property is HANDLER.</para>
<section>
<title>Accessing the message context</title>
- <para>There is currently no portable way of doing this in 4.0.5. <literal>@WebServiceContext</literal> injection will be available with 4.2. In the meantime you can access the message context like this:</para>
-<programlisting role="XML">
-CommonMessageContext msgContext = MessageContextAssociation.peekMessageContext();
-msgContext.setProperty(<Name>, <Value>);</programlisting>
-
+ <para>Users can access the message context in handlers or in endpoints via <literal>@WebServiceContext</literal> annotation.</para>
</section>
<section>
<title>Logical Message Context</title>
- <para><literal>#Logical Handlers</literal> are passed a message context of type LogicalMessageContext when invoked. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of amessage. A protocol binding defines what component of a message are available via a logical message context. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.</para>
+ <para>LogicalMessageContext is passed to <literal>Logical Handlers</literal> at invocation time. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of a message. A protocol binding defines what component of a message are available via a logical message context. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.</para>
</section>
<section>
<title>SOAP Message Context</title>
- <para>SOAP handlers are passed a SOAPMessageContext when invoked. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.</para>
+ <para>SOAPMessageContext is passed to <literal>SOAP handlers</literal> at invocation time. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.</para>
</section>
</section>
<section>
<title>Fault Handling</title>
- <para>An implementation may thow a SOAPFaultException</para>
+ <para>An implementation may throw a SOAPFaultException</para>
<programlisting role="JAVA">
public void throwSoapFaultException()
{
-SOAPFactory factory = SOAPFactory.newInstance();
-SOAPFault fault = factory.createFault("this is a fault string!", new QName("http://foo", "FooCode"));
-fault.setFaultActor("mr.actor");
-fault.addDetail().addChildElement("test");
-throw new SOAPFaultException(fault);
+ SOAPFactory factory = SOAPFactory.newInstance();
+ SOAPFault fault = factory.createFault("this is a fault string!", new QName("http://foo", "FooCode"));
+ fault.setFaultActor("mr.actor");
+ fault.addDetail().addChildElement("test");
+ throw new SOAPFaultException(fault);
}
</programlisting>
<para>or an application specific user exception</para>
@@ -954,7 +960,7 @@
<programlisting role="JAVA">
public void throwApplicationException() throws UserException
{
-throw new UserException("validation", 123, "Some validation error");
+ throw new UserException("validation", 123, "Some validation error");
}
</programlisting>
<para>
@@ -968,8 +974,7 @@
<title>DataBinding</title>
<section>
<title>Using JAXB with non annotated classes</title>
- <para> Since 2.0.2</para>
- <para>JAXB is heavily driven by Java Annotations on the Java Bindings. It currently doesn't support an external binding configuration. This recently became an issue for us on JBossESB since the JBossWS 2.0.0 native SOAP stack uses JAXB to perform the SOAP to Java bindings (see 1, 2). It's an issue for JBossESB simply because it needs to be able to support user definition of JBossWS native Webservice Endpoints (e.g. JSR 181) using Java typesets that have not been "JAXB Annotated" (see JAXB Introductions On JBossWS).</para>
+ <para>JAXB is heavily driven by Java Annotations on the Java Bindings. It currently doesn't support an external binding configuration.</para>
<para>In order to support this, we built on a JAXB RI feature whereby it allows you to specify a RuntimeInlineAnnotationReader implementation during JAXBContext creation (see JAXBRIContext).</para>
<para>We call this feature "JAXB Annotation Introduction" and we've made it available for general consumption i.e. it can be checked out, built and used from SVN:</para>
<itemizedlist>
@@ -990,195 +995,6 @@
</section>
</section>
<section>
- <title>Attachments</title>
- <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>Since 2.0</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 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;
-}
-
- at XmlElement
- at 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
-{
- at WebMethod
-DocumentPayload beanAnnotation(DocumentPayload dhw, String test);
-
- at WebMethod
- at 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>
@@ -1193,7 +1009,7 @@
<para>Top-down use cases:</para>
<itemizedlist>
<listitem>
- <para> Replacing the implementation of an existing Web Service, and you can't break compatibility with older clients</para>
+ <para> Replacing the implementation of an existing Web Service without breaking compatibility with older clients</para>
</listitem>
<listitem>
<para> Exposing a service that conforms to a contract specified by a third party (e.g. a vender that calls you back using an already defined protocol).</para>
@@ -1223,7 +1039,7 @@
<row>
<entry>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink>
</para>
</entry>
<entry>
@@ -1233,7 +1049,7 @@
<row>
<entry>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsconsume">wsconsume</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsconsume">wsconsume</ulink>
</para>
</entry>
<entry>
@@ -1243,11 +1059,11 @@
<row>
<entry>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsrunclient">wsrunclient</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsrunclient">wsrunclient</ulink>
</para>
</entry>
<entry>
- <para> Executes a Java client (has a main method) using the JBossWS classpath.</para>
+ <para> Executes a Java client (that has a main method) using the JBossWS classpath.</para>
</entry>
</row>
</tbody>
@@ -1263,14 +1079,14 @@
@javax.jws.WebService
public class Echo
{
-public String echo(String input)
-{
-return input;
+ public String echo(String input)
+ {
+ return input;
+ }
}
-}
</programlisting>
<para>A JSE or EJB3 deployment can be built using this class, and it is the only Java code needed to deploy on JBossWS. The WSDL, and all other Java artifacts called "wrapper classes" will be generated for you at deploy time. This actually goes beyond the JAX-WS specification, which requires that wrapper classes be generated using an offline tool. The reason for this requirement is purely a vender implementation problem, and since we do not believe in burdening a developer with a bunch of additional steps, we generate these as well. However, if you want your deployment to be portable to other application servers, you will need to use a tool and add the generated classes to your deployment.</para>
- <para>This is the primary purpose of the <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide</ulink> tool, to generate portable JAX-WS artifacts. Additionally, it can be used to "provide" the abstract contract (WSDL file) for your service. This can be obtained by invoking <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide</ulink> using the "-w" option:</para>
+ <para>This is the primary purpose of the <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink> tool, to generate portable JAX-WS artifacts. Additionally, it can be used to "provide" the abstract contract (WSDL file) for your service. This can be obtained by invoking <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink> using the "-w" option:</para>
<programlisting role="JAVA">
$ javac -d . -classpath jboss-jaxws.jar Echo.java
$ wsprovide -w echo.Echo
@@ -1283,17 +1099,17 @@
<para>Inspecting the WSDL reveals a service called EchoService:</para>
<programlisting role="XML">
<service name='EchoService'>
-<port binding='tns:EchoBinding' name='EchoPort'>
-<soap:address location='REPLACE_WITH_ACTUAL_URL'/>
-</port>
+ <port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port>
</service></programlisting>
<para>As expected, this service defines one operation, "echo":</para>
<programlisting role="XML">
<portType name='Echo'>
-<operation name='echo' parameterOrder='echo'>
-<input message='tns:Echo_echo'/>
-<output message='tns:Echo_echoResponse'/>
-</operation>
+ <operation name='echo' parameterOrder='echo'>
+ <input message='tns:Echo_echo'/>
+ <output message='tns:Echo_echoResponse'/>
+ </operation>
</portType></programlisting>
<para>
<note><title>Note</title>
@@ -1308,15 +1124,15 @@
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
-<servlet>
-<servlet-name>Echo</servlet-name>
-<servlet-class>echo.Echo</servlet-class>
-</servlet>
+ <servlet>
+ <servlet-name>Echo</servlet-name>
+ <servlet-class>echo.Echo</servlet-class>
+ </servlet>
-<servlet-mapping>
-<servlet-name>Echo</servlet-name>
-<url-pattern>/Echo</url-pattern>
-</servlet-mapping>
+ <servlet-mapping>
+ <servlet-name>Echo</servlet-name>
+ <url-pattern>/Echo</url-pattern>
+ </servlet-mapping>
</web-app>
</programlisting>
<para>The <filename>web.xml</filename> and the single class can now be used to create a WAR:</para>
@@ -1334,20 +1150,20 @@
]]> </programlisting>
<para>The war can then be deployed:</para>
<programlisting> <![CDATA[
- cp echo.war /usr/local/jboss-4.2.0.GA-ejb3/server/default/deploy
+ cp echo.war $JBOSS_HOME/server/default/deploy
]]> </programlisting>
- <para>This will internally invoke <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide</ulink>, which will generate the WSDL. If deployment was successful, and you are using the default settings, it should be available here: <ulink url="http://localhost:8080/echo/Echo?wsdl">http://localhost:8080/echo/Echo?wsdl</ulink></para>
+ <para>At deploy time JBossWS will internally invoke <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink>, which will generate the WSDL. If deployment was successful, and you are using the default settings, it should be available here: <ulink url="http://localhost:8080/echo/Echo?wsdl">http://localhost:8080/echo/Echo?wsdl</ulink></para>
<para>For a portable JAX-WS deployment, the wrapper classes generated earlier could be added to the deployment.</para>
</section>
<section>
<title>Top-Down (Using wsconsume)</title>
- <para>The top-down development strategy begins with the abstract contract for the service, which includes the WSDL file and zero or more schema files. The <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsconsume">wsconsume</ulink> tool is then used to consume this contract, and produce annotated Java classes (and optionally sources) that define it.</para>
+ <para>The top-down development strategy begins with the abstract contract for the service, which includes the WSDL file and zero or more schema files. The <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsconsume">wsconsume</ulink> tool is then used to consume this contract, and produce annotated Java classes (and optionally sources) that define it.</para>
<para>
<note><title>Note</title>
<para>wsconsume seems to have a problem with symlinks on unix systems</para>
</note>
</para>
- <para>Using the WSDL file from the bottom-up example, a new Java implementation that adheres to this service can be generated. The "-k" option is passed to <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsconsume">wsconsume</ulink> to preserve the Java source files that are generated, instead of providing just classes:</para>
+ <para>Using the WSDL file from the bottom-up example, a new Java implementation that adheres to this service can be generated. The "-k" option is passed to <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsconsume">wsconsume</ulink> to preserve the Java source files that are generated, instead of providing just classes:</para>
<programlisting> <![CDATA[
$ wsconsume -k EchoService.wsdl
@@ -1436,15 +1252,13 @@
<para>Examining the Service Endpoint Interface reveals annotations that are more explicit than in the class written by hand in the bottom-up example, however, these evaluate to the same contract:</para>
<programlisting role="JAVA">
@WebService(name = "Echo", targetNamespace = "http://echo/")
-public interface Echo {
- at WebMethod
- at WebResult(targetNamespace = "")
- at RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type")
- at ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse")
-public String echo(
- at WebParam(name = "arg0", targetNamespace = "")
-String arg0);
-
+public interface Echo
+{
+ @WebMethod
+ @WebResult(targetNamespace = "")
+ @RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type")
+ @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse")
+ public String echo(@WebParam(name = "arg0", targetNamespace = "") String arg0);
}</programlisting>
<para>The only missing piece (besides the packaging) is the implementation class, which can now be written using the above interface.</para>
<programlisting role="JAVA">
@@ -1453,11 +1267,11 @@
@javax.jws.WebService(endpointInterface="echo.Echo")
public class EchoImpl implements Echo
{
-public String echo(String arg0)
-{
-return arg0;
+ public String echo(String arg0)
+ {
+ return arg0;
+ }
}
-}
</programlisting>
</section>
<section>
@@ -1469,22 +1283,22 @@
<emphasis>the top-down approach</emphasis>
</emphasis>
, even if the client is running on the same server.</para>
- <para>Let's repeat the process of the top-down section, although using the deployed WSDL, instead of the one generated offline by <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide</ulink>. The reason why we do this is just to get the right value for soap:address. This value must be computed at deploy time, since it is based on container configuration specifics. You could of course edit the WSDL file yourself, although you need to ensure that the path is correct.</para>
+ <para>Let's repeat the process of the top-down section, although using the deployed WSDL, instead of the one generated offline by <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide</ulink>. The reason why we do this is just to get the right value for soap:address. This value must be computed at deploy time, since it is based on container configuration specifics. You could of course edit the WSDL file yourself, although you need to ensure that the path is correct.</para>
<para>Offline version:</para>
<programlisting role="XML">
<service name='EchoService'>
-<port binding='tns:EchoBinding' name='EchoPort'>
-<soap:address location='REPLACE_WITH_ACTUAL_URL'/>
-</port>
+ <port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port>
</service></programlisting>
<para>Online version:</para>
<programlisting role="XML">
<service name="EchoService">
-<port binding="tns:EchoBinding" name="EchoPort">
-<soap:address location="http://localhost.localdomain:8080/echo/Echo"/>
-</port>
+ <port binding="tns:EchoBinding" name="EchoPort">
+ <soap:address location="http://localhost.localdomain:8080/echo/Echo"/>
+ </port>
</service></programlisting>
- <para>Using the online deployed version with <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsconsume">wsconsume</ulink>:</para>
+ <para>Using the online deployed version with <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsconsume">wsconsume</ulink>:</para>
<programlisting>
$ wsconsume -k http://localhost:8080/echo/Echo?wsdl
echo/Echo.java
@@ -1504,30 +1318,37 @@
@WebServiceClient(name = "EchoService", targetNamespace = "http://echo/", wsdlLocation = "http://localhost:8080/echo/Echo?wsdl")
public class EchoService extends Service
{
-private final static URL ECHOSERVICE_WSDL_LOCATION;
+ private final static URL ECHOSERVICE_WSDL_LOCATION;
-static {
-URL url = null;
-try {
-url = new URL("http://localhost:8080/echo/Echo?wsdl");
-} catch (MalformedURLException e) {
-e.printStackTrace();
-}
-ECHOSERVICE_WSDL_LOCATION = url;
-}
+ static
+ {
+ URL url = null;
+ try
+ {
+ url = new URL("http://localhost:8080/echo/Echo?wsdl");
+ }
+ catch (MalformedURLException e)
+ {
+ e.printStackTrace();
+ }
+ ECHOSERVICE_WSDL_LOCATION = url;
+ }
-public EchoService(URL wsdlLocation, QName serviceName) {
-super(wsdlLocation, serviceName);
-}
+ public EchoService(URL wsdlLocation, QName serviceName)
+ {
+ super(wsdlLocation, serviceName);
+ }
-public EchoService() {
-super(ECHOSERVICE_WSDL_LOCATION, new QName("http://echo/", "EchoService"));
-}
+ public EchoService()
+ {
+ super(ECHOSERVICE_WSDL_LOCATION, new QName("http://echo/", "EchoService"));
+ }
- at WebEndpoint(name = "EchoPort")
-public Echo getEchoPort() {
-return (Echo)super.getPort(new QName("http://echo/", "EchoPort"), Echo.class);
-}
+ @WebEndpoint(name = "EchoPort")
+ public Echo getEchoPort()
+ {
+ return (Echo)super.getPort(new QName("http://echo/", "EchoPort"), Echo.class);
+ }
}</programlisting>
<para>As you can see, this generated class extends the main client entry point in JAX-WS, <classname>javax.xml.ws.Service</classname>. While you can use <classname>Service</classname> directly, this is far simpler since it provides the configuration info for you. The only method we really care about is the <methodname>getEchoPort()</methodname> method, which returns an instance of our <classname>Service Endpoint Interface</classname>. Any Web Services operation can then be called by just invoking a method on the returned interface.</para>
@@ -1543,20 +1364,20 @@
..
public class EchoClient
{
-public static void main(String args[])
-{
-if (args.length != 1)
-{
-System.err.println("usage: EchoClient <message>");
-System.exit(1);
-}
+ public static void main(String args[])
+ {
+ if (args.length != 1)
+ {
+ System.err.println("usage: EchoClient <message>");
+ System.exit(1);
+ }
-EchoService service = new EchoService();
-Echo echo = service.getEchoPort();
-System.out.println("Server said: " + echo.echo(args[0]));
-}
+ EchoService service = new EchoService();
+ Echo echo = service.getEchoPort();
+ System.out.println("Server said: " + echo.echo(args[0]));
+ }
}</programlisting>
- <para>It can then be easily executed using the <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsrunclient">wsrunclient</ulink> tool. This is just a convenience tool that invokes java with the needed classpath:</para>
+ <para>It can then be easily executed using the <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsrunclient">wsrunclient</ulink> tool. This is just a convenience tool that invokes java with the needed classpath:</para>
<programlisting> <![CDATA[
$ wsrunclient EchoClient 'Hello World!'
Server said: Hello World!
@@ -1581,17 +1402,17 @@
<itemizedlist>
<listitem>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsconsume">wsconsume reference page</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsconsume">wsconsume reference page</ulink>
</para>
</listitem>
<listitem>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide reference page</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsprovide">wsprovide reference page</ulink>
</para>
</listitem>
<listitem>
<para>
- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsrunclient">wsrunclient reference page</ulink>
+ <ulink url="http://www.jboss.org/community/wiki/JBossWS-wsrunclient">wsrunclient reference page</ulink>
</para>
</listitem>
</itemizedlist>
@@ -1780,266 +1601,9 @@
</section>
<section>
<title>WS-BPEL</title>
- <para>WS-BPEL is not supported with JAX-WS, please refer to <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-RPC_User_Guide#WS-BPEL">JAX-RPC User Guide#WS-BPEL</ulink>.</para>
+ <para>WS-BPEL is not supported with JAX-WS, please refer to <ulink url="http://www.jboss.org/community/wiki/JBossWS-JAX-RPCUserGuide#WSBPEL">JAX-RPC User Guide#WS-BPEL</ulink>.</para>
</section>
<section>
- <title>WS-Eventing</title>
- <para>WS-Eventing specifies a set of operations that allow an event consumer to register (subscribe) with an event producer (source) to receive events (notifications) in an asynchronous fashion.</para>
- <section>
- <title>Specifications</title>
- <para>WS-Eventing is defined by the combination of the following specifications:</para>
- <itemizedlist>
- <listitem>
- <para>
- <ulink url="ftp://www6.software.ibm.com/software/developer/library/ws-eventing/WS-Eventing.pdf">WS-Eventing specification</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://www.w3.org/TR/ws-addr-core">WS-Addressing Specifications</ulink>
- </para>
- </listitem>
- </itemizedlist>
- <para>The following section will introduce the main eventing actors and their responsiblities.</para>
- <para>
- <note>
- <para>The original eventing specification builds upon WS-Addressing 2004/08. JBossWS however decided to stick to the latest version, which is the W3C candidate release.</para>
- </note>
- </para>
- </section>
- <section>
- <title>Collaboration</title>
- <para>
- <!-- <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Image:EventingCollaboration.gif">
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="./http://jbws.dyndns.org/mediawiki/images/8/8a/EventingCollaboration.gif" format="GIF"/>
- </imageobject>
- </inlinemediaobject>
- </ulink>
- </para>
- <para>Eventing collaboration</para>-->
- <orderedlist>
- <listitem>
- <para> An event sink (web service client) sends a subscribtion request to the event source endpoint. This includes the event sink endpoint address where notifications should delivered. Upon successful subscription the sink receives a leased subscription ID that can be used to identify the client in subsequent requests.</para>
- </listitem>
- <listitem>
- <para> A successfully registered event sink directs management requests (Renew, GetStatus, Unsubscribe) to the subscription manager endpoint using the previously received subscription ID. The subscription manager endpoint address was returned as part of the subscription response in the first place.</para>
- </listitem>
- <listitem>
- <para> The actual event sink (application) emits notification messages through the JBossWS-Eventing module. JBossWS-Eventing dispatches the notification to any subscriber endpoint that is registered with a particular event source.s</para>
- </listitem>
- <listitem>
- <para> Besides notifications JBossWS-Eventing may emit lifecycle events at any time. For instance, to inform an event sink that a subscription was canceled. This can be the case when the subscription expired or the event source was undeployed.</para>
- </listitem>
- </orderedlist>
- </para>
- <para>It is the users responsibilty to supply the web service endpoints (EventSourceEndpoint, SubscriptionManagerEndpoint) that are required for a complete event source deployment. Fortunatly JBossWS-Eventing already ships with a implementation that can be used right away. All that is left to do is the packaging of standard JSR-109 deployment archive that includes the event source specific WSDL and points to the JBossWS-Eventing endpoint implementations.</para>
- <para>The relevant steps are:</para>
- <itemizedlist>
- <listitem>
- <para> Create a custom WSDL that describes your event source, in respect to the notification schema and the fact that is actually contains an event source port </para>
- </listitem>
- <listitem>
- <para> Use the JBossWS SEI and endpoint implementations (webservices.xml, web.xml).</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Setup an event source endpoint</title>
- <para>With JAX-WS the event source setup has actually become quiet easy. All you need to do is to subclass your endpoint implementation from <literal>AbstractEventSourceEndpoint</literal> and a subscription manager from <literal>AbstractSubscriptionManagerEndpoint</literal> and finally point that implementation to a <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#The_WSDL_that_describes_an_event_source">event source specific WSDL</ulink>.</para>
-<programlisting role="JAVA">
-package org.jboss.test.ws.jaxws.samples.wseventing;
-..
-import javax.jws.WebService;
-
-import org.jboss.logging.Logger;
-import org.jboss.ws.annotation.EndpointConfig;
-import org.jboss.ws.extensions.eventing.jaxws.AbstractEventSourceEndpoint;
-
-/**
-* @author Heiko.Braun at jboss.org
-* @version $Id$
-* @since 18.01.2007
-*/
- at WebService( (1)
-name = "EventSource",
-portName = "EventSourcePort",
-targetNamespace = "http://schemas.xmlsoap.org/ws/2004/08/eventing",
-wsdlLocation = "/WEB-INF/wsdl/sysmon.wsdl", (2)
-endpointInterface = "org.jboss.ws.extensions.eventing.jaxws.EventSourceEndpoint")
- at EndpointConfig(configName = "Standard WSAddressing Endpoint") (3)
-public class SysmonRegistrationEndpoint extends AbstractEventSourceEndpoint { (4)
-
-private static final Logger log = Logger.getLogger(SysmonRegistrationEndpoint.class);
-
-protected Logger getLogger()
-{
-return log;
-}
-}</programlisting>
- <orderedlist>
- <listitem>
- <para> Of course we need a <literal>@WebService</literal> annotation</para>
- </listitem>
- <listitem>
- <para> It's important to override the WSDL here</para>
- </listitem>
- <listitem>
- <para> You need to tell JBossWS that it requires WS-Addressing for this endpoint</para>
- </listitem>
- <listitem>
- <para> Subclass a predefined implementation that knows how to delegate to the actual eventing service implementation</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>The WSDL that describes an event source</title>
- <para>Even though we are already using the annotation driven approach, JBossWS eventing still requires an event source specific WSDL.</para>
- <para>The following excerpt shows the relevant WSDL details that describe an event source.</para>
-<programlisting role="XML">
-<?xml version="1.0" encoding="UTF-8"?>
-
-<wsdl:definitions
-targetNamespace="http://www.jboss.org/sysmon"
-xmlns:tns="http://www.jboss.org/sysmon"
-xmlns:wse='http://schemas.xmlsoap.org/ws/2004/08/eventing'
-xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
-xmlns:wsa10='http://www.w3.org/2005/08/addressing'
-xmlns:xs='http://www.w3.org/2001/XMLSchema'
-xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
-
-<wsdl:import
-(1) namespace='http://schemas.xmlsoap.org/ws/2004/08/eventing'
-location='jbwse.wsdl' />
-
-<wsdl:types>
-
-<xs:schema targetNamespace='http://schemas.xmlsoap.org/ws/2004/08/eventing'>
-(2) <xs:include schemaLocation='jbwse.xsd'/>
-</xs:schema>
-
-(3) <xs:schema
-targetNamespace="http://www.jboss.org/sysmon"
-elementFormDefault="qualified"
-blockDefault="#all">
-<xs:element name="SystemStatus">
-<xs:complexType>
-<xs:sequence>
-<xs:element name="Time " type="xs:dateTime"/>
-<xs:element name="HostName" type="xs:string"/>
-<xs:element name="HostAddress" type="xs:string"/>
-<xs:element name="ActiveThreadCount" type="xs:int"/>
-<xs:element name="FreeMemory" type="xs:string"/>
-<xs:element name="MaxMemory" type="xs:string"/>
-</xs:sequence>
-</xs:complexType>
-</xs:element>
-</xs:schema>
-
-</wsdl:types>
-
-<wsdl:message name='SystemInfoMsg'>
-<wsdl:part name='body' element='tns:SystemStatus'/>
-</wsdl:message>
-
-(4) <wsdl:portType name='SystemInfo' wse:EventSource='true'>
-<wsdl:operation name='SysmonOp'>
-<wsdl:output message='tns:SystemInfoMsg'/>
-</wsdl:operation>
-</wsdl:portType>
-
-<wsdl:binding name="SystemInfoBinding" type="tns:SystemInfo">
-<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
-<wsdl:operation name="SysmonOp">
-<soap:operation soapAction=""/>
-<wsdl:output>
-<soap:body use="literal"/>
-</wsdl:output>
-</wsdl:operation>
-</wsdl:binding>
-
-</wsdl:definitions></programlisting>
- <orderedlist>
- <listitem>
- <para> Import the default eventing WSDL, that includes service and port declarations.</para>
- </listitem>
- <listitem>
- <para> Include the default eventing Types</para>
- </listitem>
- <listitem>
- <para> Specifiy the notitification message schema.</para>
- </listitem>
- <listitem>
- <para> Declare a port type, attributed <code>"wse:EventSource='true'"</code> that points to your notification message schema.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>Emitting notifications</title>
- <para>JBossWS-Eventing registeres a event dispatcher within local JNDI tree that can be used to emit notifications from applications.</para>
-<programlisting>
-java:/EventDispatcher
-</programlisting>
-
-<para>The event dispatcher interface:</para>
-<programlisting role="JAVA">
-public interface EventDispatcher
-{
-void dispatch(URI eventSourceNS, Element payload);
-}
-</programlisting>
-
-<para>
- <emphasis role="bold">Example notification</emphasis>
- </para>
-<programlisting role="JAVA">
-(1) URI eventSourceURI = new URI("http://http://www.jboss.org/sysmon/SystemInfo");
-(2) Element payload = DOMUtils.parse("SOME XML STRING");
-try
-{
-InitialContext iniCtx = getInitialContext();
-(3) EventDispatcher delegate = (EventDispatcher)
-iniCtx.lookup(EventingConstants.DISPATCHER_JNDI_NAME);
-(4) delegate.dispatch(eventSourceURI, payload);
-}
-catch (Exception e)
-{
-//
-} </programlisting>
- <orderedlist>
- <listitem>
- <para> Address your event source correctly (TargetNamespace+PortTypeName)</para>
- </listitem>
- <listitem>
- <para> Create your payload</para>
- </listitem>
- <listitem>
- <para> Lookup dispatcher from JNDI</para>
- </listitem>
- <listitem>
- <para> Dispatch notification.</para>
- </listitem>
- </orderedlist>
- <para>The SubscriptionManager MBean is the actual core component that drives the JBossWS-Eventing implementation. It can be accessed through the jmx-console.</para>
-<programlisting> <![CDATA[
-jboss.ws.eventing:service=SubscriptionManager
-]]> </programlisting>
- <para>Management operations exist to monitor and maintain active subscritions and deployed event sources. The current implementation is backed by a ThreadPoolExecutor, that asynchronously delivers messages to event sink endpoints. It can be configured through the following attributes:</para>
- <itemizedlist>
- <listitem>
- <para> corePoolSize - average number of idle threads</para>
- </listitem>
- <listitem>
- <para> maximumPoolSize - maximum number of threads</para>
- </listitem>
- <listitem>
- <para> eventKeepAlive - keep alive before an undelivered event message is discarded.</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section>
<title>WS-Security</title>
<para>WS-Security addresses message level security. It standardizes authorization, encryption, and digital signature processing of web services. Unlike transport security models, such as SSL, WS-Security applies security directly to the elements of the web service message. This increases the flexibility of your web services, by allowing any message model to be used (point to point, multi-hop relay, etc).</para>
<para>This chapter describes how to use WS-Security to sign and encrypt a simple SOAP message.</para>
More information about the jboss-cvs-commits
mailing list