Spring/spring-ws
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

More Docs.

Browse Source
This commit is contained in:
Arjen Poutsma
2007-05-15 00:24:28 +00:00
parent 81f209cfb6
commit d364beafb1
5 changed files with 134 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/docbkx/client.xml
View File

@@ -21,7 +21,7 @@
</section>
<section>
<title>Using the client-side API</title>
<section>
<section id="client-webservicetemplate">
<title><classname>WebServiceTemplate</classname></title>
<para>
The <classname>WebServiceTemplate</classname> is the core class for client-side Web service access in

54
src/docbkx/common.xml
View File

@@ -31,43 +31,25 @@
</thead>
<tbody>
<row>
<entry>
<classname>javax.xml.transform.dom.DOMSource</classname>
</entry>
<entry>
<interfacename>org.w3c.dom.Node</interfacename>
</entry>
<entry><classname>javax.xml.transform.dom.DOMSource</classname></entry>
<entry><interfacename>org.w3c.dom.Node</interfacename></entry>
</row>
<row>
<entry>
<classname>javax.xml.transform.dom.DOMResult</classname>
</entry>
<entry>
<interfacename>org.w3c.dom.Node</interfacename>
</entry>
<entry><classname>javax.xml.transform.dom.DOMResult</classname></entry>
<entry><interfacename>org.w3c.dom.Node</interfacename></entry>
</row>
<row>
<entry>
<classname>javax.xml.transform.sax.SAXSource</classname>
</entry>
<entry>
<classname>org.xml.sax.InputSource</classname>
and
<entry><classname>javax.xml.transform.sax.SAXSource</classname></entry>
<entry><classname>org.xml.sax.InputSource</classname> and
<interfacename>org.xml.sax.XMLReader</interfacename>
</entry>
</row>
<row>
<entry>
<classname>javax.xml.transform.sax.SAXResult</classname>
</entry>
<entry>
<interfacename>org.xml.sax.ContentHandler</interfacename>
</entry>
<entry><classname>javax.xml.transform.sax.SAXResult</classname></entry>
<entry><interfacename>org.xml.sax.ContentHandler</interfacename></entry>
</row>
<row>
<entry>
<classname>javax.xml.transform.stream.StreamSource</classname>
</entry>
<entry><classname>javax.xml.transform.stream.StreamSource</classname></entry>
<entry>
<classname>java.io.File</classname>, <classname>java.io.InputStream</classname>, or
<classname>java.io.Reader</classname>
@@ -154,5 +136,23 @@
</para>
</section>
</section>
<section id="message-context">
<title><interfacename>MessageContext</interfacename></title>
<para>
Typically, messages come in pairs: a request and a response. A request is created on the client-side,
which is sent over some transport to the server-side, where a response is generated. This response gets
sent back to the client, where it is read.
</para>
<para>
In Spring Web Services, such a conversation is contained in a
<interfacename>MessageContext</interfacename>, which has properties to get request and response
messages.
On the client-side, the message context is created by the <link linkend="client-webservicetemplate">
<classname>WebServiceTemplate</classname></link>.
On the server-side, the message context is read from the transport-specific input stream. In HTTP,
it is read from the <interfacename>HttpServletRequest</interfacename> and the response is written back
to the <interfacename>HttpServletResponse</interfacename>.
</para>
</section>
</section>
</chapter>

BIN
src/docbkx/resources/images/sequence.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

4
src/docbkx/security.xml
View File

