diff --git a/doc/src/docbkx/index.xml b/doc/src/docbkx/index.xml index 18dd903c..0510f60c 100644 --- a/doc/src/docbkx/index.xml +++ b/doc/src/docbkx/index.xml @@ -32,7 +32,6 @@ - Document-driven Web services with Spring-WS This chapter will contain the reference for server-side Spring-WS usage. diff --git a/doc/src/docbkx/why-contract-first.xml b/doc/src/docbkx/why-contract-first.xml deleted file mode 100644 index d61e8fb7..00000000 --- a/doc/src/docbkx/why-contract-first.xml +++ /dev/null @@ -1,170 +0,0 @@ - - - - Why Contract First? -
- Introduction - - When creating Web services, there are two development styles: Contract Last and - Contract First. When using a contract-last approach, you start with the Java code, and - let the Web service contract (WSDL, see sidebar) be generated from that. - When using contract-first, you start with the WSDL contract, and use Java to implement said contract. - - - What is WSDL? - - WSDL stands for Web Services Description Language. A WSDL file is an XML document that describes a Web - service. It specifies the location of the service and the operations (or methods) the service exposes. - For more information about WSDL, refer to the - WSDL specification, or read the - WSDL tutorial - - - - Spring-WS only supports the contract-first development style. This chapter explains why. - -
-
- Object/XML Impedance Mismatch - - Similar to the field of ORM, where we have an - Object/Relational impedance mismatch, - there is a similar problem when converting Java objects to XML. - At first glance, the O/X mapping problem appears simple: create an XML element for each Java object, - converting all Java properties and fields to sub-elements or attributes. However, things are not so - simple as they appear: there is a fundamental difference between hierarchical languages such as XML - (and especially XSD) and the graph model of Java - Most of the contents in this section was inspired by and - .. - -
- XSD extensions - - In Java, the only way to change the behavior of a class is to subclass it, adding the new behavior to - that subclass. In XSD, you can extend a data type by restricting it: i.e. constraning the valid values - for the elements and attributes. - For instance, consider the following example: - - - -]]> - This type restricts a XSD string by ways of a regular expression, allowing only three upper case - letters. If this type is converted to Java, we will end up with an ordinary - java.lang.String; the regular expression is lost in the conversion process, - because Java does not allow for these sorts of extensions. - -
-
- Unportable types - - One of the most important goals of a Web service is to be interoperable: to support multiple platforms - such as Java, .NET, Python, etc. Because all of these languages have different class libraries, you - must use some common, interlingual format to communicate between them. That format is XML, which is - supported by all of these languages. - - - Because of this conversion, you must make sure that you use portable types in your service - implementation. Consider, for example, a service that returns a - java.util.TreeMap, like so: - Undoubtedly, the contents of this map can be converted into some sort of - XML, but since there is no standard way to describe a map in XML, it will be - proprietary. Also, even if it can be converted to XML, many platforms do not have a data structure - similar to the TreeMap. So when a .NET client accesses your Web service, it - will probably end up with a System.Collections.Hashtable, which has different - semantics. - - - This problem is also present when working on the client side. Consider the following XSD snippet, which - describes a service contract: - - - - - - - -]]> - This contract defines a request that takes an date, which is a XSD datatype representing - a year, month, and day. If we call this service from Java, we will probably use - either a java.util.Data or java.util.Calendar. However, - both of these classes actually describe times, rather than dates. So, we will actually send data that - represents the fourth of April 2007 at midnight (2007-04-04T00:00:00), which is not - the same as 2007-04-04. - -
-
- Cyclic graphs - - Imagine we have the following simple class structure: passengers; - - // getters and setters omitted -} - -public class Passenger { - private String name; - private Flight flight; - - // getters and setters omitted -}]]> - This is a cyclic graph: the Flight refers to the Passenger, - which refers to the Flight again. Cyclic graphs like these are quite common in - Java. If we took a naive approach to converting this to XML, we will end up with something - like: - - - Arjen Poutsma - - - - Arjen Poutsma - - - - Arjen Poutsma - ...]]> - which will take a pretty long time to finish, because there is no stop condition for this loop. - - - One way to solve this problem is to use references to objects that were already marshalled, like - so: - - - Arjen Poutsma - - - ... - -]]> - This solves the recursiveness problem, but introduces new ones. For one, you cannot use an XML validator - to validate this structure. Another issue is that the standard way to use these references in the SOAP - (RPC/encoded) has been deprecated in favor of document/literal. - -
- - These are just a few of the problems when dealing with O/X mapping. It is important to respect these issues - when writing Web services. The best way to respect them is to focus on the XML completely, while using Java - as an implementation language. This is what contract-first is all about. - -
-
- Contract-first is a Best Practice - - - -
- \ No newline at end of file