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

Browse Source
This commit is contained in:
Arjen Poutsma
2007-04-22 08:49:16 +00:00
parent 494edbb56e
commit f1ddfb63e9
1 changed files with 90 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
src/docbkx/tutorial.xml Normal file
View File

@@ -0,0 +1,90 @@
<?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="tutorial">
<title>Writing Contract-First Web Services</title>
<section>
<title>Introduction</title>
<para>
This tutorial shows you how to write contract-first Web services, i.e. starting with the XML Schema/WSDL
contract instead of Java code. Spring Web Services focuses on this development style, and this tutorial
helps you get started. Note that the first part of this tutorial contains almost no Spring-WS specific
information: it is mostly about XML, XSD, and WSDL. The second part focusses on implementing this contract
using Spring-WS.
</para>
<para>
In this tutorial, we will define a Web service that is created by a Human Resources department. Clients can
send holiday request forms to this service to book a holiday.
</para>
<para>
The most important thing when doing contract-first Web service development is to try and think in terms of
XML. This means that Java-language concepts are of lesser importance. It is the XML that is sent across the
wire, and you should focus on that. The fact that Java is used to implement the Web service is an
implementation detail. An important detail, but a detail nonetheless.
</para>
</section>
<section>
<title>Messages</title>
<para>
In this section, we will focus on the actual XML messages that are sent to and from the service. We will
start out by determining what these messages look like.
</para>
<section>
<title>Holiday</title>
<para>
In the scenario, we have to deal with holiday request, so it makes sense to determine what a holiday
looks like:
</para>
<programlisting><![CDATA[
<Holiday xmlns="http://mycompany.com/hr/schemas">
<StartDate>2006-07-03</StartDate>
<EndDate>2006-07-07</EndDate>
</Holiday>]]></programlisting>
<para>
A holiday consists of a start date and an end date. We decided to use the standard
<ulink url="http://www.cl.cam.ac.uk/~mgk25/iso-time.html">ISO 8601</ulink> date format for the dates,
because that will save a lot of parsing hassle. We also added a namespace to the element, to make sure
our elements can used within other XML documents.
</para>
</section>
<section>
<title>Employee</title>
<para>
There is also the notion of an employee in the scenario. Here's what it looks like:
</para>
<programlisting><![CDATA[
<Employee xmlns="http://mycompany.com/hr/schemas">
<Number>42</Number>
<FirstName>Arjen</FirstName>
<LastName>Poutsma</LastName>
</Employee>]]></programlisting>
<para>
We have used the same namespace as before. If this employee element could be used in other scenarios, it
might make sense to use a different namespace, such as
<literal>http://mycompany.com/employees/schemas</literal>.
</para>
</section>
<section>
<title>HolidayRequest</title>
<para>
Both the holiday and employee element can be put in a <literal>HolidayRequest</literal>:
</para>
<programlisting><![CDATA[
<HolidayRequest xmlns="http://mycompany.com/hr/schemas">
<Holiday>
<StartDate>2006-07-03</StartDate>
<EndDate>2006-07-07</EndDate>
</Holiday>
<Employee>
<Number>42</Number>
<FirstName>Arjen</FirstName>
<LastName>Poutsma</LastName>
</Employee>
</HolidayRequest>]]></programlisting>
<para>
The order of the two element does not matter: <literal>Employee</literal> could have been the first element just as well. As long as all the data is there; that's what is
important. In fact, the data is the only thing that is important: we are taking a <emphasis>data-driven</emphasis> approach.
</para>
</section>
</section>
</chapter>