@@ -60,7 +60,7 @@
is an
<classname>EndpointInterceptor</classname>
(see
<xref linkend="ws-endpoint-interceptor" />
<xref linkend="server-endpoint-interceptor" />
) that is based on SUN's XML and Web Services Security package (XWSS). This WS-Security implementation is
part of the Java Web Services Developer Pack (
<ulink url="http://java.sun.com/webservices/">
@@ -70,7 +70,7 @@
</para>
<para>
Like any other endpoint interceptor, it is defined in the endpoint mapping (see
<xref linkend="ws-endpoint-mapping" />
<xref linkend="server-endpoint-mapping" />
). This means that you can be selective about adding WS-Security support: some endpoint mappings require it,
while others do not.
</para>

115
src/docbkx/server.xml
View File

@@ -3,23 +3,114 @@
"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
Spring Web Services's server-side support in designed around a <classname>MessageDispatcher</classname>
that dispatches incoming messages to endpoints, with configurable endpoint mappings, response generation,
and endpoint interception.
The simplest endpoint is a <interfacename>PayloadEndpoint</interfacename>, just offering a
<literal>Source invoke(Source request)</literal> method. This interface can be implemented for creating an
endpoint, but you will prefer the included implementation hierarchy, consisting of, for example
<classname>AbstractDomPayloadEndpoint</classname>, <classname>AbstractSaxPayloadEndpoint</classname>, and
of course <classname>AbstractMarshallingPayloadEndpoint</classname>. Application endpoints will typically
be subclasses of those.
Alternatively, there is a endpoint development that uses Java 5 annotations, such as
<literal>@Endpoint</literal> for marking a POJO as endpoint, and marking a method with
<literal>@PayloadRoot</literal> or <literal>@SoapAction</literal>.
</para>
<para>
Spring-WS's XML handling is extremely flexible. An endpoint can choose from
a large amount of XML handling libraries supported by Spring-WS, including the DOM family (W3C DOM, JDOM,
dom4j, and XOM), SAX or StAX for faster performance, XPath to extract information from the message, or even
marshalling to convert the XML to objects and vice-versa.
</para>
</section>
<section>
<title>MessageDispatcher</title>
<para>
Spring-WS is designed around a central dispatching mechanism, which received and forwards incoming
</para>
</section>
<title>The <classname>MessageDispatcher</classname></title>
<para>
The server-side of Spring-WS is designed around a central class that dispatches incoming XML messages to
endpoints. Spring-WS's <classname>MessageDispatcher</classname> is extremely flexible, allowing you to
use any sort of class as an endpoint, as long as it can be configured in the Spring IoC container.
In a way, the message dispatcher resembles Spring's<classname>DispatcherServlet</classname>, the
<quote>Front Controller</quote> used in Spring Web MVC.
</para>
<para>
The processing and dispatching flow of the <classname>MessageDispatcher</classname> is illustrated in the
following sequence diagram. Whenever a message comes in, a suitable endpoint is retrieved via the
<interfacename>EndpointMapping</interfacename>. After the endpoint has been determined, the
<classname>MessageDispatcher</classname> delegates to an <interfacename>EndpointAdapter</interfacename>
to adapt to the specific method signature of the endpoint class. After the endpoint has been invoked, the
result value of the endpoint, if any, is converted back by the adapter after the invocation, and the
response is sent on its way.
<mediaobject>
<imageobject role="fo">
<imagedata fileref="src/docbkx/resources/images/sequence.png" format="PNG" align="center" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/sequence.png" format="PNG" align="center" />
</imageobject>
<caption>
<para>The request processing workflow in Spring Web Services</para>
</caption>
</mediaobject>
</para>
<para>
The <classname>MessageDispatcher</classname> has several properties, for setting endpoint adapters,
<link linkend="server-endpoint-mapping">mappings</link>,
<link linkend="server-endpoint-exception-resolver">exception resolvers</link>.
However, setting these properties is not required, since the dispatcher will automatically detect all of
these types that are registered in the application context. Only when detection needs to be overriden,
should these properties be set.
</para>
<para>
The message dispatcher operates on a <link linkend="message-context">message context</link>, and not
transport-specific input stream and output stream. As a result, transport specific requests need to read
into a <interfacename>MessageContext</interfacename>. For HTTP, this is done with a
<classname>WebServiceMessageReceiverHandlerAdapter</classname>, which is a Spring Web
<interfacename>HandlerInterceptor</interfacename>, so that the <classname>MessageDispatcher</classname>
can be wired in a standard <classname>DispatcherServlet</classname>. There is a more convenient way to do
this, however, which is shown in the next section.
</para>
<section>
<title><classname>MessageDispatcherServlet</classname></title>
<para>
The <classname>MessageDispatcherServlet</classname> is a standard <interface>Servlet</interface> which
conveniently extends from the standard Spring Web <classname>DispatcherServlet</classname>, and wraps
a <classname>MessageDispatcher</classname>. As a servlet, the
<classname>MessageDispatcherServlet</classname> is configured in the <filename>web.xml</filename> of
your web application. Requests that you want the <classname>MessageDispatcherServlet</classname> to
handle will have to be mapped using a URL mapping in the same <literal>web.xml</literal> file. This is
standard Java EE servlet configuration; an example of such a
<classname>MessageDispatcherServlet</classname> declaration and mapping can be found below.
</para>
<programlisting><![CDATA[<web-app>
<servlet>
<servlet-name>spring-ws</servlet-name>
<servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>spring-ws</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>]]></programlisting>
<para>
In the example above, all requests will be handled by the <literal>'spring-ws'</literal>
<classname>MessageDispatcherServlet</classname>. This is only the first step in setting up Spring Web
Services; the various endpoint and other beans used by the Spring Web Services framework also need to be
configured.
</para>
</section>
</section>
<section>
<title>Endpoints</title>
<para/>
</section>
<section id="ws-endpoint-mapping">
<section id="server-endpoint-mapping">
<title>Endpoint mappings</title>
<para>
The endpoint mapping is responsible for mapping incoming messages to appropriate endpoints. It does this by
@@ -65,14 +156,17 @@
</para>
<section>
<title>SoapActionEndpointMapping</title>
<para/>
</section>
<section>
<title>PayloadRootQNameEndpointMapping</title>
<para/>
</section>
<section id="ws-endpoint-interceptor">
<section id="server-endpoint-interceptor">
<title>Adding <interfacename>EndpointInterceptors</interfacename></title>
<para/>
</section>
<section>
<section id="server-endpoint-exception-resolver">
<title>Handling Exceptions</title>
<para>
Spring-WS provides
@@ -192,5 +286,4 @@
</informaltable>
</para>
</section>
-->
</chapter>