Skip to content

Commit d7b035f

Browse files
poutsmapoutsma
committed
SWS-299
1 parent e36a840 commit d7b035f

File tree

2 files changed

+162
-2
lines changed

2 files changed

+162
-2
lines changed

‎src/docbkx/client.xml‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
<classname>Result</classname>. Additionally, it can marshal objects to XML before sending
3333
them across a transport, and unmarshal any response XML into an object again.
3434
</para>
35-
<section>
35+
<section id="client-transports">
3636
<title>URIs and Transports</title>
3737
<para>
3838
The <classname>WebServiceTemplate</classname> class uses an URI as the message destination.
@@ -313,6 +313,34 @@ public void marshalWithSoapActionHeader(MyObject o) {
313313
}
314314
});
315315
}]]></programlisting>
316+
<note>
317+
<para>
318+
Note that you can also use the
319+
<classname>org.springframework.ws.soap.client.core.SoapActionCallback</classname> to set the SOAP
320+
Action header.
321+
</para>
322+
</note>
323+
<section>
324+
<title>WS-Addressing</title>
325+
<para>
326+
In addition to the <link linkend="server-ws-addressing">server-side WS-Addressing</link> support,
327+
Spring Web Services also has support for this specification on the client-side.
328+
</para>
329+
<para>
330+
For setting WS-Addressing headers on the client, you can use the
331+
<classname>org.springframework.ws.soap.addressing.client.ActionCallback</classname>. This callback
332+
takes the desired Action header as a parameter. It also has constructors for specifying the
333+
WS-Addressing version, and a <literal>To</literal> header. If not specified, the
334+
<literal>To</literal> header will default to the URL of the connection being made.
335+
</para>
336+
<para>
337+
Here is an example of setting the <literal>Action</literal> header to
338+
<uri>http://samples/RequestOrder</uri>:<programlisting><![CDATA[
339+
webServiceTemplate.marshalSendAndReceive(o, new ActionCallback("http://samples/RequestOrder"));
340+
]]></programlisting>
341+
342+
</para>
343+
</section>
316344
</section>
317345
<section>
318346
<title>

‎src/docbkx/server.xml‎

