Skip to content

Commit b0d9c92

Browse files
poutsmapoutsma
committed
Moved Spring-WS to seperate dir
0 parents  commit b0d9c92

File tree

623 files changed

+44106
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

623 files changed

+44106
-0
lines changed

‎doc/pom.xml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
3+
<parent>
4+
<artifactId>spring-ws</artifactId>
5+
<groupId>org.springframework.ws</groupId>
6+
<version>1.0-m2</version>
7+
</parent>
8+
<modelVersion>4.0.0</modelVersion>
9+
<artifactId>spring-ws-doc</artifactId>
10+
<packaging>pom</packaging>
11+
<name>Spring WS Documentation</name>
12+
<pluginRepositories>
13+
<pluginRepository>
14+
<id>agilejava</id>
15+
<url>http://agilejava.com/maven/</url>
16+
</pluginRepository>
17+
</pluginRepositories>
18+
<build>
19+
<plugins>
20+
<plugin>
21+
<groupId>com.agilejava.docbkx</groupId>
22+
<artifactId>docbkx-maven-plugin</artifactId>
23+
<version>1.69.1.7</version>
24+
<executions>
25+
<execution>
26+
<goals>
27+
<goal>generate-html</goal>
28+
<goal>generate-pdf</goal>
29+
</goals>
30+
<phase>generate-sources</phase>
31+
</execution>
32+
</executions>
33+
<dependencies>
34+
<dependency>
35+
<groupId>org.docbook</groupId>
36+
<artifactId>docbook-xml</artifactId>
37+
<version>4.4</version>
38+
<scope>runtime</scope>
39+
</dependency>
40+
</dependencies>
41+
<configuration>
42+
<includes>index.xml</includes>
43+
<chunkedOutput>true</chunkedOutput>
44+
<entities>
45+
<entity>
46+
<name>version</name>
47+
<value>${version}</value>
48+
</entity>
49+
</entities>
50+
</configuration>
51+
</plugin>
52+
</plugins>
53+
</build>
54+
</project>

‎doc/src/docbkx/bibliography.xml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<bibliography>
2+
<title>Bibliography</title>
3+
<biblioentry id="waldo-94">
4+
<authorgroup>
5+
<author>
6+
<firstname>Jim</firstname><surname>Waldo</surname>
7+
</author>
8+
<author>
9+
<firstname>Ann</firstname><surname>Wollrath</surname>
10+
</author>
11+
<author>
12+
<firstname>Sam</firstname><surname>Kendall</surname>
13+
</author>
14+
</authorgroup>
15+
<title>A Note on Distributed Computing</title>
16+
<publisher><publishername>Springer Verlag</publishername></publisher>
17+
<date>1994</date>
18+
</biblioentry>
19+
<biblioentry id="alpine">
20+
<authorgroup>
21+
<author>
22+
<firstname>Steve</firstname><surname>Loughran</surname>
23+
</author>
24+
<author>
25+
<firstname>Edmund</firstname><surname>Smith</surname>
26+
</author>
27+
</authorgroup>
28+
<title>Rethinking the Java SOAP Stack</title>
29+
<date>May 17, 2005</date>
30+
<copyright><year>2005</year>
31+
<holder>IEEE Telephone Laboratories, Inc.</holder></copyright>
32+
</biblioentry>
33+
</bibliography>

‎doc/src/docbkx/contract-first.xml‎

Lines changed: 365 additions & 0 deletions
Large diffs are not rendered by default.

‎doc/src/docbkx/images/oxm-exceptions.png‎

20.3 KB
Loading

‎doc/src/docbkx/images/oxm-exceptions.svg‎

Lines changed: 48 additions & 0 deletions
Loading

‎doc/src/docbkx/index.xml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
3+
<!ENTITY preface SYSTEM "preface.xml">
4+
<!ENTITY overview SYSTEM "overview.xml">
5+
<!ENTITY contract-first SYSTEM "contract-first.xml">
6+
<!ENTITY ws SYSTEM "ws.xml">
7+
<!ENTITY security SYSTEM "security.xml">
8+
<!ENTITY oxm SYSTEM "oxm.xml">
9+
<!ENTITY bibliography SYSTEM "bibliography.xml">
10+
]>
11+
<book>
12+
13+
<bookinfo>
14+
<title>Spring Web Services</title>
15+
<subtitle>
16+
Reference Documentation
17+
</subtitle>
18+
<releaseinfo>Version &version;</releaseinfo>
19+
<pubdate>(Work in progress)</pubdate>
20+
21+
<authorgroup>
22+
<author>
23+
<firstname>Arjen</firstname>
24+
<surname>Poutsma</surname>
25+
</author>
26+
</authorgroup>
27+
28+
<legalnotice>Copies of this document may be made for your own use and for distribution to others, provided that
29+
you do not charge any fee for such copies and further provided that each copy contains this Copyright
30+
Notice, whether distributed in print or electronically.</legalnotice>
31+
</bookinfo>
32+
33+
<toc/>
34+
35+
&preface;
36+
37+
&overview;
38+
39+
&contract-first;
40+
41+
&ws;
42+
43+
&security;
44+
45+
&oxm;
46+
47+
&bibliography;
48+
49+
</book>

