[jboss-cvs] JBossAS SVN: r67148 - projects/docs/trunk/Server_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Nov 15 14:13:13 EST 2007
Author: skittoli at redhat.com
Date: 2007-11-15 14:13:12 -0500 (Thu, 15 Nov 2007)
New Revision: 67148
Modified:
projects/docs/trunk/Server_Configuration_Guide/en-US/Naming.xml
projects/docs/trunk/Server_Configuration_Guide/en-US/Web_Services.xml
Log:
updates
Modified: projects/docs/trunk/Server_Configuration_Guide/en-US/Naming.xml
===================================================================
--- projects/docs/trunk/Server_Configuration_Guide/en-US/Naming.xml 2007-11-15 17:54:47 UTC (rev 67147)
+++ projects/docs/trunk/Server_Configuration_Guide/en-US/Naming.xml 2007-11-15 19:13:12 UTC (rev 67148)
@@ -349,7 +349,7 @@
</listitem>
</itemizedlist>
<para>
- The JNDI <literal>Context</literal> implementation returned by the <literal>HttpNamingContextFactory</literal> is a proxy that delegates invocations made on it to a bridge servlet which forwards the invocation to the <literal>NamingService</literal> through the JMX bus and marshalls the reply back over HTTP. The proxy needs to know what the URL of the bridge servlet is in order to operate. This value may have been bound on the server side if the JBoss web server has a well known public interface. If the JBoss web server is sitting behind one or more firewalls or proxies, the proxy cannot know what URL is required. In this case, the proxy will be associated with a system property value that must be set in the client VM. For more information on the operation of JNDI over HTTP see <xref linkend="JNDI_over_HTTP-Accessing_JNDI_over_HTTP" />.
+ The JNDI <literal>Context</literal> implementation returned by the <literal>HttpNamingContextFactory</literal> is a proxy that delegates invocations made on it to a bridge servlet. The bridge sevlet forwards the invocation to the <literal>NamingService</literal> through the JMX bus and marshalls the reply back over HTTP. The proxy needs to know what the URL of the bridge servlet is in order to operate. This value may have been bound on the server side if the JBoss web server has a well known public interface. If the JBoss web server is sitting behind one or more firewalls or proxies, the proxy cannot know what URL is required. In this case, the proxy will be associated with a system property value that must be set in the client VM. For more information on the operation of JNDI over HTTP see <xref linkend="JNDI_over_HTTP-Accessing_JNDI_over_HTTP" />.
</para>
</section>
@@ -513,7 +513,7 @@
<itemizedlist>
<listitem>
<para>
- A <literal>namingProxyMBean</literal> initialization parameter that maps to the <literal>HttpProxyFactory</literal> MBean name. This is used by the <literal>NamingFactoryServlet</literal> to obtain the <literal>Naming</literal> proxy which it will return in response to HTTP posts. For the default <literal>http-invoker.sar/META-INF/jboss-service.xml</literal> settings the name <literal>jboss:service=invoker,type=http,target=Naming</literal>.
+ A <literal>namingProxyMBean</literal> initialization parameter that maps to the <literal>HttpProxyFactory</literal> MBean name. This is used by the <literal>NamingFactoryServlet</literal> to obtain the <literal>Naming</literal> proxy which it will return in response to HTTP posts. For the default <literal>http-invoker.sar/META-INF/jboss-service.xml</literal> settings the name <literal>jboss:service=invoker,type=http,target=Naming</literal> is used.
</para>
</listitem>
<listitem>
@@ -862,7 +862,7 @@
</mbean>
</programlisting>
<para>
- This binds the text string "<literal>Hello, JNDI!</literal>" under the JNDI name <literal>bindexample/message</literal>. An application would look up the value just as it would for any other JNDI value. The <literal>trim</literal> attribute specifies that leading and trailing whitespace should be ignored. The use of the attribute here is purely for illustrative purposes as the default value is true.
+ This binds the text string "<literal>Hello, JNDI!</literal>" under the JNDI name <literal>bindexample/message</literal>. An application would look up the value just as it would for any other JNDI value. The <literal>trim</literal> attribute specifies that leading and trailing whitespaces should be ignored. The use of the attribute here is purely for illustrative purposes as the default value is true.
</para>
<programlisting>InitialContext ctx = new InitialContext();
String text = (String) ctx.lookup("bindexample/message");
@@ -1045,7 +1045,7 @@
Context ldapCtx = iniCtx.lookup("external/fs/usr/local");
</programlisting>
<para>
- Note that the use the Sun JNDI service providers, which must be downloaded from <ulink url="http://java.sun.com/products/jndi/serviceproviders.html"></ulink>. The provider JARs should be placed in the server configuration <literal>lib</literal> directory.
+ Note that you need to use the Sun JNDI service providers, which must be downloaded from <ulink url="http://java.sun.com/products/jndi/serviceproviders.html"></ulink>. The provider JARs should be placed in the server configuration <literal>lib</literal> directory.
</para>
</section>
Modified: projects/docs/trunk/Server_Configuration_Guide/en-US/Web_Services.xml
===================================================================
--- projects/docs/trunk/Server_Configuration_Guide/en-US/Web_Services.xml 2007-11-15 17:54:47 UTC (rev 67147)
+++ projects/docs/trunk/Server_Configuration_Guide/en-US/Web_Services.xml 2007-11-15 19:13:12 UTC (rev 67148)
@@ -4,678 +4,2635 @@
<chapter id="Web_Services">
<title>Web Services</title>
+
+ <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. No need to agree on such low level details as operation names and their associated parameters.
+ The payload of the SOAP message is an XML document that can be validated against XML schema.
+ Document is defined by the style attribute on the SOAP binding.
+ </para>
<para>
- The biggest new feature of J2EE 1.4 is the ability of J2EE components to act both as web service providers and consumers. J2EE applications can expose a web service from the EJB tier using a stateless session bean or from the web tier using a plain Java object. Additionally,J2EE components have a standard way of declaring references to external web services.
+<programlisting>
+ <![CDATA[
+<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>]]>
+</programlisting>
</para>
- <section id="Web_Services-JAX_RPC_Service_Endpoints">
- <title>JAX-RPC Service Endpoints</title>
+
+ <para>
+ With document style web services the payload of every message is defined by a complex type in XML schema.
+
+<programlisting>
+<![CDATA[
+<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'/>
+</message>
+ ]]>
+</programlisting>
+ </para>
+
+ </section>
+
+
+ <section><title>Document/Literal (Bare)</title>
<para>
- JAX-RPC service endpoints (JSEs) provide web services from the web tier. They take the form of a simple Java objects that masquerade as servlets. To show how simple they are, we'll jump right in with a trivial hello web service implementation class.
- </para>
-<programlisting>package org.jboss.ws.hello;
-
-public class HelloPojo
+ Bare is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a bare endpoint recognizable.
+ A bare endpoint or client uses a Java bean that represents the entire document payload.
+<programlisting>
+<![CDATA[
+ at WebService
+ at SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
+public class DocBareServiceImpl
{
- public String hello(String name)
- {
- return "Hello " + name + "!";
- }
+ at WebMethod
+public SubmitBareResponse submitPO(SubmitBareRequest poRequest)
+{
+ ...
}
+}
+]]>
</programlisting>
- <para>
- There is nothing remarkable about <literal>HelloPojo</literal>. It doesn't implement any special interfaces nor does it need any methods besides the business methods it decides to provide. The <literal>hello</literal> method is the operation that we will expose as a web service, and it does nothing but respond with a friendly greeting to the person passed in.
</para>
+
<para>
- That is our web service implementation. In addition to this, we need a service endpoint interface (SEI) that defines the interface of the web service. That is shown here as the <literal>Hello</literal> interface.
+ The trick is that the Java beans representing the payload contain JAXB annotations that define how the payload is represented on the wire.
+<programlisting>
+ <![CDATA[
+ @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;
+
+ ...
+}]]></programlisting>
</para>
-<programlisting>package org.jboss.ws.hello;
-
-import java.rmi.Remote;
-import java.rmi.RemoteException;
-
-public interface Hello
- extends Remote
-{
- public String hello(String name)
- throws RemoteException;
-}
-</programlisting>
+ </section>
+
+ <section><title>Document/Literal (Wrapped)</title>
<para>
- The service endpoint interface is declared <literal>Remote</literal> and the methods must throw <literal>RemoteException</literal>. Beyond this, it is a simple expression of the interface to our web service. This is all the code we need to write to expose a J2EE web service. Deploying it, however, does require a few additional deployment descriptors.
+ Wrapped is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a wrapped endpoint recognizable.
+ A wrapped endpoint or client uses the individual document payload properties. Wrapped is the default and does not have to be declared explicitly.
+<programlisting>
+<![CDATA[
+ at WebService
+public class DocWrappedServiceImpl
+ {
+ @WebMethod
+ @RequestWrapper (className="org.somepackage.SubmitPO")
+ @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
+ public String submitPO(String product, int quantity)
+ {
+ ...
+ }
+ }]]></programlisting>
+
+Note, that with JBossWS the request/response wrapper annotations are not required, they will be generated on demand using sensible defaults.
</para>
+
+ </section>
+
+ <section><title>RPC/Literal</title>
<para>
- Although a JSE doesn't bears any direct resemblance to a servlet, it is nonetheless deployed as a servlet in the <literal>web.xml</literal> file. We'll need to declare the web service implementation class as a servlet and provide a servlet mapping that will respond to the web service invocations. Here is the definition required to deploy the hello web service.
+ With RPC there is a wrapper element that names the endpoint operation. Child elements of the RPC parent are the individual parameters.
+ The SOAP body is constructed based on some simple rules:
+ <itemizedlist>
+ <listitem>
+ <para>
+ The port type operation name defines the endpoint method name
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Message parts are endpoint method parameters
+ </para>
+ </listitem>
+ </itemizedlist>
+
+RPC is defined by the style attribute on the SOAP binding.
+<programlisting>
+ <![CDATA[
+ <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>
</para>
-<programlisting><?xml version="1.0" encoding="UTF-8"?>
-<web-app xmlns="http://java.sun.com/xml/ns/"Whats_new_in_JBoss_4-J2EE_Certification_and_Standards_Compliance"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- 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>HelloWorldWS</servlet-name>
- <servlet-class>org.jboss.ws.hello.HelloPojo</servlet-class>
- </servlet>
+
+<para>
+ With rpc style web services the portType names the operation (i.e. the java method on the endpoint)
+<programlisting>
+<![CDATA[ <portType name='EndpointInterface'>
+ <operation name='echo' parameterOrder='String_1'>
+ <input message='tns:EndpointInterface_echo'/>
+ <output message='tns:EndpointInterface_echoResponse'/>
+ </operation>
+ </portType> ]]></programlisting>
- <servlet-mapping>
- <servlet-name>HelloWorldWS</servlet-name>
- <url-pattern>/Hello</url-pattern>
- </servlet-mapping>
-</web-app>
-</programlisting>
+ Operation parameters are defined by individual message parts.
+<programlisting><![CDATA[
+ <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, there is no complex type in XML schema that could validate the entire SOAP message payload.
+
+<programlisting>
+<![CDATA[
+ @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class JSEBean01
+ {
+ @WebMethod
+ @WebResult(name="result")
+ public String echo(@WebParam(name="String_1") String input)
+ {
+ ...
+ }
+} ]]></programlisting>
+
+The element names of RPC parameters/return values may be defined using the JAX-WS Annotations#javax.jws.WebParam and JAX-WS Annotations#javax.jws.WebResult respectively.
+
+</para>
+
+ </section>
+
+ <section><title>RPC/Encoded</title>
<para>
- The URL pattern in the servlet mapping is the only externally visible configuration element. It controls what URL the web service lives at. This will be primarily noticed as the location of the WSDL file for this service.
+ SOAP encodeding style is defined by the infamous <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512">chapter 5</ulink> of the <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">SOAP-1.1</ulink> specification. It has inherent interoperability issues that cannot be fixed. The <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html">Basic Profile-1.0</ulink> prohibits this encoding style in <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement16448072">4.1.7 SOAP encodingStyle Attribute</ulink>.
+
+ JBossWS has basic support for rpc/encoded that is provided as is for simple interop scenarios with SOAP stacks that do not support literal encoding.
+ Specifically, JBossWS does not support:-
+ <itemizedlist>
+ <listitem>
+ <para>
+ element references
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ soap arrays as bean properties
+ </para>
+ </listitem>
+ </itemizedlist>
+
</para>
- <para>
- The <literal>web.xml</literal> file doesn't contain any web service related configuration. A new deployment descriptor, <literal>webservices.xml</literal>, is needed to instruct JBoss to treat this servlet as a web service and not as a normal servlet. We'll need two additional configuration files, a WSDL file and a JAX-RPC mapping file. All of these files can be generated using the <literal>wstool</literal> generator that ships with JBoss.
+
+ </section>
+
+ <section><title>Web Service Endpoints </title>
+ <para>JAX-WS simplifies the development model for a web service endpoint a great deal. In short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. The server automatically generates and publishes the abstract contract (i.e. wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to JAXB [2].
</para>
- <para>
- <literal>wstool</literal> can be run from from the command line or as an Ant task. The JBossWS guide explains in more detail how to run the tool. In both cases, wstool needs to be pointed to the code and to a configuration file which describes the files to generate and the endpoint to generate them for. Here is the configuration file for the hello web service.
+
+ </section>
+
+
+
+ <section><title>Plain old Java Object (POJO)</title>
+ <para>Let's take a look at simple POJO endpoint implementation. All endpoint associated metadata is provided via JSR-181 annotations
+<programlisting><![CDATA[@WebService
+ at SOAPBinding(style = SOAPBinding.Style.RPC)
+public class JSEBean01
+ {
+ @WebMethod
+ public String echo(String input)
+ {
+ ...
+ }
+ } ]]></programlisting>
+
</para>
-<programlisting><configuration xmlns="http://www.jboss.org/jbossws-tools">
- <java-wsdl>
- <service name="HelloService"
- style="rpc"
- endpoint="org.jboss.ws.hello.Hello"/>
- <namespaces target-namespace="http://hello.ws.jboss.org/"
- type-namespace="http://hello.ws.jboss.org/types"/>
- <mapping file="jaxrpc-mapping.xml"/>
- <webservices servlet-link="HelloWorldWS"/>
- </java-wsdl>
-</configuration>
-</programlisting>
+
+ </section>
+
+ <section><title>The endpoint as a web application</title>
<para>
- For a complete description of this file, see the JBossWS documentation.
- </para>
- <para>
- The WSDL file that wscompile generated for our <literal>config.xml</literal> file is shown below. Note that the SOAP address isn't provided in the WSDL file. JBoss will insert the correct URL for the WSDL when it deploys the web service.
- </para>
-<programlisting><definitions name="HelloService"
- targetNamespace="http://hello.ws.jboss.org/"
- xmlns="http://schemas.xmlsoap.org/wsdl/"
- xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
- xmlns:tns="http://hello.ws.jboss.org/"
- xmlns:xsd="http://www.w3.org/2001/XMLSchema">
- <types/>
- <message name="Hello_hello">
- <part name="String_1" type="xsd:string"/>
- </message>
- <message name="Hello_helloResponse">
- <part name="result" type="xsd:string"/>
- </message>
- <portType name="Hello">
- <operation name="hello" parameterOrder="String_1">
- <input message="tns:Hello_hello"/>
- <output message="tns:Hello_helloResponse"/>
- </operation>
- </portType>
- <binding name="HelloBinding" type="tns:Hello">
- <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
- <operation name="hello">
- <soap:operation soapAction=""/>
- <input>
- <soap:body namespace="http://hello.ws.jboss.org/" use="literal"/>
- </input>
- <output>
- <soap:body namespace="http://hello.ws.jboss.org/" use="literal"/>
- </output>
- </operation>
- </binding>
- <service name="HelloService">
- <port binding="tns:HelloBinding" name="HelloPort">
- <soap:address location="REPLACE_WITH_ACTUAL_URL"/>
- </port>
- </service>
-</definitions>
+ A JAX-WS java service endpoint (JSE) is deployed as a web application.
+
+<programlisting>
+ <![CDATA[
+ <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>
+ </web-app> ]]>
</programlisting>
- <para>
- We also asked wscompile to generate a JAX-RPC mapping file. This is shown below.
+
</para>
-<programlisting><?xml version='1.0' encoding='UTF-8'?>
-<java-wsdl-mapping version="1.1"
- xmlns="http://java.sun.com/xml/ns/"Whats_new_in_JBoss_4-J2EE_Certification_and_Standards_Compliance"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
- http://www.ibm.com/webservices/xsd/j2ee_jaxrpc_mapping_1_1.xsd">
- <package-mapping>
- <package-type>org.jboss.ws.hello</package-type>
- <namespaceURI>http://hello.ws.jboss.org/types</namespaceURI>
- </package-mapping>
- <service-interface-mapping>
- <service-interface>org.jboss.ws.hello.HelloService</service-interface>
- <wsdl-service-name xmlns:serviceNS="http://hello.ws.jboss.org/">
- serviceNS:HelloService
- </wsdl-service-name>
- <port-mapping>
- <port-name>HelloPort</port-name>
- <java-port-name>HelloPort</java-port-name>
- </port-mapping>
- </service-interface-mapping>
- <service-endpoint-interface-mapping>
- <service-endpoint-interface>org.jboss.ws.hello.Hello</service-endpoint-interface>
- <wsdl-port-type xmlns:portTypeNS="http://hello.ws.jboss.org/">
- portTypeNS:Hello
- </wsdl-port-type>
- <wsdl-binding xmlns:bindingNS="http://hello.ws.jboss.org/">
- bindingNS:HelloBinding
- </wsdl-binding>
- <service-endpoint-method-mapping>
- <java-method-name>hello</java-method-name>
- <wsdl-operation>hello</wsdl-operation>
- <method-param-parts-mapping>
- <param-position>0</param-position>
- <param-type>java.lang.String</param-type>
- <wsdl-message-mapping>
- <wsdl-message xmlns:wsdlMsgNS="http://hello.ws.jboss.org/">
- wsdlMsgNS:Hello_hello
- </wsdl-message>
- <wsdl-message-part-name>String_1</wsdl-message-part-name>
- <parameter-mode>IN</parameter-mode>
- </wsdl-message-mapping>
- </method-param-parts-mapping>
- <wsdl-return-value-mapping>
- <method-return-value>java.lang.String</method-return-value>
- <wsdl-message xmlns:wsdlMsgNS="http://hello.ws.jboss.org/">
- wsdlMsgNS:Hello_helloResponse
- </wsdl-message>
- <wsdl-message-part-name>result</wsdl-message-part-name>
- </wsdl-return-value-mapping>
- </service-endpoint-method-mapping>
- </service-endpoint-interface-mapping>
-</java-wsdl-mapping>
-</programlisting>
+
+ </section>
+
+ <section><title>Packaging the endpoint</title>
<para>
- Finally, we generates a <literal>webservices.xml</literal> file. This file links to our WSDL file with the <literal>wsdl-file</literal> element and to the mapping file using the <literal>jaxrpc-mapping-file</literal> element.
+ A JSR-181 java service endpoint (JSE) is packaged as a web application in a *.war file.
+
+<programlisting>
+<![CDATA[
+ <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>
+</war> ]]></programlisting>
+
+Note, only the endpoint implementation bean and web.xml are required.
</para>
- <para>
- In addition to this, a <literal>port-component</literal> element is needed that maps a port in the WSDL file to a particular service implementation. For our JSE, this is done with a <literal>servlet-link</literal> inside the <literal>service-impl-bean</literal> element. The servlet link must be the same as the name of the pseudo-servlet we declared in the <literal>web.xml</literal> file.
- </para>
-<programlisting><webservices version="1.1"
- xmlns="http://java.sun.com/xml/ns/"Whats_new_in_JBoss_4-J2EE_Certification_and_Standards_Compliance" xmlns:impl="http://hello.ws.jboss.org/"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
- http://www.ibm.com/webservices/xsd/j2ee_web_services_1_1.xsd">
- <webservice-description>
- <webservice-description-name>HelloService</webservice-description-name>
- <wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
- <jaxrpc-mapping-file>WEB-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file>
- <port-component>
- <port-component-name>HelloPort</port-component-name>
- <wsdl-port>impl:HelloPort</wsdl-port>
- <service-endpoint-interface>org.jboss.ws.hello.Hello</service-endpoint-interface>
- <service-impl-bean>
- <servlet-link>HelloWorldWS</servlet-link>
- </service-impl-bean>
- </port-component>
- </webservice-description>
-</webservices>
-</programlisting>
- <para>
- With these completed we can deploy the WAR file containing our web service. All the deployment descriptors go in the <literal>WEB-INF</literal> directory, as shown in <xref linkend="JAX_RPC_Service_Endpoints-The_structure_of_hello_servlet.war" />. It's important to note that the WSDL file is required to be in the wsdl subdirectory.
- </para>
- <figure id="JAX_RPC_Service_Endpoints-The_structure_of_hello_servlet.war">
- <title>The structure of hello-servlet.war</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/hello-servlet.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- To deploy and test the hello web service, run the following from the examples directory:
- </para>
-<programlisting>[examples]$ ant -Dchap=ws -Dex=1 run-example
-...
-run-example1:
- [echo] Waiting for 5 seconds for deploy...
- [java] Contacting webservice at http://localhost:8080/hello-servlet/Hello?wsdl
- [java] hello.hello(JBoss user)
- [java] output:Hello JBoss user!
-</programlisting>
- <para>
- The server log will contain information about the deployment including the temporary location of the generated WSDL and wsdd files. It also shows the full URL of the web service.
- </para>
- <para>
- Note the URL the JBoss publishes the WSDL file at. Our web application name is <literal>hello-servlet</literal> and we mapped the servlet to <literal>/Hello</literal> in the <literal>web.xml</literal> file so the web service is mappend to <literal>/hello-servlet/Hello</literal>. The <literal>?wsdl</literal> query returns the WSDL file.
- </para>
- <para>
- If you aren't sure what the URL of the WSDL file will be, JBoss provides a way to list the web services available on the system at <literal>/jbossws/services</literal>. <xref linkend="JAX_RPC_Service_Endpoints-The_web_services_list" /> shows a view of the services list.
- </para>
- <figure id="JAX_RPC_Service_Endpoints-The_web_services_list">
- <title>The web services list</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/jbossws-view.png" />
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- The services list shows all of the deployed web services along with the name of the deployment unit and a link to the WSDL file for that service.
- </para>
+
</section>
- <section id="Web_Services-EJB_Endpoints">
- <title>EJB Endpoints</title>
+
+
+
+
+
+ <section>
+ <title>Accessing the generated WSDL</title>
+ <para>A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated wsdl.</para>
<para>
- Web services can also be provided from the EJB tier. Any stateless session bean can serve as the endpoint for a web service in almost the same way as the JAX-RPC endpoints. To see how this works, we will adapt the <literal>HelloServlet</literal> example into a session bean. Here is the code:
- </para>
-<programlisting>package org.jboss.ws.hello;
+<programlisting> <![CDATA[
+http://yourhost:8080/jbossws/services
+]]> </programlisting>
-import javax.ejb.EJBException;
-import javax.ejb.SessionBean;
-import javax.ejb.SessionContext;
+Note, it is also possible to generate the abstract contract off line using jbossw 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>
+ </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>
+<programlisting> <![CDATA[
+ @Stateless
+ @Remote(EJB3RemoteInterface.class)
+ @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface")
+
+ @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class EJB3Bean01 implements EJB3RemoteInterface
+ {
+ @WebMethod
+ public String echo(String input)
+ {
+ ...
+ }
+ }]]> </programlisting>
-public class HelloBean
- implements SessionBean
-{
- public String hello(String name)
- {
- return "Hello " + name + "!";
- }
-
- public void ejbCreate() {};
- public void ejbRemove() {};
-
- public void ejbActivate() {}
- public void ejbPassivate() {}
-
- public void setSessionContext(SessionContext ctx) {}
-}
-</programlisting>
+ <para>Above you see an EJB-3.0 stateless session bean that exposes one method both on the remote interface and on and as an endpoint operation.</para>
<para>
- This is a very trivial session bean. Session beans normally require a home interface and either a local or remote interface. However, it is possible to omit them if the session bean is only serving as a web services endpoint. However, we do still need the <literal>Hello</literal> service endpoint interface that we used in the JSE example.
+ <emphasis role="bold">Packaging the endpoint</emphasis>
</para>
+ <para>A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment.</para>
+<programlisting> <![CDATA[
+<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>
+</jar>]]> </programlisting>
<para>
- The <literal>ejb-jar.xml</literal> file is very standard for a session bean. The normal session bean parameters are explained in <xref linkend="EJBs_on_JBoss" />. The only new element is the <literal>service-endpoint</literal> element, which declares the service endpoint interface for the web service.
+ <emphasis role="bold">Accessing the generated WSDL</emphasis>
</para>
-<programlisting><?xml version="1.0" encoding="UTF-8"?>
-<ejb-jar xmlns="http://java.sun.com/xml/ns/"Whats_new_in_JBoss_4-J2EE_Certification_and_Standards_Compliance" version="2.1"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
- http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">
- <display-name>chapter 12 EJB JAR</display-name>
- <enterprise-beans>
- <session>
- <ejb-name>HelloBean</ejb-name>
- <emphasis role="bold"><service-endpoint>org.jboss.ws.hello.Hello</service-endpoint></emphasis>
- <ejb-class>org.jboss.ws.hello.HelloBean</ejb-class>
- <session-type>Stateless</session-type>
- <transaction-type>Container</transaction-type>
- </session>
- </enterprise-beans>
- <assembly-descriptor>
- <method-permission>
- <unchecked/>
- <method>
- <ejb-name>HelloBean</ejb-name>
- <method-name>*</method-name>
- </method>
- </method-permission>
- <container-transaction>
- <method>
- <ejb-name>HelloBean</ejb-name>
- <method-name>*</method-name>
- </method>
- <trans-attribute>Required</trans-attribute>
- </container-transaction>
- </assembly-descriptor>
-</ejb-jar>
-</programlisting>
- <para>
- The accompanying deployment descriptor files can again be generated by the <literal>wstool</literal> program. The configuration file is nearly identical, except that instaead of linking to the pseudo-servlet, we link to the <literal>HelloBean</literal> EJB.
- </para>
-<programlisting><configuration xmlns="http://www.jboss.org/jbossws-tools">
- <java-wsdl>
- <service name="HelloService"
- style="rpc"
- endpoint="org.jboss.ws.hello.Hello"/>
- <namespaces target-namespace="http://hello.ws.jboss.org/"
- type-namespace="http://hello.ws.jboss.org/types"/>
- <mapping file="jaxrpc-mapping.xml"/>
- <webservices ejb-link="HelloBean"/>
- </java-wsdl>
-</configuration>
-</programlisting>
- <para>
- The generated files are nearly identical to the ones for the previous example, except for the <literal>webservice.xml</literal> file <literal>webservices.xml</literal>. The file, shown below, contains configuration options appropriate to the EJB endpoint.
- </para>
-<programlisting><webservices version="1.1"
- xmlns="http://java.sun.com/xml/ns/"Whats_new_in_JBoss_4-J2EE_Certification_and_Standards_Compliance"
- xmlns:impl="http://hello.ws.jboss.org/"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
- http://www.ibm.com/webservices/xsd/j2ee_web_services_1_1.xsd">
- <webservice-description>
- <webservice-description-name>HelloService</webservice-description-name>
- <emphasis role="bold"><wsdl-file>META-INF/wsdl/HelloService.wsdl</wsdl-file></emphasis>
- <jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file>
- <port-component>
- <port-component-name>HelloPort</port-component-name>
- <wsdl-port>impl:HelloPort</wsdl-port>
- <service-endpoint-interface>org.jboss.ws.hello.Hello</service-endpoint-interface>
- <service-impl-bean>
- <emphasis role="bold"><ejb-link>HelloBean</ejb-link></emphasis>
- </service-impl-bean>
- </port-component>
- </webservice-description>
-</webservices>
-</programlisting>
- <para>
- The first difference is that the WSDL file should be in the <literal>META-INF/wsdl</literal> directory instead of the <literal>WEB-INF/wsdl</literal> directory. The second difference is that the <literal>service-impl-bean</literal> element contains an <literal>ejb-link</literal> that refers to the <literal>ejb-name</literal> of the session bean.
- </para>
- <para>
- To package and deploy the application, run the following command in the examples directory:
- </para>
-<programlisting>[examples]$ ant -Dchap=ws -Dex=2 run-example
-...
-run-example2:
- [echo] Waiting for 5 seconds for deploy...
- [java] Contacting webservice at http://localhost:8080/hello-ejb/HelloBean?wsdl
- [java] hello.hello(JBoss user)
- [java] output:Hello JBoss user!
-</programlisting>
- <para>
- The test program run here is the same as with the servlet example, except that we use a different URL for the WSDL. JBoss composes the WSDL using the base name of the EJB JAR file and the name of the service interface. However, as with all web services in JBoss, you can use the <literal>http://localhost:8080/jbossws/services</literal> service view shown in <xref linkend="JAX_RPC_Service_Endpoints-The_web_services_list" /> to verify the deployed URL of the WSDL.
- </para>
+ <para>A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated wsdl.</para>
+<programlisting> <![CDATA[
+ http://yourhost:8080/jbossws/services]]> </programlisting>
+ <para>Note, it is also possible to generate the abstract contract off line using jbossw 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>
</section>
-
- <section id="Web_Services-Web_Services_Clients">
- <title>Web Services Clients</title>
- <para>
- We will now turn our attention from providing web services to consuming them.
- </para>
- <section id="Web_Services_Clients-A_JAX_RPC_client">
- <title>A JAX-RPC client</title>
- <para>
- The full JAX-RPC programming model is available to J2EE applications and clients. We won't cover the full range of client programming techniques, but we swill look briefly at the client we've used so far to test the web services we've deployed. The client, shown in the following listing, illustrates the dynamic proxy invocation mechanism.
- </para>
-<programlisting>package org.jboss.ws.client;
-
-import org.jboss.ws.hello.Hello;
-
-import javax.xml.rpc.Service;
-import javax.xml.rpc.ServiceFactory;
-
-import javax.xml.namespace.QName;
-
-import java.net.URL;
-
-public class HelloClient
+ <section>
+ <title>Endpoint Provider</title>
+ <para>JAX-WS services typically implement a native Java service endpoint interface (SEI), perhaps mapped from a WSDL port type, either directly or via the use of annotations.</para>
+ <para>Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages. However, in some cases it is desirable for services to be able to operate at the XML message level. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.</para>
+ <para>A Provider based service instance’s invoke method is called for each message received for the service.</para>
+<programlisting> <![CDATA[
+ at WebServiceProvider
+ at ServiceMode(value = Service.Mode.PAYLOAD)
+public class ProviderBeanPayload implements Provider<Source>
{
- public static void main(String[] args)
- throws Exception
- {
- String urlstr = args[0];
- String argument = args[1];
-
- System.out.println("Contacting webservice at " + urlstr);
-
- URL url = new URL(urlstr);
-
- QName qname = new QName("http://hello.ws.jboss.org/",
- "HelloService");
-
- ServiceFactory factory = ServiceFactory.newInstance();
- Service service = factory.createService(url, qname);
-
- Hello hello = (Hello) service.getPort(Hello.class);
-
- System.out.println("hello.hello(" + argument + ")");
- System.out.println("output:" + hello.hello(argument));
- }
+public Source invoke(Source req)
+{
+// Access the entire request PAYLOAD and return the response PAYLOAD
+ }
+}]]> </programlisting>
+ <para>Note, Service.Mode.PAYLOAD is the default and does not have to be declared explicitly. You can also use Service.Mode.MESSAGE to access the entire SOAP message (i.e. with MESSAGE the Provider can also see SOAP Headers)</para>
+ </section>
+ <section>
+ <title>WebServiceContext</title>
+ <para>The WebServiceContext is treated as an injectable resource that can be set at the time an endpoint is initialized. The WebServiceContext object will then use thread-local information to return the correct information regardless of how many threads are concurrently being used to serve requests addressed to the same endpoint object.</para>
+<programlisting> <![CDATA[
+ at WebService
+public class EndpointJSE
+{
+ at Resource
+WebServiceContext wsCtx;
+
+ at WebMethod
+public String testGetMessageContext()
+{
+SOAPMessageContext jaxwsContext = (SOAPMessageContext)wsCtx.getMessageContext();
+return jaxwsContext != null ? "pass" : "fail";
}
-</programlisting>
- <para>
- This JAX-RPC client uses the <literal>Hello</literal> service endpoint interface and creates a dynamic proxy to speak to the service advertised by the WSDL at the URL that is passed in as a command line argument. For illustrative purposes, we'll show another variation of web services invocation that doesn't use the service endpoint interface. This is known as the Dynamic Invocation Interface (DII). Using DII, it is possible to refer to a specific port and operation by name. Think of it as reflection for web services. The client code is shown in the following listing.
- </para>
-<programlisting>package org.jboss.ws.client;
-
-import org.jboss.ws.hello.Hello;
-
-import javax.xml.rpc.Service;
-import javax.xml.rpc.ServiceFactory;
-import javax.xml.rpc.Call;
-
-import javax.xml.namespace.QName;
-
-import java.net.URL;
-
-public class HelloClientDII
+..
+ at WebMethod
+public String testGetUserPrincipal()
{
- public static void main(String[] args)
- throws Exception
- {
- String urlstr = args[0];
- String argument = args[1];
+Principal principal = wsCtx.getUserPrincipal();
+return principal.getName();
+}
+
+ at WebMethod
+public boolean testIsUserInRole(String role)
+{
+return wsCtx.isUserInRole(role);
+}
+}
+]]> </programlisting>
+ </section>
+ <section>
+ <title>Web Service Clients</title>
+ <section>
+ <title>Service</title>
+ <para><literal>Service</literal> is an abstraction that represents a WSDL service. A WSDL service is a collection of related ports, each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.</para>
+ <para>For most clients, you will start with a set of stubs generated from the WSDL. One of these will be the service, and you will create objects of that class in order to work with the service (see "static case" below).</para>
+ <section>
+ <title>Service Usage</title>
+ <para>
+ <emphasis role="bold">Static case</emphasis>
+ </para>
+ <para>Most clients will start with a WSDL file, and generate some stubs using jbossws tools like <emphasis>wsconsume</emphasis>. This usually gives a mass of files, one of which is the top of the tree. This is the service implementation class.</para>
+ <para>The generated implementation class can be recognised as it will have two public constructors, one with no arguments and one with two arguments, representing the wsdl location (a java.net.URL) and the service name (a javax.xml.namespace.QName) respectively.</para>
+ <para>Usually you will use the no-argument constructor. In this case the WSDL location and service name are those found in the WSDL. These are set implicitly from the WebServiceClient annotation that decorates the generated class.</para>
+ <para>The following code snippet shows the generated constructors from the generated class:</para>
+<programlisting> <![CDATA[
+// Generated Service Class
+
+ @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(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>
+ <emphasis role="bold">Dynamic case</emphasis>
+ </para>
+ <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>
+<programlisting> <![CDATA[
+URL wsdlLocation = new URL("http://example.org/my.wsdl");
+QName serviceName = new QName("http://example.org/sample", "MyService");
+Service service = Service.create(wsdlLocation, serviceName);]]> </programlisting>
- System.out.println("Contacting webservice at " + urlstr);
-
- URL url = new URL(urlstr);
-
- String ns = "http://hello.ws.jboss.org/";
- QName qname = new QName(ns, "HelloService");
- QName port = new QName(ns, "HelloPort");
- QName operation = new QName(ns, "hello");
-
- ServiceFactory factory = ServiceFactory.newInstance();
- Service service = factory.createService(url, qname);
- Call call = service.createCall(port, operation);
-
- System.out.println("hello.hello(" + argument + ")");
- System.out.println("output:" + call.invoke(new Object[] {argument}));
- }
-}
-</programlisting>
+ <para>This is the nastiest way to work with JBossWs. Older versions have extensive details on DII as it was then known.</para>
+ </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 Service instance provides access to a HandlerResolver via a pair of getHandlerResolver/setHandlerResolver 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 Service instance is used to create a proxy or a Dispatch 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 Service instance do not affect the handlers on previously created proxies, or Dispatch 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>
+ <section>
+ <title>Executor</title>
+ <para>Service instances can be configured with a java.util.concurrent.Executor. The executor will then be used to invoke any asynchronous callbacks requested by the application. The setExecutor and getExecutor methods of Service can be used to modify and retrieve the executor configured for a service.</para>
+ <!--<para>[TODO] <ulink url="http://jira.jboss.org/jira/browse/JBWS-1513">(JBWS-1513) Provide a sample for Service Executor</ulink></para>-->
+ </section>
+ </section>
+ <section>
+ <title>Dynamic Proxy</title>
+ <para>You can create an instance of a client proxy using one of getPort methods on the <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_User_Guide#Service">#Service</ulink>.</para>
+<programlisting> <![CDATA[
+ /**
+ * 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)
+ {
+ ...
+ }
+
+ /**
+ * The getPort method returns a proxy. The parameter
+ * <code>serviceEndpointInterface</code> specifies the service
+ * endpoint interface that is supported by the returned proxy.
+ * In the implementation of this method, the JAX-WS
+ * runtime system takes the responsibility of selecting a protocol
+ * 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 service endpoint interface (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">#Service</ulink> usually also offers typed methods to get ports. These methods also return dynamic proxies that implement the SEI.</para>
+ <programlisting> <![CDATA[
+ @WebServiceClient(name = "TestEndpointService", targetNamespace = "http://org.jboss.ws/wsref",
+ wsdlLocation = "http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl")
+
+ public class TestEndpointService extends Service
+ {
+ ...
+
+ public TestEndpointService(URL wsdlLocation, QName serviceName) {
+ super(wsdlLocation, serviceName);
+ }
+
+ @WebEndpoint(name = "TestEndpointPort")
+ public TestEndpoint getTestEndpointPort()
+ {
+ return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
+ }
+ }
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>WebServiceRef</title>
+ <para>The WebServiceRef annotation is used to declare a reference to a Web service. It follows the resource pattern exemplified by the javax.annotation.Resource annotation in JSR-250 [5]</para>
+ <para>There are two uses to the WebServiceRef annotation:</para>
+ <orderedlist>
+ <listitem>
+ <para> To define a reference whose type is a generated service class. In this case, the type and value element will both refer to the generated service class type. Moreover, if the reference type can be inferred by the field/method declaration the annotation is applied to, the type and value elements MAY have the default value (Object.class, that is). If the type cannot be inferred, then at least the type element MUST be present with a non-default value.</para>
+ </listitem>
+ <listitem>
+ <para> To define a reference whose type is a SEI. In this case, the type element MAY be present with its default value if the type of the reference can be inferred from the annotated field/method declaration, but the value element MUST always be present and refer to a generated service class type (a subtype of javax.xml.ws.Service). The wsdlLocation element, if present, overrides theWSDL location information specified in the WebService annotation of the referenced generated service class.</para>
+ </listitem>
+ </orderedlist>
+ <programlisting> <![CDATA[
+ public class EJB3Client implements EJB3Remote
+ {
+ @WebServiceRef
+ public TestEndpointService service4;
+
+ @WebServiceRef
+ public TestEndpoint port3;
+ ]]> </programlisting>
<para>
- The following two commands can be used to run the DII client against both the JSE and EJB web services we have created.
+ <emphasis role="bold">WebServiceRef Customization</emphasis>
</para>
-<programlisting>[examples]$ ant -Dchap=ws -Dex=1b run-example</programlisting>
-<programlisting>[examples]$ ant -Dchap=ws -Dex=2b run-example</programlisting>
- <para>
- Note: When accessing a remote client using the JBossWS client code, is is necessary to set the <literal>java.endorsed.dirs</literal> system property to the lib/endorsed directory under your JBoss installation. For example: <literal>-Djava.endorsed.dirs=/path/to/jboss-4.0.4/lib/endorsed</literal>.
- </para>
+ <para>In jboss-5.0.x we offer a number of overrides and extensions to the WebServiceRef annotation. These include</para>
+ <itemizedlist>
+ <listitem>
+ <para> define the port that should be used to resolve a container-managed port</para>
+ </listitem>
+ <listitem>
+ <para> define default Stub property settings for Stub objects</para>
+ </listitem>
+ <listitem>
+ <para> define the URL of a final WSDL document to be used</para>
+ </listitem>
+ </itemizedlist>
+ <para>Example:</para>
+ <programlisting> <![CDATA[
+ <service-ref>
+ <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>
+
+ <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>
+ ]]> </programlisting>
+ <para>For details please see <emphasis role="bold">service-ref_5_0.dtd</emphasis> in the jboss docs directory.</para>
</section>
-
- <section id="Web_Services_Clients-Service_references">
- <title>Service references</title>
- <para>
- The JAX-RPC examples in <xref linkend="Web_Services_Clients-A_JAX_RPC_client" /> all required manual configuration of the WSDL URL and knowledge of the XML nature of the web services in question. This can be a configuration nightmare, but if your code is a J2EE component there is another option. J2EE components can declare service references and look up preconfigured <literal>Service</literal> objects in JNDI without needing to hardcode any web service references in the code.
+ <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>Dispatch supports two usage modes, identified by the constants javax.xml.ws.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respectively:</para>
+ <para><emphasis role="bold">Message</emphasis> In this mode, client applications work directly with protocol-specific message structures. E.g., when used with a SOAP protocol binding, a client application would work directly with a SOAP message.</para>
+ <para><emphasis role="bold">Message Payload</emphasis> In this mode, client applications work with the payload of messages rather than the messages themselves. E.g., when used with a SOAP protocol binding, a client application would work with the contents of the SOAP Body rather than the SOAP message as a whole.</para>
+ <para>Dispatch is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure. Dispatch is a generic class that supports input and output of messages or message payloads of any type.</para>
+ <programlisting> <![CDATA[
+ Service service = Service.create(wsdlURL, serviceName);
+ Dispatch dispatch = service.createDispatch(portName, StreamSource.class, Mode.PAYLOAD);
+
+ String payload = "<ns1:ping xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>";
+ dispatch.invokeOneWay(new StreamSource(new StringReader(payload)));
+
+ payload = "<ns1:feedback xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/>";
+ Source retObj = (Source)dispatch.invoke(new StreamSource(new StringReader(payload)));
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>Asynchronous Invocations</title>
+ <para>The BindingProvider interface represents a component that provides a protocol binding for use by clients, it is implemented by proxies and is extended by the Dispatch 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>BindingProvider instances may provide asynchronous operation capabilities. When used, asynchronous operation invocations are decoupled from the BindingProvider 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 Response interface.</para>
+ <programlisting> <![CDATA[
+ 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);
+
+ Response response = port.echoAsync("Async");
+
+ // access future
+ String retStr = (String) response.get();
+ assertEquals("Async", retStr);
+ }
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>Oneway Invocations</title>
+ <para>@Oneway indicates that the given web method has only an input message and no output. Typically, a oneway method returns the thread of control to the calling application prior to executing the actual business method.</para>
+ <programlisting> <![CDATA[
+ @WebService (name="PingEndpoint")
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class PingEndpointImpl
+ {
+ 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>
+ <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>
+ <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 javax.xml.ws.handler.LogicalHandler.</para>
+ </section>
+ <section>
+ <title>Protocol Handler</title>
+ <para>Handlers that operate on message context properties and protocol specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol specific aspects of a message. Protocol handlers are handlers that implement any interface derived from javax.xml.ws.handler.Handler except javax.xml.ws.handler.LogicalHandler.</para>
+ </section>
+ <section>
+ <title>Service endpoint handlers</title>
+ <para>On the service endpoint, handlers are defined using the @HandlerChain annotation.</para>
+ <programlisting> <![CDATA[
+ @WebService
+ @HandlerChain(file = "jaxws-server-source-handlers.xml")
+ public class SOAPEndpointSourceImpl
+ {
+ ...
+ }
+ ]]> </programlisting>
+ <para>The location of the handler chain file supports 2 formats</para>
+ <para>1. An absolute java.net.URL in externalForm. (ex: <ulink url="http://myhandlers.foo.com/handlerfile1.xml">http://myhandlers.foo.com/handlerfile1.xml</ulink>)</para>
+ <para>2. A relative path from the source file or class file. (ex: bar/handlerfile1.xml)</para>
+ </section>
+ <section>
+ <title>Service client handlers</title>
+ <para>On the client side, handler can be configured using the @HandlerChain annotation on the SEI or dynamically using the API.</para>
+ <programlisting> <![CDATA[
+ Service service = Service.create(wsdlURL, serviceName);
+ Endpoint port = (Endpoint)service.getPort(Endpoint.class);
+
+ BindingProvider bindingProvider = (BindingProvider)port;
+ List<Handler> handlerChain = new ArrayList<Handler>();
+ handlerChain.add(new LogHandler());
+ handlerChain.add(new AuthorizationHandler());
+ handlerChain.add(new RoutingHandler());
+ bindingProvider.getBinding().setHandlerChain(handlerChain); // important!
+ ]]> </programlisting>
+ </section>
+ </section>
+ <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>
+ <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> <![CDATA[
+ CommonMessageContext msgContext = MessageContextAssociation.peekMessageContext();
+ msgContext.setProperty(<Name>, <Value>);
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>Logical Message Context</title>
+ <para><ulink url="#">#Logical Handlers</ulink> 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>
+ </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>
+ </section>
+ </section>
+ <section>
+ <title>Fault Handling</title>
+ <para>An implementation may thow a SOAPFaultException</para>
+ <programlisting> <![CDATA[
+ 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);
+ }
+ ]]> </programlisting>
+ <para>or an application specific user exception</para>
+ <programlisting> <![CDATA[
+ public void throwApplicationException() throws UserException
+ {
+ throw new UserException("validation", 123, "Some validation error");
+ }
+ ]]> </programlisting>
+ <para>
+ <note><title>Note</title>
+ <para>In case of the latter JBossWS generates the required fault wrapper beans at runtime if they are not part of the deployment</para>
+ </note>
+ </para>
+ </section>
+ </section>
+ <section>
+ <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>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>
+ <listitem>
+ <para>
+ <ulink url="http://anonsvn.jboss.org/repos/jbossws/projects/jaxbintros/">http://anonsvn.jboss.org/repos/jbossws/projects/jaxbintros/</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>Complete documentation can be found here:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JAXBIntroductions">JAXB Introductions</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </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>
- <para>
- To show how this works, let's first look at a session bean that needs to make a call to the hello web service:
+ </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> <![CDATA[
+ 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>
+ <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> <![CDATA[
+ [...]
+ 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>
-<programlisting>package org.jboss.ws.example;
-
-import javax.ejb.*;
-import javax.naming.*;
-import java.rmi.RemoteException;
-
-import javax.xml.rpc.Service;
-import javax.xml.rpc.ServiceException;
-
-import org.jboss.ws.hello.Hello;
-
-public class ExampleBean
- implements SessionBean
-{
- public String doWork()
- {
- try {
- Context ctx = new InitialContext();
-
- Service service = (Service) ctx.lookup("java:comp/env/services/hello");
- Hello hello = (Hello) service.getPort(Hello.class);
-
- return hello.hello("example bean");
- } catch (NamingException e) {
- throw new EJBException(e);
-
- } catch (ServiceException e) {
- throw new EJBException(e);
-
- } catch (RemoteException e) {
- throw new EJBException(e);
- }
- }
-
- public void ejbCreate() {};
- public void ejbRemove() {};
-
- public void ejbActivate() {}
- public void ejbPassivate() {}
-
- public void setSessionContext(SessionContext ctx) {}
-}
-</programlisting>
+ </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> <![CDATA[
+ /**
+ * Payload bean that will use SwaRef encoding
+ */
+ @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> <![CDATA[
+ @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> <![CDATA[
+ <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> <![CDATA[
+ <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>
+ <itemizedlist>
+ <listitem>
+ <para> Exposing an already existing EJB3 bean as a Web Service</para>
+ </listitem>
+ <listitem>
+ <para> Providing a new service, and you want the contract to be generated for you</para>
+ </listitem>
+ </itemizedlist>
+ <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>
+ </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>
+ </listitem>
+ <listitem>
+ <para> Creating a service that adheres to the XML Schema and WSDL you developed by hand up front</para>
+ </listitem>
+ </itemizedlist>
+ <para>The following JAX-WS command line tools are included in JBossWS:</para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="50*"/>
+ <colspec colname="c2" colwidth="50*"/>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <emphasis role="bold">Command</emphasis>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <emphasis role="bold">Description</emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para> Generates JAX-WS portable artifacts, and provides the abstract contract. Used for bottom-up development.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsconsume">wsconsume</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para> Consumes the abstract contract (WSDL and Schema files), and produces artifacts for both a server and client. Used for top-down and client development</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsrunclient">wsrunclient</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para> Executes a Java client (has a main method) using the JBossWS classpath.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <section>
+ <title>Bottom-Up (Using wsprovide)</title>
+ <para>The bottom-up strategy involves developing the Java code for your service, and then annotating it using JAX-WS annotations. These annotations can be used to customize the contract that is generated for your service. For example, you can change the operation name to map to anything you like. However, all of the annotations have sensible defaults, so only the @WebService annotation is required.</para>
+ <para>This can be as simple as creating a single class:</para>
+ <programlisting> <![CDATA[
+ package echo;
+
+ @javax.jws.WebService
+ public class Echo
+ {
+ 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 unfortunately 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>
+ <programlisting> <![CDATA[
+ $ javac -d . -classpath jboss-jaxws.jar Echo.java
+ $ wsprovide -w echo.Echo
+ Generating WSDL:
+ EchoService.wsdl
+ Writing Classes:
+ echo/jaxws/Echo.class
+ echo/jaxws/EchoResponse.class
+ ]]> </programlisting>
+ <para>Inspecting the WSDL reveals a service called EchoService:</para>
+ <programlisting> <![CDATA[
+ <service name='EchoService'>
+ <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> <![CDATA[
+ <portType name='Echo'>
+ <operation name='echo' parameterOrder='echo'>
+ <input message='tns:Echo_echo'/>
+ <output message='tns:Echo_echoResponse'/>
+ </operation>
+ </portType>
+ ]]> </programlisting>
<para>
- <literal>ExampleBean</literal> invokes the hello web service in its <literal>doWork</literal> method. We've used the dynamic proxy invocation method here, but any of the JAX-RPC supported invocation methods would be fine. The interesting point here is that the bean has obtained the <literal>Service</literal> reference from a JNDI lookup in its ENC.
+ <note><title>Note</title>
+ <para>Remember that <emphasis role="bold">when deploying on JBossWS you do not need to run this tool.</emphasis> You only need it for generating portable artifacts and/or the abstract contract for your service.</para>
+ </note>
</para>
+
+ <para>Let's create a POJO endpoint for deployment on JBoss AS. A simple web.xml needs to be created:</para>
+ <programlisting> <![CDATA[
+ <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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-mapping>
+ <servlet-name>Echo</servlet-name>
+ <url-pattern>/Echo</url-pattern>
+ </servlet-mapping>
+ </web-app>
+ ]]> </programlisting>
+ <para>The web.xml and the single class can now be used to create a war:</para>
+ <programlisting> <![CDATA[
+ $ mkdir -p WEB-INF/classes
+ $ cp -rp echo WEB-INF/classes/
+ $ cp web.xml WEB-INF
+ $ jar cvf echo.war WEB-INF
+ added manifest
+ adding: WEB-INF/(in = 0) (out= 0)(stored 0%)
+ adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%)
+ adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%)
+ adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%)
+ adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)
+ ]]> </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
+ ]]> </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>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>
- Web service references are declared using a <literal>service-ref</literal> element in inside an <literal>ejb-jar.xml</literal> file.
+ <emphasis role="bold">Note</emphasis>
</para>
- <figure id="Service_references-The_service_ref_content_model">
- <title>The service-ref content model</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ejb-jar_service-ref.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>wsconsume seems to have a problem with symlinks on unix systems</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>
+ <programlisting> <![CDATA[
+
+ $ wsconsume -k EchoService.wsdl
+ echo/Echo.java
+ echo/EchoResponse.java
+ echo/EchoService.java
+ echo/Echo_Type.java
+ echo/ObjectFactory.java
+ echo/package-info.java
+ echo/Echo.java
+ echo/EchoResponse.java
+ echo/EchoService.java
+ echo/Echo_Type.java
+ echo/ObjectFactory.java
+ echo/package-info.java
+ ]]> </programlisting>
+ <para>The following table shows the purpose of each generated file:</para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="50*"/>
+ <colspec colname="c2" colwidth="50*"/>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <emphasis role="bold">File</emphasis>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <emphasis role="bold">Purpose</emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> Echo.java</para>
+ </entry>
+ <entry>
+ <para> Service Endpoint Interface</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> Echo_Type.java</para>
+ </entry>
+ <entry>
+ <para> Wrapper bean for request message</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> EchoResponse.java</para>
+ </entry>
+ <entry>
+ <para> Wrapper bean for response message</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> ObjectFactory.java</para>
+ </entry>
+ <entry>
+ <para> JAXB XML Registry</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> package-info.java</para>
+ </entry>
+ <entry>
+ <para> Holder for JAXB package annotations</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> EchoService.java</para>
+ </entry>
+ <entry>
+ <para> Used only by JAX-WS clients</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <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> <![CDATA[
+ @WebService(name = "Echo", targetNamespace = "http://echo/")
+ 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> <![CDATA[
+ package echo;
+
+ @javax.jws.WebService(endpointInterface="echo.Echo")
+ public class EchoImpl implements Echo
+ {
+ public String echo(String arg0)
+ {
+ return arg0;
+ }
+ }
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>Client Side</title>
+ <para>Before going to detail on the client-side it is important to understand the decoupling concept that is central to Web Services. Web Services are not the best fit for internal RPC, even though they can be used in this way. There are much better technologies for this (CORBA, and RMI for example). Web Services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a Web Service interaction will be at any particular location, running on any particular OS, or written in any particular programming language. So because of this, it is important to clearly separate client and server implementations. The only thing they should have in common is the abstract contract definition. If, for whatever reason, your software does not adhere to this principal, then you should not be using Web Services. For the above reasons, the <emphasis role="bold">
+ <emphasis>recommended methodology for developing a client is</emphasis>
+ </emphasis>
+ to follow <emphasis role="bold">
+ <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>Offline version:</para>
+ <programlisting> <![CDATA[
+ <service name='EchoService'>
+ <port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port>
+ </service>
+ ]]> </programlisting>
+ <para>Online version:</para>
+ <programlisting> <![CDATA[
+ <service name="EchoService">
+ <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>
+ <programlisting> <![CDATA[
+ $ wsconsume -k http://localhost:8080/echo/Echo?wsdl
+ echo/Echo.java
+ echo/EchoResponse.java
+ echo/EchoService.java
+ echo/Echo_Type.java
+ echo/ObjectFactory.java
+ echo/package-info.java
+ echo/Echo.java
+ echo/EchoResponse.java
+ echo/EchoService.java
+ echo/Echo_Type.java
+ echo/ObjectFactory.java
+ echo/package-info.java
+ ]]> </programlisting>
+ <para> The one class that was not examined in the top-down section, was EchoService.java. Notice how it stores the location the WSDL was obtained from.</para>
+ <programlisting> <![CDATA[
+ @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;
+
+ 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() {
+ super(ECHOSERVICE_WSDL_LOCATION, new QName("http://echo/", "EchoService"));
+ }
+
+ @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, javax.xml.ws.Service. While you can use Service directly, this is far simpler since it provides the configuration info for you. The only method we really care about is the getEchoPort() method, which returns an instance of our Service Endpoint Interface. Any WS operation can then be called by just invoking a method on the returned interface.</para>
+
<para>
- The following elements are supported by the <literal>service-ref</literal>:
+ <note><title>Note</title>
+ <para>It's not recommended to refer to a remote WSDL URL in a production application. This causes network I/O every time you instantiate the Service Object. Instead, use the tool on a saved local copy, or use the URL version of the constructor to provide a new WSDL location.</para>
+ </note>
</para>
+
+ <para>All that is left to do, is write and compile the client:</para>
+ <programlisting> <![CDATA[
+ import echo.*;
+
+ public class EchoClient
+ {
+ 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]));
+ }
+ }
+ ]]> </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>
+ <programlisting> <![CDATA[
+ $ wsrunclient EchoClient 'Hello World!'
+ Server said: Hello World!
+ ]]> </programlisting>
+ <para>It is easy to change the endpoint address of your operation at runtime, setting the ENDPOINT_ADDRESS_PROPERTY as shown below:</para>
+ <programlisting> <![CDATA[
+ ...
+ EchoService service = new EchoService();
+ Echo echo = service.getEchoPort();
+
+ /* Set NEW Endpoint Location */
+ String endpointURL = "http://NEW_ENDPOINT_URL";
+ BindingProvider bp = (BindingProvider)echo;
+ bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL);
+
+ System.out.println("Server said: " + echo.echo(args[0]));
+ ...
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>Command-line & Ant Task Reference</title>
<itemizedlist>
<listitem>
<para>
- <emphasis role="bold">service-ref-name</emphasis>: This is the JNDI name that the service object will be bound under in the bean's ENC. It is relative to <literal>java:comp/env/</literal>.
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsconsume">wsconsume reference page</ulink>
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">service-interface</emphasis>: This is the name of JAX-RPC service interface the client will use. Normally this is <literal>javax.xml.rpc.Service</literal>, but it's possible to provide your own service class.
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsprovide">wsprovide reference page</ulink>
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">wsdl-file</emphasis>: This is the location of the WSDL file. The WSDL file should be under <literal>META-INF/wsdl</literal>.
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=Wsrunclient">wsrunclient reference page</ulink>
</para>
</listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>JAX-WS binding customization</title>
+ <para>An introduction to binding customizations:</para>
+ <itemizedlist>
<listitem>
<para>
- <emphasis role="bold">jaxrpc-mapping-file</emphasis>: This is the location of the JAX-RPC mapping file. It must be under the <literal>META-INF</literal> directory.
+ <ulink url="http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html">http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html</ulink>
</para>
</listitem>
+ </itemizedlist>
+ <para>The schema for the binding customization files can be found here:</para>
+ <itemizedlist>
<listitem>
<para>
- <emphasis role="bold">service-qname</emphasis>: This element specifies the name of the service in the web services file. It is only mandatory if the WSDL file defines multiple services. The value must by a QName, which means it needs to be a namespace qualified value such as <literal>ns:ServiceName</literal> where <literal>ns</literal> is an XML namespace valid at the scope of the <literal>service-qname</literal> element.
+ <ulink url="https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customization.xsd?rev=1.2&view=log">binding customization</ulink>
</para>
</listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section>
+ <title>Web Service Extensions</title>
+ <section>
+ <title>WS-Addressing</title>
+ <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>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://www.w3.org/TR/ws-addr-core">Web Services Addressing 1.0 - Core</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.w3.org/TR/ws-addr-soap">Web Services Addressing 1.0 - SOAP Binding</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Addressing Endpoint</title>
+ <para>The following endpoint implementation has a set of operation for a typical stateful shopping chart application.</para>
+ <programlisting> <![CDATA[
+ @WebService(name = "StatefulEndpoint", targetNamespace = "http://org.jboss.ws/samples/wsaddressing", serviceName = "TestService")
+ @EndpointConfig(configName = "Standard WSAddressing Endpoint")
+ @HandlerChain(file = "WEB-INF/jaxws-handlers.xml")
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class StatefulEndpointImpl implements StatefulEndpoint, ServiceLifecycle
+ {
+ @WebMethod
+ public void addItem(String item)
+ { ... }
+
+ @WebMethod
+ public void checkout()
+ { ... }
+
+ @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>The endpoint handler chain</para>
+ <programlisting> <![CDATA[
+ <handler-chains xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee javaee_web_services_1_2.xsd">
+
+ <handler-chain>
+ <protocol-bindings>##SOAP11_HTTP</protocol-bindings>
+ <handler>
+ <handler-name>Application Server Handler</handler-name>
+ <handler-class>org.jboss.test.ws.jaxws.samples.wsaddressing.ServerHandler</handler-class>
+ </handler>
+ </handler-chain>
+
+ </handler-chains>
+ ]]> </programlisting>
+ <para>defines an application specific hander that assignes/processes stateful client ids.</para>
+ </section>
+ <section>
+ <title>Addressing Client</title>
+ <para>On the client side there are simmilar handlers that does the reverse. It uses the JSR-261 API to add WS-Addressing header elements including the clientid association.</para>
+ <para> The client sets a custom handler chain in the binding</para>
+ <programlisting> <![CDATA[
+ Service service = Service.create(wsdlURL, serviceName);
+ port1 = (StatefulEndpoint)service.getPort(StatefulEndpoint.class);
+ BindingProvider bindingProvider = (BindingProvider)port1;
+
+ List<Handler> customHandlerChain = new ArrayList<Handler>();
+ customHandlerChain.add(new ClientHandler());
+ customHandlerChain.add(new WSAddressingClientHandler());
+ bindingProvider.getBinding().setHandlerChain(customHandlerChain);
+ ]]> </programlisting>
+ <para>The WSAddressingClientHandler is provided by JBossWS and reads/writes the addressing properties and puts then into the message context.</para>
+ <para>
+ <emphasis role="bold">A client connecting to the stateful endpoint</emphasis>
+ </para>
+ <programlisting> <![CDATA[
+ public class AddressingStatefulTestCase extends JBossWSTest
+ {
+ public void testAddItem() throws Exception
+ {
+ port1.addItem("Ice Cream");
+ port1.addItem("Ferrari");
+
+ port2.addItem("Mars Bar");
+ port2.addItem("Porsche");
+ }
+
+ public void testGetItems() throws Exception
+ {
+ String items1 = port1.getItems();
+ assertEquals("[Ice Cream, Ferrari]", items1);
+
+ String items2 = port2.getItems();
+ assertEquals("[Mars Bar, Porsche]", items2);
+ }
+ }
+ ]]> </programlisting>
+ <para>
+ <emphasis role="bold">SOAP message exchange</emphasis>
+ </para>
+ <para>Below you see the SOAP messages that are beeing exchanged.</para>
+ <programlisting> <![CDATA[
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'>
+ <wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action>
+ <wsa:ReferenceParameters>
+ <ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid>
+ </wsa:ReferenceParameters>
+ </env:Header>
+ <env:Body>
+ <ns1:addItem xmlns:ns1='http://org.jboss.ws/samples/wsaddr'>
+ <String_1>Ice Cream</String_1>
+ </ns1:addItem>
+ </env:Body>
+ </env:Envelope>
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'>
+ <wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action>
+ <ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid>
+ </env:Header>
+ <env:Body>
+ <ns1:addItemResponse xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/>
+ </env:Body>
+ </env:Envelope>
+
+ ...
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'>
+ <wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action>
+ <wsa:ReferenceParameters>
+ <ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid>
+ </wsa:ReferenceParameters>
+ </env:Header>
+ <env:Body>
+ <ns1:getItems xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/>
+ </env:Body>
+ </env:Envelope>
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'>
+ <wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action>
+ <ns1:clientid xmlns:ns1='http://somens'>clientid-1</ns1:clientid>
+ </env:Header>
+ <env:Body>
+ <ns1:getItemsResponse xmlns:ns1='http://org.jboss.ws/samples/wsaddr'>
+ <result>[Ice Cream, Ferrari]</result>
+ </ns1:getItemsResponse>
+ </env:Body>
+ </env:Envelope>
+ ]]> </programlisting>
+ </section>
+ </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>
+ </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><title>Note</title>
+ <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, i.e. 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's left todo is 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 (1) and the fact that is actually contains an event source port (2)</para>
+ </listitem>
+ <listitem>
+ <para> Use the JBossWS SEI (3) and endpoint (4) 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> <![CDATA[
+ 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
+ */
+ @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")
+ @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> <![CDATA[
+ <?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 "wse:EventSource='true'" 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> <![CDATA[
+ java:/EventDispatcher
+ ]]> </programlisting>
+ <para>The event dispatcher interface:</para>
+ <programlisting> <![CDATA[
+ public interface EventDispatcher
+ {
+ void dispatch(URI eventSourceNS, Element payload);
+ }
+ ]]> </programlisting>
+ <para>
+ <emphasis role="bold">Example notification</emphasis>
+ </para>
+ <programlisting> <![CDATA[
+ (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>
+ <para>
+ <emphasis role="bold">Specifications</emphasis>
+ </para>
+ <para>WS-Security is defined by the combination of the following specifications:</para>
+ <itemizedlist>
<listitem>
<para>
- <emphasis role="bold">port-component-ref</emphasis>: This element provides the mapping between a service endpoint interface and a port in a web service.
+ <ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf">SOAP Message Security 1.0</ulink>
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">handler</emphasis>: This allows the specification of handlers, which act like filters or interceptors on the current request or response.
+ <ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf">Username Token Profile 1.0</ulink>
</para>
</listitem>
- </itemizedlist>
- <para>
- The following <literal>service-ref</literal> declares a reference to the hello web service for the <literal>Example</literal> session bean.
- </para>
-<programlisting><session>
- <ejb-name>Example</ejb-name>
- <home>org.jboss.ws.example.ExampleHome</home>
- <remote>org.jboss.ws.example.Example</remote>
- <ejb-class>org.jboss.ws.example.ExampleBean</ejb-class>
- <session-type>Stateless</session-type>
- <transaction-type>Container</transaction-type>
- <service-ref>
- <service-ref-name>services/hello</service-ref-name>
- <service-interface>javax.xml.rpc.Service</service-interface>
- <wsdl-file>META-INF/wsdl/hello.wsdl</wsdl-file>
- <jaxrpc-mapping-file>META-INF/mapping.xml</jaxrpc-mapping-file>
- <service-qname xmlns:hello="http://hello.ws.jboss.org">
- hello:HelloService
- </service-qname>
- </service-ref>
-</session>
-</programlisting>
- <para>
- This instructs the EJB deployer to make a <literal>Service</literal> object available for the bean in JNDI under the name <literal>java:comp/env/services/hello</literal> that talks to our hello web service. The session bean can then invoke normal web services operations on the service.
- </para>
- <para>
- Since most of the web services configuration options are completely standard, there's little need to go into great depths here. However, JBoss does provide several additional web services configuration options through the <literal>service-ref</literal> element in the <literal>jboss.xml</literal> deployment descriptor. The content model for the service-ref element is shown in <xref linkend="Service_references-The_jboss.xml_service_ref_content_model" />.
- </para>
- <figure id="Service_references-The_jboss.xml_service_ref_content_model">
- <title>The jboss.xml service-ref content model</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/jboss_service-ref.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- The configurable elements are:
- </para>
- <itemizedlist>
<listitem>
<para>
- <emphasis role="bold">service-ref-name</emphasis>: This element should match the <literal>service-ref-name</literal> in the <literal>ejb-jar.xml</literal> file that is being configured.
+ <ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf">X.509 Token Profile 1.0</ulink>
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">port-component-ref</emphasis>: The <literal>port-component-ref</literal> element provides additional information for a specific port. This includes properties that should be associated with the JAX-RPC stub for the port.
+ <ulink url="http://www.w3.org/TR/xmlenc-core">W3C XML Encryption</ulink>
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">wsdl-override</emphasis>: This provides an alternate location for the WSDL file. The value can be any valid URL. This can be used in co-ordination with the <literal>wsdl-publish-location</literal> to get the final WSDL file for a locally published web service. It could also be the URL of a remotely published WSDL that you don't want duplicated in the deployment file.
+ <ulink url="http://www.w3.org/TR/xmldsig-core">W3C XML Signature</ulink>
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">call-property</emphasis>: This sets properties on the JAX-RPC stub.
+ <ulink url="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html">Basic Security Profile 1.0 (Still in Draft)</ulink>
</para>
</listitem>
</itemizedlist>
- <para>
- Since the WSDL file generated by wscompile doesn't contain the SOAP address of our web service, we'll use the WSDL override feature to dynamically download the correct WSDL file from the server. While this might not be the best technique to use in a production application, it does illustrate the WSDL override functionality very well. The following <literal>jboss.xml</literal> file links the published URL for the <literal>hello-servlet</literal> version of the hello web service..
- </para>
-<programlisting><!DOCTYPE jboss PUBLIC
- "-//JBoss//DTD JBOSS 4.0//EN"
- "http://www.jboss.org/j2ee/dtd/jboss_4_0.dtd">
-<jboss>
- <enterprise-beans>
- <session>
- <ejb-name>Example</ejb-name>
- <service-ref>
- <service-ref-name>services/hello</service-ref-name>
- <wsdl-override><emphasis role="bold">http://localhost:8080/hello-servlet/Hello?wsdl</emphasis></wsdl-override>
- </service-ref>
- </session>
- </enterprise-beans>
-</jboss>
-</programlisting>
- <para>
- This example can be run as shown below:
- </para>
-<programlisting>[examples]$ ant -Dchap=ws -Dex=3 run-example
-...
-run-example3:
- [echo] Waiting for 5 seconds for deploy...
- [copy] Copying 1 file to /tmp/jboss-4.0.4/server/production/deploy
- [echo] Waiting for 5 seconds for deploy...
- [java] output:Hello example bean!
-</programlisting>
- <para>
- The <literal>service-ref</literal> element is not limited to the <literal>ejb-jar.xml</literal> file. It's available to any J2EE component. A service reference can be placed in the <literal>web.xml</literal> file for use by web tier components or in the <literal>application-client.xml</literal> file for use by J2EE client applications.
- </para>
+ <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>
+ <note><title>Note</title>
+ <para>You need to setup both the endpoint configuration and the WSSE declarations. That's two separate steps.</para>
+ </note>
+ </para>
+ </section>
+ <section>
+ <title>Server side WSSE declaration (jboss-wsse-server.xml)</title>
+ <para>In this example we configure both the client and the server to sign the message body. Both also require this from each other. So, if you remove either the client or the server security deployment descriptor, you will notice that the other party will throw a fault explaining that the message did not conform to the proper security requirements.</para>
+ <programlisting> <![CDATA[
+ <jboss-ws-security xmlns="http://www.jboss.com/ws-security/config"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.jboss.com/ws-security/config
+ http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
+ (1) <key-store-file>WEB-INF/wsse.keystore</key-store-file>
+ (2) <key-store-password>jbossws</key-store-password>
+ (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>
+ </jboss-ws-security>
+ ]]> </programlisting>
+ <orderedlist>
+ <listitem>
+ <para> This specifies that the key store we wish to use is WEB-INF/wsse.keystore, which is located in our war file.</para>
+ </listitem>
+ <listitem>
+ <para> This specifies that the store password is "jbossws". Password can be encypted using the {EXT} and {CLASS} commands. Please see samples for their usage.</para>
+ </listitem>
+ <listitem>
+ <para> This specifies that the trust store we wish to use is WEB-INF/wsse.truststore, which is located in our war file.</para>
+ </listitem>
+ <listitem>
+ <para> This specifies that the trust store password is also "jbossws". Password can be encrypted using the {EXT} and {CLASS} commands. Please see samples for their usage.</para>
+ </listitem>
+ <listitem>
+ <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/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>
+ </listitem>
+ <listitem>
+ <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>
+ <programlisting> <![CDATA[
+ @WebService
+ @EndpointConfig(configName = "Standard WSSecurity Endpoint")
+ public class HelloJavaBean
+ {
+ ...
+ }
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>Client side WSSE declaration (jboss-wsse-client.xml)</title>
+ <programlisting> <![CDATA[
+ <jboss-ws-security xmlns="http://www.jboss.com/ws-security/config"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+ </jboss-ws-security>
+ ]]> </programlisting>
+ <orderedlist>
+ <listitem>
+ <para> Here we start our root config block. The root config block is the default configuration for all web service clients (Call, Proxy objects).</para>
+ </listitem>
+ <listitem>
+ <para> This means that the client must sign the message body of all requests it sends. Type means that we are to use a X.509v3 certificate (a standard certificate). The alias option says that the certificate/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 client receives a response.</para>
+ </listitem>
+ <listitem>
+ <para> This means that all web service clients must receive signed response messages.</para>
+ </listitem>
+ </orderedlist>
+ <section>
+ <title>Client side key store configuration</title>
+ <para>We did not specify a key store or trust store, because client apps instead use the wsse System properties instead. If this was a web or ejb client (meaning a webservice client in a war or ejb jar file), then we would have specified them in the client descriptor.</para>
+ <para>Here is an excerpt from the JBossWS samples:</para>
+ <programlisting> <![CDATA[
+ <sysproperty key="org.jboss.ws.wsse.keyStore"
+ value="${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.keystore"/>
+ <sysproperty key="org.jboss.ws.wsse.trustStore"
+ value="${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.truststore"/>
+ <sysproperty key="org.jboss.ws.wsse.keyStorePassword" value="jbossws"/>
+ <sysproperty key="org.jboss.ws.wsse.trustStorePassword" value="jbossws"/>
+ <sysproperty key="org.jboss.ws.wsse.keyStoreType" value="jks"/>
+ <sysproperty key="org.jboss.ws.wsse.trustStoreType" value="jks"/>
+ ]]> </programlisting>
+ <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>Incomming SOAPMessage</para>
+ <programlisting> <![CDATA[
+ <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+ <env:Header>
+ <wsse:Security env:mustUnderstand="1" ...>
+ <wsu:Timestamp wsu:Id="timestamp">...</wsu:Timestamp>
+ <wsse:BinarySecurityToken ...>
+ ...
+ </wsse:BinarySecurityToken>
+ <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
+ ...
+ </ds:Signature>
+ </wsse:Security>
+ </env:Header>
+ <env:Body wsu:Id="element-1-1140197309843-12388840" ...>
+ <ns1:echoUserType xmlns:ns1="http://org.jboss.ws/samples/wssecurity">
+ <UserType_1 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <msg>Kermit</msg>
+ </UserType_1>
+ </ns1:echoUserType>
+ </env:Body>
+ </env:Envelope>
+ ]]> </programlisting>
+ </section>
+ </section>
+ <section>
+ <title>Installing the BouncyCastle JCE provider (JDK 1.4)</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 java.security properties file (found in $JAVA_HOME/jre/lib/security/java.security, where $JAVA_HOME is the location of your JDK/JRE distribution). You'll find detailed instructions in the file but basically it comes down to adding a line:</para>
+ <programlisting> <![CDATA[
+ security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider
+ ]]> </programlisting>
+ <para>Where <n> is the preference you want the provider at.</para>
+ <para>
+ <emphasis role="bold">Note</emphasis>
+ </para>
+ <para>Issues may arise if the Sun provided providers are not first.</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 $JAVA_HOME/jre/lib/ext. 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>
+ </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>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>
+ <para>Configuration of the jUDDI registry happens via an MBean Service that is deployed in the juddi-service.sar archive in the "all" configuration. The configuration of this service can be done in the jboss-service.xml of the META-INF directory in the juddi-service.sar</para>
+ <para>Let us look at the individual configuration items that can be changed.</para>
+ <para>DataSources configuration</para>
+ <programlisting> <![CDATA[
+ <!-- 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> <![CDATA[
+ <!-- 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>
+ ]]> </programlisting>
+ <para>JAXR Connection Factory to be bound in JNDI. (Should it be bound? and under what name?)</para>
+ <programlisting> <![CDATA[
+ <!-- Should I bind a Context to which JaxrConnectionFactory bound-->
+ <attribute name="ShouldBindJaxr">true</attribute>
+
+ <!-- Context to which JaxrConnectionFactory to bind to. If you have remote clients, please bind it to the global namespace(default behavior).
+ To just cater to clients running on the same VM as JBoss, change to java:/JAXR -->
+ <attribute name="BindJaxr">JAXR</attribute>
+ ]]> </programlisting>
+ <para>Other common configuration:</para>
+ <para>Add authorized users to access the jUDDI registry. (Add a sql insert statement in a single line)</para>
+ <programlisting> <![CDATA[
+ Look at the script META-INF/ddl/juddi_data.ddl for more details. Example for a user 'jboss'
+
+ INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,
+ EMAIL_ADDRESS,IS_ENABLED,IS_ADMIN)
+ VALUES ('jboss','JBoss User','jboss at xxx','true','true');
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>JBoss JAXR Configuration</title>
+ <para>In this section, we will discuss the configuration needed to run the JAXR API. The JAXR configuration relies on System properties passed to the JVM. The System properties that are needed are:</para>
+ <programlisting> <![CDATA[
+ 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
+ ]]> </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>
+ <itemizedlist>
+ <listitem>
+ <para> When the client code is running inside JBoss (maybe a servlet or an EJB). Then you will need to pass the System properties in the run.sh/run.bat scripts to the java process via the "-D" option.</para>
+ </listitem>
+ <listitem>
+ <para> When the client code is running in an external JVM. Then you can pass the properties either as "-D" options to the java process or explicitly set them in the client code(not recommended).</para>
+ </listitem>
+ </itemizedlist>
+ <programlisting> <![CDATA[
+ System.setProperty(propertyname, propertyvalue);
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>JAXR Sample Code</title>
+ <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>
+ </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 BusinessLifeCycleManager interface, which is exposed by the Registry Service, implements the life cycle management functionality of the Registry as part of a business level API. Note that 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 BusinessQueryManager 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>
+ <para>Getting a JAXR Connection to the registry.</para>
+ <programlisting> <![CDATA[
+ String queryurl = System.getProperty("jaxr.query.url", "http://localhost:8080/juddi/inquiry");
+ String puburl = System.getProperty("jaxr.publish.url", "http://localhost:8080/juddi/publish");
+
+ Properties props = new Properties();
+ 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);
+
+ // Create the connection, passing it the configuration properties
+ factory = ConnectionFactory.newInstance();
+ factory.setProperties(props);
+ connection = factory.createConnection();
+ ]]> </programlisting>
+ <para>Authentication with the registry.</para>
+ <programlisting> <![CDATA[
+ /**
+ * 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);
+
+ connection.setCredentials(creds);
+ }
+ ]]> </programlisting>
+ <para>Save a Business</para>
+ <programlisting> <![CDATA[
+ /**
+ * 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"));
+
+ //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);
+
+ 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;
+ }
+ ]]> </programlisting>
+ <para>Query a Business</para>
+ <programlisting> <![CDATA[
+ /**
+ * 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();
+
+ // 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);
+
+ // 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();
+ }
+ }
+ ]]> </programlisting>
+ <para>For more examples of code using the JAXR API, please refer to the resources in the Resources Section.</para>
+ </section>
+ <section>
+ <title>Troubleshooting</title>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">I cannot connect to the registry from JAXR.</emphasis> Please check the inquiry and publish url passed to the JAXR ConnectionFactory.</para>
+ </listitem>
+ <listitem>
+ <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>
+ </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>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Resources</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://java.sun.com/webservices/jaxr/learning/tutorial/index.html">JAXR Tutorial and Code Camps</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/">J2EE 1.4 Tutorial</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.amazon.com/exec/obidos/ASIN/0321146182">J2EE Web Services by Richard Monson-Haefel</ulink>
+ </para>
+ </listitem>
+ </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 implementation 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>Please note that 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 wssecurity.</para>
+ <programlisting> <![CDATA[
+ @WebService(name = "Hello",
+ targetNamespace = "http://org.jboss.ws/samples/wssecuritypolicy",
+ wsdlLocation="WEB-INF/wsdl/HelloService.wsdl")
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class HelloJavaBean
+ {
+ private Logger log = Logger.getLogger(HelloJavaBean.class);
+
+ @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> <![CDATA[
+ /**
+
+ @Target(ElementType.TYPE)
+ @Retention(RetentionPolicy.RUNTIME)
+ public @interface PolicyAttachment {
+ Policy[] value();
+ }
+
+ @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> <![CDATA[
+ @WebService(name = "Hello", targetNamespace = "http://org.jboss.ws/samples/wssecurityAnnotatedpolicy")
+ @PolicyAttachment({@Policy( policyFileLocation="WEB-INF/Policy.xml", scope = PolicyScopeLevel.WSDL_PORT ) })
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class HelloJavaBean
+ {
+ private Logger log = Logger.getLogger(HelloJavaBean.class);
+
+ @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>
+ <section>
+ <title>EndpointConfig</title>
+ <programlisting> <![CDATA[
+ /**
+ * 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
+ */
+ @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 "";
+ }
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>WebContext</title>
+ <programlisting> <![CDATA[
+ /**
+ * 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 {};
+
+ /**
+ * 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 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;
+ }
+ ]]> </programlisting>
+ </section>
+ <section>
+ <title>SecurityDomain</title>
+ <programlisting> <![CDATA[
+ /**
+ * Annotation for specifying the JBoss security domain for an EJB
+ *
+ * @author <a href="mailto:bill at jboss.org">Bill Burke</a>
+ **/
+ @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 name for the unauthenticated pricipal
+ */
+ String unauthenticatedPrincipal() default "";
+ }
+ ]]> </programlisting>
+ </section>
+ </section>
+ </section>
+ <section>
+ <title>Appendix</title>
+ <para>
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Endpoint_Configuration">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>
+ </para>
+ <para>
+ <ulink url="http://jbws.dyndns.org/mediawiki/index.php?title=JAX-WS_Annotations">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>
+
+ <title>References</title>
+ <orderedlist>
+ <listitem>
+ <para><ulink url="http://www.jcp.org/en/jsr/detail?id=224">JSR-224 - Java API for XML-Based Web Services (JAX-WS) 2.0</ulink></para>
+ </listitem>
+ <listitem>
+ <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>
+ <para><ulink url="http://jcp.org/en/jsr/detail?id=181">JSR 181 - Web Services Metadata for the Java Platform</ulink></para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <!-- </section>-->
+
+
- </section>
-
</chapter>
More information about the jboss-cvs-commits
mailing list