Lines changed: 133 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -850,7 +850,7 @@ public class AnnotationOrderEndpoint {
850850
<para>
851851
The mapping above routes requests which have a <literal>SOAPAction</literal> of
852852
<uri>http://samples/RequestOrder</uri> to the <literal>'getOrderEndpoint'</literal>. Requests with
853-
<uri>http://samples/CreateOrder</uri> will be routed to the <literal>'createController'</literal>.
853+
<uri>http://samples/CreateOrder</uri> will be routed to the <literal>'createOrderEndpoint'</literal>.
854854
</para>
855855
<caution>
856856
<para>
@@ -887,6 +887,138 @@ public class AnnotationOrderEndpoint {
887887
method will be invoked.
888888
</para>
889889
</section>
890+
<section id="server-ws-addressing">
891+
<title>WS-Addressing</title>
892+
<para>
893+
WS-Addressing specifies a transport-neutral routing mechanism. It is based on a
894+
<literal>To</literal> and <literal>Action</literal> SOAP header, which indicate the destination and
895+
intent of the SOAP message, respectively. Additionally, WS-Addressing allows you to define a return
896+
address (for normal messages and for faults), and a unique message identifier which can be used for
897+
correlation
898+
<footnote>
899+
<para>For more information on WS-Addressing, see <ulink url="http://en.wikipedia.org/wiki/WS-Addressing"/>.</para>
900+
</footnote>.
901+
Here is an example of a WS-Addressing message:
902+
<programlisting><![CDATA[<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
903+
xmlns:wsa="http://www.w3.org/2005/08/addressing">
904+
<SOAP-ENV::Header>
905+
<wsa:MessageID>urn:uuid:21363e0d-2645-4eb7-8afd-2f5ee1bb25cf</wsa:MessageID>
906+
<wsa:ReplyTo>
907+
<wsa:Address>http://example.com/business/client1</wsa:Address>
908+
</wsa:ReplyTo>
909+
<wsa:To S:mustUnderstand="true">http://example/com/fabrikam</wsa:To>
910+
<wsa:Action>http://example.com/fabrikam/mail/Delete</wsa:Action>
911+
</SOAP-ENV:Header>
912+
<SOAP-ENV:Body>
913+
<f:Delete xmlns:f="http://example.com/fabrikam">
914+
<f:maxCount>42</f:maxCount>
915+
</f:Delete>
916+
</SOAP-ENV:Body>
917+
</SOAP-ENV:Envelope>]]></programlisting>
918+
In this example, the destination is set to <uri>http://example/com/fabrikam</uri>, while the action is
919+
set to <uri>http://example.com/fabrikam/mail/Delete</uri>. Additionally, there is a message identifier,
920+
and an reply-to address. By default, this address is the "anonymous" address, indicating that a response
921+
should be sent using the same channel as the request (i.e. the HTTP response), but it can also be
922+
another address, as indicated in this example.
923+
</para>
924+
<para>
925+
In Spring Web Services, WS-Addressing is implemented as an endpoint mapping. Using this mapping, you
926+
associate WS-Addressing actions with endpoints, similar to the <classname>SoapActionEndpointMapping</classname>
927+
described above.
928+
</para>
929+
<section>
930+
<title><classname>SimpleActionEndpointMapping</classname></title>
931+
<para>
932+
The <classname>SimpleActionEndpointMapping</classname> is meant to be used in a standard Spring
933+
application context. It maps actions to endpoints via an exposed <property>mappings</property>
934+
property. Here is an example:<programlisting><![CDATA[<beans>
935+
<bean id="endpointMapping" class="org.springframework.ws.soap.addressing.server.SimpleActionEndpointMapping">
936+
<property name="mappings">
937+
<props>
938+
<prop key="http://samples/RequestOrder">getOrderEndpoint</prop>
939+
<prop key="http://samples/CreateOrder">createOrderEndpoint</prop>
940+
</props>
941+
</property>
942+
</bean>
943+
944+
<bean id="getOrderEndpoint" class="samples.GetOrderEndpoint">
945+
<constructor-arg ref="orderService"/>
946+
</bean>
947+
948+
<bean id="createOrderEndpoint" class="samples.CreateOrderEndpoint">
949+
<constructor-arg ref="orderService"/>
950+
</bean>
951+
</beans>]]></programlisting>
952+
</para>
953+
<para>
954+
The mapping above routes requests which have a WS-Addressing <literal>Action</literal> of
955+
<uri>http://samples/RequestOrder</uri> to the <literal>'getOrderEndpoint'</literal>. Requests with
956+
<uri>http://samples/CreateOrder</uri> will be routed to the <literal>'createOrderEndpoint'</literal>.
957+
</para>
958+
<para>
959+
By default, the <classname>SimpleActionEndpointMapping</classname> supports both the 1.0
960+
(May 2006), and the August 2004 editions of WS-Addressing. These two versions are most popular, and
961+
are interoperably with Axis 1 and 2, JAX-WS, XFire, Windows Communication Foundation (WCF), and
962+
Windows Services Enhancemenets (WSE) 3.0. If necessary, specific versions of the spec can be
963+
injected into the <property>versions</property> property.
964+
</para>
965+
<para>
966+
Besides the <property>mappings</property> property, the endpoint mapping also has an
967+
<property>address</property> property. If set, value of this property is compared to the
968+
<literal>To</literal> header property of the incominging message.
969+
</para>
970+
<para>
971+
Finally, there is the <property>messageSenders</property> property, which is required for sending
972+
response messages to non-anonymous, out-of-bound addresses. You can set <interfacename>MessageSender</interfacename>
973+
implementations in this property, the same as you would on the <classname>WebServiceTemplate</classname>.
974+
See <xref linkend="client-transports"/>.
975+
</para>
976+
</section>
977+
<section>
978+
<title><classname>AnnotationActionEndpointMapping</classname></title>
979+
<para>
980+
The <classname>AnnotationActionEndpointMapping</classname> is quite similar to the <classname>SimpleActionEndpointMapping</classname>.
981+
It has the same <property>versions</property> and <property>messageSenders</property> properties,
982+
but uses Java 5 annotations.
983+
</para>
984+
<para>
985+
To use the <classname>AnnotationActionEndpointMapping</classname>, annotate the handling methods
986+
with the <interfacename>@Action</interfacename> annotation, similar to the
987+
<interfacename>@PayloadRoot</interfacename> and <interfacename>@SoapAction</interfacename>
988+
annotations described in <xref linkend="server-at-endpoint"/> and
989+
<xref linkend="server-method-endpoint-mapping"/>. Here is an example:
990+
<programlisting><![CDATA[package samples;
991+
992+
import org.springframework.ws.server.endpoint.annotation.Endpoint;
993+
import org.springframework.ws.soap.addressing.server.annotation.Action
994+
995+
@Endpoint
996+
public class AnnotationOrderEndpoint {
997+
private final OrderService orderService;
998+
999+
public AnnotationOrderEndpoint(OrderService orderService) {
1000+
this.orderService = orderService;
1001+
}
1002+
1003+
@Action("http://samples/RequestOrder")
1004+
public Order getOrder(OrderRequest orderRequest) {
1005+
return orderService.getOrder(orderRequest.getId());
1006+
}
1007+
1008+
@Action("http://samples/CreateOrder")
1009+
public void order(Order order) {
1010+
orderService.createOrder(order);
1011+
}
1012+
1013+
}]]></programlisting>
1014+
</para>
1015+
<para>
1016+
In addition to the <interfacename>@Action</interfacename> annotation, you can annotate the class
1017+
with the <interfacename>@Address</interfacename> annotation. If set, the value is compared to the
1018+
<literal>To</literal> header property of the incominging message.
1019+
</para>
1020+
</section>
1021+
</section>
8901022
<section id="server-endpoint-interceptor">
8911023
<title>Intercepting requests - the <interfacename>EndpointInterceptor</interfacename> interface</title>
8921024
<para>

0 commit comments

Comments
 (0)