diff --git a/src/site/apt/resources.apt b/src/site/apt/resources.apt index aa19c089..cdfb6d4b 100644 --- a/src/site/apt/resources.apt +++ b/src/site/apt/resources.apt @@ -2,10 +2,6 @@ Resources --------- -Tutorial - - * {{{http://blog.springframework.com/arjen/archives/2006/06/09/tutorial-writing-contract-first-web-services/}Writing Contract-first Web Services}} - SOAP Reference Below are some resources which help you understand SOAP in general. These are not tied to Spring-WS. diff --git a/src/site/apt/tutorial/tutorial1.apt b/src/site/apt/tutorial/tutorial1.apt new file mode 100644 index 00000000..0bd98774 --- /dev/null +++ b/src/site/apt/tutorial/tutorial1.apt @@ -0,0 +1,340 @@ + ----------------------------------- + Writing Contract-first Web Services + ----------------------------------- + +Introduction + + This is an overall tutorial on how to approach Web services development in contract-first style, i.e. starting with the XML Schema/WSDL contract instead of Java code. Spring Web Services focusses on this development style, and this +tutorial helps you get started. Note that this chapter contains almost no Spring-WS specific information: it is mostly +about XML, XSD, and WSDL. + + In this tutorial, we will define a Web service that can be used for Human Resources. Clients can send +holiday request forms to this service to book a holiday. It is based on a metaphor for Service Oriented Architectures +originally though of by {{{url="http://blog.springframework.com/arjen/archives/2006/02/06/what-is-so-hard-about-soa/}Dan +North}}. + + 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 Messages + + 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. + +* Holiday + + In the scenario, we have to deal with holiday request, so it makes sense to determine what a holiday looks like: + ++------------------------------------- + + 2006-07-03 + 2006-07-07 + ++------------------------------------- + + A holiday consists of a start date and an end date. We decided to use the standard +{{{http://www.cl.cam.ac.uk/~mgk25/iso-time.html}ISO 8601}} 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. + +* Employee + + There is also the notion of an employee in the scenario. Here's what it looks like: + ++------------------------------------- + + 42 + Arjen + Poutsma + ++------------------------------------- + + + 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 <<<"http://mycompany.com/employees/schemas">>>. + +* HolidayRequest + + Both the holiday and employee element can be put in a <<>>: + ++------------------------------------- + + + 2006-07-03 + 2006-07-07 + + + 42 + Arjen + Poutsma + + ++------------------------------------- + + The order of the two element does not matter: <<>> 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 approach. + +The Schema + + Now that we have seen some examples of the XML data that we will use, it makes sense to formalize this into +a schema. Basically, there are four different ways of defining a grammar for XML: + + * DTDs + + * {{{http://www.w3.org/XML/Schema}XML Schema (XSD)}} + + * {{{http://www.relaxng.org/}RELAX NG}} + + * {{{http://www.schematron.com/}Schematron}} + + DTDs have limited namespaces support, so they are not suitable for Web services. Relax NG and Schematron are +certainly easier than XSDs. Unfortunately, they are not so widely supported across platforms. We will use XML +Schema. + + By far the easiest way to create a XSD is to infer it from sample documents. Any good XML editor or Java IDE +offers this functionality. Basically, these tools use some sample XML documents, and generate a schema from it +that validates them all. The end result certainly needs to be polished up, but it's a great starting +point. + + Using the sample described above, we end up with the following generated schema: + ++------------------------------------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ++------------------------------------- + + The generated schema can obviously be improved. The first thing to notice is that everything is a root-level +element. This means that the Web service should be able to accept all of these elements as data. This is not desirable: +we only want to accept a <<>>. By removing the wrapping element tags (thus keeping the +types), and inlining the results, we can accomplish this. + ++------------------------------------- + + + + + /> + /> + + + + + + + + + + + + + + + + + ++------------------------------------- + + The schema still has one problem: with a schema like this, you can expect the following messages to +validate: + ++------------------------------------- + + + this is not a date + neither is this + + ... + ++------------------------------------- + + Clearly, we must make sure that the start and end date are really dates. XML Schema has an excellent built-in +<<>> type which we can use. We also change the <<>>s to <<>>s. Finally, we change the +<<>> in <<>> to <<>>. This tells the XML parser that the order of <<>> and +<<>> is not significant. Our final XSD looks like this: + ++------------------------------------- + + + + + + + + + + + + /> + /> + + + + + + /> + /> + + + ++------------------------------------- + + We can store this file with a convenient name such as <<>>. + +The WSDL + + Which leaves the WSDL. We start our WSDL with the standard preamble, and by importing our existing XSD. To +separate the schema from the definition, we will use a separate namespace for the WSDL definitions: +<<<"http://mycompany.com/holidays/definitions">>>. + ++------------------------------------- + + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"> + + + + + + ++------------------------------------- + + Next, we define our messages based on the written schema. We only have one message: one with the +<<>> we put in the schema: + ++------------------------------------- + + + + + + + > + + + ++------------------------------------- + + We add the messages to a port type as operations: + ++------------------------------------- + + + + + + + + + + + + + + + ++------------------------------------- + + That finished the abstract part of the WSDL (the interface, as it were), and leaves the concrete part. This +part consists of a <<>>, which tells the client to invoke the operations you've just defined; and a +<<>>, which tells it to invoke it. + + Adding a concrete part is pretty standard: just refer to the abstract part you defined previously, make sure +you use for the <<>> elements (anything else is not interoperable), pick a +<<>> (in this case <<>>, but any URI will do), and determine the +<<>> URL where you want request to come in (in this case <<>>): + ++------------------------------------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ++------------------------------------- + + This is the final WSDL. We will describe how to implement the resulting schema and WSDL in the next chapter. \ No newline at end of file diff --git a/src/site/site.xml b/src/site/site.xml index e8bbab20..e2b05951 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -12,6 +12,7 @@ +