196 lines
8.5 KiB
XML
196 lines
8.5 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
<chapter id="server">
|
|
<title>Creating a Web service with Spring-WS</title>
|
|
<!--
|
|
<section id="ws-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
Spring's Web service framework is designed around
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>MessageDispatcher</title>
|
|
<para>
|
|
Spring-WS is designed around a central dispatching mechanism, which received and forwards incoming
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Endpoints</title>
|
|
</section>
|
|
<section id="ws-endpoint-mapping">
|
|
<title>Endpoint mappings</title>
|
|
<para>
|
|
The endpoint mapping is responsible for mapping incoming messages to appropriate endpoints. It does this by
|
|
delivering a <classname>EndpointInterceptorChain</classname>, which consists of the endpoint that matches
|
|
the incoming request, and an optional list of endpoint interceptors. When a message is received by the
|
|
<classname>MessageDispatcher</classname>, it will ask the registered endpoint mappings to come up with a
|
|
appropriate <classname>HandlerExecutionChain</classname>. After that, the
|
|
<classname>MessageDispatcher</classname> will invoke the endpoint and interceptors in the chain.
|
|
</para>
|
|
<para>
|
|
Most endpoint mappings inherit from the <classname>AbstractEndpointMapping</classname>, which offers the
|
|
following properties:
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<methodname>interceptors</methodname>
|
|
</entry>
|
|
<entry>
|
|
the list of interceptors use. <interfacename>EndpointInterceptor</interfacename>s are
|
|
discussed in <xref linkend="ws-endpoint-interceptor"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<methodname>defaultHandler</methodname>
|
|
</entry>
|
|
<entry>
|
|
the default handler to use. This endpoint will be returned if no specific mapping was
|
|
found.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
|
|
</entry>
|
|
</row>
|
|
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<section>
|
|
<title>SoapActionEndpointMapping</title>
|
|
</section>
|
|
<section>
|
|
<title>PayloadRootQNameEndpointMapping</title>
|
|
</section>
|
|
<section id="ws-endpoint-interceptor">
|
|
<title>Adding <interfacename>EndpointInterceptors</interfacename></title>
|
|
</section>
|
|
<section>
|
|
<title>Handling Exceptions</title>
|
|
<para>
|
|
Spring-WS provides
|
|
<classname>EndpointExceptionResolvers</classname>
|
|
to ease the pain of unexpected
|
|
exceptions occurring while your message is being processed by an endpoint which matched the request.
|
|
<classname>EndpointExceptionResolver</classname>
|
|
s somewhat resemble the exception mappings that can be
|
|
defined in the web application descriptor
|
|
<filename>web.xml</filename>
|
|
.
|
|
Rather than expose the innards of your application by giving a client a full stack trace, you can handle
|
|
the exception any way you want, e.g. return a SOAP fault with a specific fault code and string.
|
|
Furthermore, a programmatic way of handling exceptions gives you many more options for how to respond
|
|
appropriately.
|
|
</para>
|
|
<para>
|
|
Besides implementing the
|
|
<classname>HandlerExceptionResolver</classname>
|
|
interface, which is only a
|
|
matter of implementing the
|
|
<methodname>resolveException(MessageContext, endpoint, Exception)</methodname>
|
|
method and returning a
|
|
boolean, you may also use the
|
|
<classname>SoapFaultMappingExceptionResolver</classname>
|
|
.
|
|
This resolver enables you to take the class name of any exception that might be thrown and map it to a
|
|
SOAP Fault, like so:
|
|
<programlisting><![CDATA[
|
|
<bean id="exceptionResolver"
|
|
class="org.springframework.ws.soap.endpoint.SoapFaultMappingExceptionResolver">
|
|
<property name="defaultFault" value="RECEIVER,Server error">
|
|
</property>
|
|
<property name="exceptionMappings">
|
|
<props>
|
|
<prop key="org.springframework.oxm.ValidationFailureException">
|
|
SENDER,Invalid request
|
|
</prop>
|
|
</props>
|
|
</property>
|
|
</bean>
|
|
]]></programlisting>
|
|
This configuration will map exceptions of type
|
|
<classname>ValidationFailureException</classname>
|
|
to a
|
|
sender side SOAP Fault with a fault string "Invalid request".
|
|
If any other exception occurs, it will return the default fault: a server side fault with fault string
|
|
"Server error".
|
|
Refer to the Javadoc of
|
|
<classname>SoapFaultDefinitionEditor</classname>
|
|
to read more about the exact
|
|
notation of the faults.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Similarities between Spring-MVC and Spring-WS</title>
|
|
<para>
|
|
Spring-WS has the same basic architecture as Spring's Web MVC framework.
|
|
The table below shows some of the core concepts of Spring Web MVC, and the corresponding class in Spring-WS.
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Spring Web MVC</entry>
|
|
<entry>Spring Web Services</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<classname>DispatcherServlet</classname>
|
|
</entry>
|
|
<entry>
|
|
<classname>MessageDispatcher</classname>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>handler</entry>
|
|
<entry>endpoint</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<classname>HandlerAdapter</classname>
|
|
</entry>
|
|
<entry>
|
|
<classname>EndpointAdapter</classname>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<classname>HandlerMapping</classname>
|
|
</entry>
|
|
<entry>
|
|
<classname>EndpointMapping</classname>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<classname>HandlerInterceptor</classname>
|
|
</entry>
|
|
<entry>
|
|
<classname>EndpointInterceptor</classname>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<classname>HandlerExceptionResolver</classname>
|
|
</entry>
|
|
<entry>
|
|
<classname>EndpointExceptionResolver</classname>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</section>
|
|
-->
|
|
</chapter> |