‎doc/src/docbkx/overview.xml‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<chapter id="introduction">
3+
<title>Introduction</title>
4+
5+
<section>
6+
<title>Overview</title>
7+
<para>
8+
Spring-WS consists of three separate modules. This chapter discusses each of the modules in turn.
9+
</para>
10+
<para>
11+
The <link linkend="ws">Core</link> package is the central part of the Web services functionality. It
12+
provides the central <classname>WebServiceMessage</classname> and <classname>SoapMessage</classname>
13+
interfaces, the powerful message dispatching, and the various support classes for implementing Web service
14+
endpoints.
15+
</para>
16+
<para>
17+
The <link linkend="security">Security</link> package provides a WS-Security implementation that integrates
18+
with the core Web service package. It allows you to add principal tokens, sign, and decrypt and encrypt SOAP
19+
messages. Addtionally, it allows you to leverage your existing Acegi security implementation for
20+
authentication and authorization.
21+
</para>
22+
<para>
23+
The <link linkend="oxm">OXM</link> package provides integration for popular XML marshalling APIs, including
24+
JAXB 1 and 2. Using the OXM package means that you benefit from a unified exception hierarchy, and can wire
25+
up your favorite XML marshalling technology easily.
26+
</para>
27+
</section>
28+
29+
30+
<section>
31+
<title>Why Spring Web Services?</title>
32+
<para>
33+
There are various other SOAP stacks available, why and where should you use Spring-WS? This section answers
34+
that question by showing what the focus of Spring-WS is.
35+
</para>
36+
<section>
37+
<title>Spring-WS is meant for Public Web Services</title>
38+
<para>
39+
One can distinguish between two different sorts of Web services. Private Web services are not used
40+
outside your application domain. They might form a part of your Enterprise Service Bus, or used as a
41+
means to communicate between a fat .NET client and a J2EE server. When the two sides of the spectrum
42+
(client and server) are under your control, you can easily expose (existing) methods, since you can
43+
(re)generate client code easily.
44+
</para>
45+
<para>
46+
Public Web services provide a separate interface to your application. They are often used by clients
47+
that are outside of your reach. When developing a public Web service, you should really think about the
48+
interface you are providing: it is probably going to be around for a while, and you cannot change it
49+
that often. As such, it is a good idea to place the Web service in a separate layer, thus hiding the
50+
inner workings of the application. As a result, you can change the Web service and the rest of the
51+
appliciation seperately.
52+
</para>
53+
</section>
54+
<section>
55+
<title>Spring-WS makes Web Services First Class Citizens of the Architecture</title>
56+
<para>
57+
Web Services deserve a proper place in an application architecture. Often, they exist as an afterthought
58+
in the application architecture, mostly because existing Java business interfaces are exposed as SOAP
59+
services. One could say that they are "SOAPified". Spring-WS provides a MVC-like framework for
60+
developing a Web service application layer, just like you would develop a layer especially for a Web
61+
user interface using Spring-MVC. Spring-WS also provides useful integration points with you existing
62+
Spring application architecture, such as the Acegi integration.
63+
</para>
64+
</section>
65+
<section>
66+
<title>Spring-WS is Data-Driven</title>
67+
<para>
68+
When Web Services started making their way into the Enterprise Computing world, developers considered
69+
Web Services just another, XML-based remoting protocol. Such remoting frameworks can be used with
70+
relative ease: on the server-side, one simply implements a specific interface such as
71+
<classname>java.rmi.Remote</classname>, and on the client side, a dynamic proxy is used.
72+
Unfortunately, because of this simplicity, remoting architectures have some issues:
73+
<itemizedlist>
74+
<listitem>
75+
<para>
76+
They pretend there is no <emphasis>latency</emphasis> between the client and the server,
77+
while in fact there is both network and application latency,
78+
</para>
79+
</listitem>
80+
<listitem>
81+
<para>
82+
They pretend that client and server have <emphasis>shared memory access</emphasis>, while in
83+
fact data must be both marshalled and unmarshalled,
84+
</para>
85+
</listitem>
86+
<listitem>
87+
<para>
88+
They ignore the possibility of a <emphasis>request or response not reaching its
89+
destination</emphasis>,
90+
</para>
91+
</listitem>
92+
<listitem>
93+
<para>
94+
They enforce a <emphasis>non-concurrent</emphasis> programming model, while in fact a
95+
concurrent approach seems more in place,
96+
</para>
97+
</listitem>
98+
<listitem>
99+
<para>
100+
They enforce a <emphasis>tightly coupled architecture</emphasis>, where changes on the
101+
server-side result in changes on the client-side.
102+
</para>
103+
</listitem>
104+
</itemizedlist>
105+
It is not without reason that Gregor Hohpe calls a distributed architecture a <quote>fairy tale
106+
architecture</quote>: one is made to believe things that simply are not true. To quote <xref
107+
linkend="waldo-94"/>:
108+
<blockquote>
109+
<para>
110+
Objects that interact in a distributed system need to be dealt with in ways that are
111+
intrinsically different from objects that interact in a single address space.
112+
</para>
113+
</blockquote>
114+
</para>
115+
<para>
116+
Instead of being behavior-driven, Spring-WS is data-driven: it focusses on the data being sent, not on a
117+
particular method being invoked.
118+
</para>
119+
</section>
120+
<section>
121+
<title>Spring-WS Focusses on Contract-first Development</title>
122+
<para>
123+
SOAP services are defined in two contracts: the data contract (the XSD schema), and the service contract
124+
(the WSDL). Generating these contracts from Java-code is called <emphasis>contract-last
125+
development</emphasis> <xref linkend="alpine"/> identifies some problems with this approach, most
126+
importantly:
127+
<blockquote>
128+
<para>
129+
There is no way to ensure that a service’s published interface remains constant over time.
130+
Every redeployment of the service may change the classes, and hence the contract.
131+
</para>
132+
</blockquote>
133+
The alternative of contract-last development is <emphasis>contract-first development</emphasis>.
134+
Using this approach, the service and data contract are leading. Spring-WS focusses on contract-first Web
135+
service development, because is considered to be a best practice. After all, the actual XML that is sent
136+
across the wire is more important than the Java code that is used to implement it.
137+
</para>
138+
</section>
139+
</section>
140+
</chapter>

0 commit comments

Comments
 (0)