From 1ffa706f303c4698b9a03739e2fb8fa961501aa3 Mon Sep 17 00:00:00 2001 From: Rick Evans Date: Wed, 23 May 2007 20:37:09 +0000 Subject: [PATCH] [SWS-120] [SWS-125] Documentation corrections. --- src/docbkx/client.xml | 12 ++-- src/docbkx/common.xml | 65 ++++++++--------- src/docbkx/index.xml | 8 +-- src/docbkx/preface.xml | 6 +- src/docbkx/server.xml | 111 ++++++++++++++++-------------- src/docbkx/tutorial.xml | 38 +++++----- src/docbkx/what-is-spring-ws.xml | 16 +++-- src/docbkx/why-contract-first.xml | 22 +++--- 8 files changed, 143 insertions(+), 135 deletions(-) diff --git a/src/docbkx/client.xml b/src/docbkx/client.xml index a9cf44b6..1aeb134b 100644 --- a/src/docbkx/client.xml +++ b/src/docbkx/client.xml @@ -7,14 +7,14 @@ Introduction Spring-WS provides a client-side Web service API that allows for consistent, XML-driven access to Web - services. It also allows for use of marshallers and unmarshallers. + services. It also allows for the use of marshallers and unmarshallers. The package org.springframework.ws.client.core provides the core functionality for using the client-side access API. It contains template classes that simplifies the use of Web services, much like the JdbcTemplate does for JDBC. The design principle common to Spring template classes is to provide helper methods to perform common operations and for more sophisticated usage, delegate - the essence of the processing task to user implemented callback interfaces. The Web service template + to user implemented callback interfaces. The Web service template follows the same design. The classes offer various convenience methods for the sending and receiving of XML messages, marshalling objects to XML before sending, and allows for multiple transports, @@ -82,6 +82,7 @@ import org.springframework.ws.transport.WebServiceMessageSender; public class WebServiceClient { private static final String MESSAGE = "Hello Web Service World"; + private WebServiceTemplate webServiceTemplate = new WebServiceTemplate(); public void setDefaultUri(String defaultUri) { @@ -95,9 +96,6 @@ public class WebServiceClient { } }]]> - - Here is the corresponding configuration: - @@ -121,7 +119,7 @@ public class WebServiceClient { Marshalling, sending, receiving, and unmarshalling In order to facilitate the sending of plain Java objects, the WebServiceTemplate - has a send methods that take an object as an argument for a message's data content. + has a number of send methods that take an object as an argument for a message's data content. The method marshalSendAndReceive in WebServiceTemplate delegates the conversion of the request object to XML to a Marshaller, and the conversion of the response XML to an object to an Unmarshaller. @@ -138,7 +136,7 @@ public class WebServiceClient { WebServiceMessageCallback - To accommodate the setting of a SOAP headers, and other settings on the message, the + To accommodate the setting of SOAP headers, and other settings on the message, the WebServiceMessageCallback interface gives you access to the message after it has been created, but before it is sent. The example below demonstrates how to set the SOAP Action header on a message that is created by marshalling an object. diff --git a/src/docbkx/common.xml b/src/docbkx/common.xml index 32eaa7ab..34403f13 100644 --- a/src/docbkx/common.xml +++ b/src/docbkx/common.xml @@ -6,7 +6,7 @@ In this chapter, we will explore the the components which are shared between client- and server side Spring-WS development. These interfaces and classes represent the building blocks of Spring-WS, so - it's important to understand what they do, even if you do not use them directly. + it is important to understand what they do, even if you do not use them directly.
Web service messages @@ -123,7 +123,7 @@ To increase reading performance on the AxiomSoapMessageFactory, you can set the payloadCaching property to false (default is true). - This this will read the contents of the SOAP body directly from the stream. + This will read the contents of the SOAP body directly from the stream. When this setting is enabled, the payload can only be read once. This means that you have to make sure that any preprocessing of the message does not consume it. @@ -139,8 +139,9 @@
<interfacename>MessageContext</interfacename> - 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 + 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. @@ -149,8 +150,8 @@ messages. On the client-side, the message context is created by the WebServiceTemplate. - On the server-side, the message context is read from the transport-specific input stream. In HTTP, - it is read from the HttpServletRequest and the response is written back + On the server-side, the message context is read from the transport-specific input stream. + For example, in HTTP, it is read from the HttpServletRequest and the response is written back to the HttpServletResponse.
@@ -158,7 +159,8 @@
Handling XML With XPath - One of the best ways to handle XML is to use XPath. Quoting , item 35: + One of the best ways to handle XML is to use XPath. + Quoting , item 35:
@@ -173,14 +175,14 @@ Elliotte Rusty Harold
- + Spring Web Services has two ways to use XPath within your application: the faster XPathExpression or the more flexible XPathTemplate.
<interfacename>XPathExpression</interfacename> - The XPathExpression is an abstraction over a compiled XPath expressions, + The XPathExpression is an abstraction over a compiled XPath expression, such as the Java 5 javax.xml.xpath.XPathExpression, or the Jaxen XPath class. To construct an expression in an application context, there is the @@ -189,7 +191,7 @@ + http://www.springframework.org/schema/beans/spring-beans-2.0.xsd"> @@ -202,14 +204,14 @@ ]]> The expression above does not use namespaces, but we could set those using the - namespaces property of the factory bean. The expression can be used in the code - as follows: + namespaces property of the factory bean. The expression + can be used in the code as follows: // do something with list of Contact objects Similar to mapping rows in Spring JDBC's RowMapper, each result node is @@ -271,12 +273,13 @@ public class MyXPathClass { public void doXPath(Source source) { String name = template.evaluateAsString("/Contacts/Contact/Name", request); - // do something with name + ]]>// do something with name - Of course, the template could have been injected with a constructor argument or a setter. + Of course, the template could have been injected with a + constructor argument or a setter.
diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 2f4dce50..a3a55a1b 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -37,8 +37,8 @@ This first part of the reference documentation gives an overview of Spring Web Services, and the - underlying concepts. We will introduce Spring-WS, and explain the concepts behind contract-first - Web service development. + underlying concepts. Spring-WS is introduced, and the concepts behind contract-first + Web service development are explained. @@ -49,8 +49,8 @@ Reference - This part of the reference documentation gives an in-depth look into the various pieces that make up - Spring Web Services. + This part of the reference documentation gives an in-depth look into the various components that + comprise Spring Web Services. It consists of a chapter which discusses the parts common to both client- and server-side, a chapter about writing server-side Web services, about using Web services on the client-side, using WS-Security, and the flexible Object/XML mapping. diff --git a/src/docbkx/preface.xml b/src/docbkx/preface.xml index ec8b9db4..3400007f 100644 --- a/src/docbkx/preface.xml +++ b/src/docbkx/preface.xml @@ -5,9 +5,9 @@ Preface In the current age of Service Oriented Architectures, more and more people are using Web Services to - connect previously unconnected systems. Initially, Web services where considered to be just another way to do - a Remote Procedure Call (RPC). Over time, however, people found out that there is a big difference - between RPC and Web services. Especially when interoperability with other platforms is important, it is often + connect previously unconnected systems. Initially, Web services were considered to be just another way to do + a Remote Procedure Call (RPC). Over time however, people found out that there is a big difference + between RPCs and Web services. Especially when interoperability with other platforms is important, it is often better to send encapsulated XML documents, containing all the data necessary to process the request. Conceptually, XML-based Web services are better off being compared to message queues rather than remoting solutions. diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index b8061014..dd236b7c 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -6,25 +6,26 @@
Introduction - Spring Web Services's server-side support in designed around a MessageDispatcher - that dispatches incoming messages to endpoints, with configurable endpoint mappings, response generation, - and endpoint interception. + Spring-WS's server-side support is designed around a + MessageDispatcher that dispatches incoming + messages to endpoints, with configurable endpoint mappings, response + generation, and endpoint interception. The simplest endpoint is a PayloadEndpoint, just offering a - Source invoke(Source request) method. This interface can be implemented for creating an - endpoint, but you will prefer the included implementation hierarchy, consisting of, for example + Source invoke(Source request) method. You are of course free to + implement this interface directly, but you will probably prefer to extend one of + the included abstract implementations such as AbstractDomPayloadEndpoint, AbstractSaxPayloadEndpoint, and - of course AbstractMarshallingPayloadEndpoint. Application endpoints will typically - be subclasses of those. + AbstractMarshallingPayloadEndpoint. Alternatively, there is a endpoint development that uses Java 5 annotations, such as @Endpoint for marking a POJO as endpoint, and marking a method with @PayloadRoot or @SoapAction. - - - 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 techniques (JAXB, Castor, XMLBeans, JiBX, or XStream) to convert - the XML to objects and vice-versa. + + + 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 techniques (JAXB, Castor, XMLBeans, JiBX, or XStream) to convert + the XML to objects and vice-versa.
@@ -33,7 +34,7 @@ The server-side of Spring-WS is designed around a central class that dispatches incoming XML messages to endpoints. Spring-WS's MessageDispatcher 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'sDispatcherServlet, the + In a way, the message dispatcher resembles Spring's DispatcherServlet, the Front Controller used in Spring Web MVC. @@ -55,20 +56,23 @@ When a MessageDispatcher is set up for use and a request comes in for that specific dispatcher, said MessageDispatcher starts processing the request. The list below describes the complete process a request goes through when handled by a - MessageDispatcher: + MessageDispatcher: - An appropriate endpoint is searched for. If an endpoint is found, the invocation chain associated - with the endpoint (preprocessors, postprocessors, and endpoints) will be executed in order to create + An appropriate endpoint is searched for using the configured + EndpointMapping(s). If an endpoint is found, + the invocation chain associated with the endpoint (preprocessors, + postprocessors, and endpoints) will be executed in order to create a response. - An appropriate adapter is searched for the endpoint. The MessageDispatcher - delegates to this adapter to invoke the endpoint. + An appropriate adapter is searched for the endpoint. The + MessageDispatcher delegates to this adapter + to invoke the endpoint. @@ -107,7 +111,7 @@ The MessageDispatcherServlet is a standard Servlet which conveniently extends from the standard Spring Web DispatcherServlet, and wraps a MessageDispatcher. As such, it combines the attributes of these into one: - as a MessageDispatcher, if follows the same request handling flow as described + as a MessageDispatcher, it follows the same request handling flow as described in the previous section. As a servlet, the MessageDispatcherServlet is configured in the web.xml of @@ -129,11 +133,13 @@ /* + ]]><!-- ... -->]]> In the example above, all requests will be handled by the 'spring-ws' MessageDispatcherServlet. 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 + Services; the various endpoint and other beans used by the Spring-WS framework also need to be configured. @@ -149,21 +155,21 @@ Endpoints Endpoints are the central concept in Spring-WS's server-side support. Endpoints provide access to the - application behavior which is typically defined by a business service interface. Endpoint interpret the XML - request message and uses that input to invoke a method on the business service. The result of that service + application behavior which is typically defined by a business service interface. An endpoint interprets the XML + request message and uses that input to invoke a method on the business service (typically). The result of that service invocation is represented as a response message. Spring-WS has a wide variety of endpoints, using various ways to handle the XML message, and to create a response. - The basis for most endpoint in Spring Web Services is the + The basis for most endpoints in Spring Web Services is the org.springframework.ws.server.endpoint.PayloadEndpoint interface, the source code of which is listed below. /** * Invokes an operation. - */ + */ @@ -176,11 +182,11 @@ most basic responsibility required of every endpoint; namely handling a request and returning a response. - Alternatively, there is the MessageEndpoint, which operated on a + Alternatively, there is the MessageEndpoint, which operates on a whole MessageContext rather than just the payload. Typically, your code should only not be dependent on messages, because the payload should - contain the interesting information. Only when it is necessary to perform actions on the mesage a whole, - such as adding a SOAP header, get an attachment, etc., should you need to cast to implement + contain the interesting information. Only when it is necessary to perform actions on the mesage as a whole, + such as adding a SOAP header, get an attachment, and so forth, should you need to implement MessageEndpoint, though these actions are usually performed in a endpoint interceptor. @@ -192,7 +198,7 @@ org.w3c.dom.Element and related classes to handle the request, and create the response. When using the AbstractDomPayloadEndpoint as the baseclass for your endpoints you only have to override the invokeInternal(Element, Document) - method, implement your logic, and return an Element if we want a + method, implement your logic, and return an Element if you want a response. Here is a short example consisting of a class and a declaration in the application context. ]]> - The above class and the declaration in the application context is all you need besides setting up a + The above class and the declaration in the application context is all you need besides setting up an endpoint mapping (see the section entitled ) to get this very simple endpoint working. The SOAP message handled by this endpoint will look something like: @@ -255,8 +261,8 @@ public class SampleEndpoint extends AbstractDomPayloadEndpoint { AbstractJDomPayloadEndpoint allows you to use JDOM, and the AbstractXomPayloadEndpoint uses XOM to handle the XML. All of these endpoints have an invokeInternal method similar to above. - Also, consider to use Spring-WS's XPath support to extract the information you need out of the payload, - see . + Also, consider using Spring-WS's XPath support to extract the information you need out of the payload. + (See the section entitled for details.)
@@ -314,7 +320,7 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint - + ]]><!-- Other beans, such as the endpoint mapping -->]]> In this sample, we configure a Jaxb2Marshaller for the @@ -516,16 +522,16 @@ public class AnnotationOrderEndpoint { interceptors that are applied to the request and response. When a request comes in, the MessageDispatcher will hand it over to the endpoint mapping to let it inspect the request and come up with an appropriate EndpointInvocationChain. Then - the MessageDispatcher will invoce the endpoint and any interceptors in the chain. + the MessageDispatcher will invoke the endpoint and any interceptors in the chain. The concept of configurable endpoint mappings that can optionally contain interceptors (which can manipulate the request or the response, or both) is extremely powerful. A lot of supporting functionality can be built - into custom EndpointMappings. Think of a custom endpoint mapping that + into custom EndpointMappings. For example, there could be a custom endpoint mapping that chooses an endpoint not only based on the contents of a message, but also a specific SOAP headers. - Most endpoint mappings inherit from the AbstractEndpointMapping, which offers a + Most endpoint mappings inherit from the AbstractEndpointMapping, which offers an interceptors property, which is the list of interceptors to use. EndpointInterceptors are discussed in . Additionally, there is the @@ -565,9 +571,7 @@ public class AnnotationOrderEndpoint { local part. Thus, the endpoint mapping above routes requests for which have a payload root element with namespace http://samples and local part orderRequest to the 'getOrderEndpoint'. Requests with a local part order will - be routed to the 'createController'. As a result of this mapping, the SOAP message - shown above will be mapped to the - getOrderEndpoint. + be routed to the 'createOrderEndpoint'.
@@ -607,9 +611,9 @@ public class AnnotationOrderEndpoint {
<classname>MethodEndpointMapping</classname> - As explain in , the @Endpoint model + As explained in , the @Endpoint style allows you to handle multiple requests in one endpoint class. This is the responsibility of the - MethodEndpointMapping. Similar to the endpoint mapping described above, the + MethodEndpointMapping. Similar to the endpoint mapping described above, this mapping determines which method is to be invoked for an incoming request message. @@ -643,17 +647,18 @@ public class AnnotationOrderEndpoint { Interceptors located in the endpoint mapping must implement EndpointInterceptor from the org.springframework.ws.server package. This interface defines three methods, one that - can be used for handling the request message has been determined, before the actual + can be used for handling the request message has been determined before the actual endpoint will be executed, one that can be used for handling a normal response message, and one that can be used for handling fault messages, both of which will be called after the endpoint is executed. These three methods should provide enough flexibility to do all kinds of pre- and post-processing. - The handleRequest(..) methods on the interceptor returns a boolean value. You - can use this method to break or continue the processing of the invocation chain. When this method + The handleRequest(..) method on the interceptor returns a boolean value. You + can use this method to interrupt or continue the processing of the invocation chain. When this method returns true, the endpoint execution chain will continue, when it returns - false, the MessageDispatcher assumes the interceptor itself + false, the MessageDispatcher interprets this to mean that + the interceptor itself has taken care of things and does not continue executing the other interceptors and the actual endoint in the invocation chain. The handleResponse(..) and handleFault(..) methods also have a boolean return value. When these methods @@ -697,7 +702,7 @@ public class AnnotationOrderEndpoint { Both of these interceptors have two properties: logRequest and logResponse, which can be set to false to disable logging - for either request of response messages. + for either request or response messages.
@@ -737,8 +742,8 @@ public class AnnotationOrderEndpoint { To transform the payload to another XML format, Spring Web Services offers the PayloadTransformingInterceptor. This endpoint interceptor is based on XSLT - stylesheets, and is especially useful when supporting with multiple version of a Web service: - you simply can transform the older message format to the new format. + stylesheets, and is especially useful when supporting multiple versions of a Web service: + you simply can transform the older message format to the newer format. Here is an example to use the PayloadTransformingInterceptor: Endpoint exception resolvers are automatically picked up by the MessageDispatcher, so - you don't have to configure them explicitely. + you don't have to configure them explicitly. Besides implementing the EndpointExceptionResolver interface, which is only a matter of implementing the resolveException(MessageContext, endpoint, Exception) method, you may also use one of the default implementations. - The simples implementation is the SimpleSoapExceptionResolver, which simply + The simplest implementation is the SimpleSoapExceptionResolver, which simply always creates a SOAP 1.1 Server or SOAP 1.2 Receiver Fault, and uses the exception message as the fault string. diff --git a/src/docbkx/tutorial.xml b/src/docbkx/tutorial.xml index 98e1289e..b1bbe7c5 100644 --- a/src/docbkx/tutorial.xml +++ b/src/docbkx/tutorial.xml @@ -82,18 +82,18 @@ ]]> - The order of the two element does not matter: Employee could have been the first + The order of the two elements does not matter: Employee 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 data-driven approach.
- Data Constract + Data Contract Now that we have seen some examples of the XML data that we will use, it makes sense to formalize this into a schema. This data contract defines the message format we accept. - Basically, there are four different ways of defining such a contract for XML: + There are four different ways of defining such a contract for XML: DTDs @@ -152,7 +152,7 @@ <xs:element name="LastName" type="xs:NCName"/> </xs:schema> - The generated schema can obviously be improved. The first thing to notice is that every type has a root-level + This generated schema obviously can be improved. The first thing to notice is that every type has a root-level element declaration. 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 HolidayRequest. By removing the wrapping element tags (thus keeping the types), and inlining the results, we can accomplish this. @@ -263,7 +263,7 @@ - We store this file with as hr.xsd. + We store this file as hr.xsd.
@@ -450,7 +450,7 @@ The following command creates a Maven2 web application project for us, using the Spring-WS archetype - (i.e. project template) + (that is, project template) mvn archetype:create -DarchetypeGroupId=org.springframework.ws \ -DarchetypeArtifactId=spring-ws-archetype \ @@ -462,12 +462,14 @@ This command will create a new directory called holidayService. In this directory, there is a src/main/webapp directory, which will contain the root of the WAR file. You will find the standard web application deployment descriptor WEB-INF/web.xml here, - which defines a Spring-WS MessageDispatcherServlet, and maps all incoming requests + which defines a Spring-WS MessageDispatcherServlet and maps all incoming requests to this servlet: MyCompany HR Holiday Service @@ -565,10 +567,9 @@ public class HolidayEndpoint extends AbstractJDomPayloadEndpoint { The HolidayEndpoint requires the HumanResourceService business service to operate, so we - use the constructor to inject it. - Next, we set up XPath expressions + use the constructor to inject it. Next, we set up XPath expressions using the JDOM API. There are three expressions: //hr:StartDate for - extracting the >StartDate< text value, + extracting the <StartDate> text value, //hr:EndDate for extracting the end date and concat(//hr:FirstName,' ',//hr:LastName) for extracting and concatenating the names of the employee. @@ -634,7 +635,7 @@ public class HolidayEndpoint extends AbstractJDomPayloadEndpoint { ]]> - Here's how we would wire up these classes in our spring-ws-servlet.xml + Here is how we would wire up these classes in our spring-ws-servlet.xml application context: http://mycompany.com/hr/schemas and the HolidayRequest local name, it will be routed to the holidayEndpoint. - It also adds a PayloadInterceptor, - which dumps incoming and outgoing messages to the log. + It also adds a PayloadLoggingInterceptor, + that dumps incoming and outgoing messages to the log.
@@ -683,7 +684,7 @@ public class HolidayEndpoint extends AbstractJDomPayloadEndpoint { Finally, we need to publish the WSDL. As stated in , we don't need to write a WSDL ourselves; Spring-WS can generate one for us based on some conventions. - Here's how we define the generation: + Here is how we define the generation: @@ -746,9 +747,8 @@ public class HolidayEndpoint extends AbstractJDomPayloadEndpoint { You can create a WAR file using mvn install. If you deploy the application, and point your browser at this location, you will - see the generated WSDL. - This WSDL is ready to be used by clients, such as soapUI, or - other SOAP frameworks. + see the generated WSDL. This WSDL is ready to be used by clients, such as + soapUI, or other SOAP frameworks. diff --git a/src/docbkx/what-is-spring-ws.xml b/src/docbkx/what-is-spring-ws.xml index 815bad00..1af42604 100644 --- a/src/docbkx/what-is-spring-ws.xml +++ b/src/docbkx/what-is-spring-ws.xml @@ -23,14 +23,14 @@ Powerful mappings - You can distribute incoming XML request to any object, depending on message payload, SOAP Action header, + You can distribute incoming XML requests to any object, depending on message payload, SOAP Action header, or an XPath expression. XML API support - Incoming XML messages can be handled in standard JAXP APIs such as DOM, SAX, and StAX, but also JDOM, + Incoming XML messages can be handled not only with standard JAXP APIs such as DOM, SAX, and StAX, but also JDOM, dom4j, XOM, or even marshalling technologies. @@ -45,7 +45,7 @@ Reuses your Spring expertise - Spring-WS uses Spring application contexts for all configuration, which should help Spring developers + Spring-WS uses Spring application contexts for all configuration, which should help Spring developers get up-to-speed nice and quickly. Also, the architecture of Spring-WS resembles that of Spring-MVC. @@ -82,21 +82,23 @@ Spring Web Services runs within a standard Java 1.3 Runtime Environment. It also supports Java 5.0, although the Java types which are specific to this release are packaged in a separate modules with the suffix "tiger" in their JAR filename. + + Spring-WS consists of a number of modules, which are described in the remainder of this section. The XML module (spring-xml.jar) contains various XML support classes for Spring Web - Services. This module is mainly targeted at the Spring-WS framework itself, and not a Web service + Services. This module is mainly intended for the Spring-WS framework itself, and not a Web service developers. The Core package (spring-ws-core.jar and spring-ws-core-tiger.jar) - is the central part of the Web services - functionality. It provides the central + is the central part of the Spring's Web services functionality. + It provides the central WebServiceMessage and SoapMessage interfaces, the server-side framework, with powerful message dispatching, and the various support classes for implementing Web service @@ -122,7 +124,7 @@ - The following figure illustrates the modules, and the dependencies between them. Arrows indicate + The following figure illustrates the Spring-WS modules and the dependencies between them. Arrows indicate dependencies, i.e. Spring-WS Core depends on Spring-XML and Spring-OXM. diff --git a/src/docbkx/why-contract-first.xml b/src/docbkx/why-contract-first.xml index f83f99c9..1790d280 100644 --- a/src/docbkx/why-contract-first.xml +++ b/src/docbkx/why-contract-first.xml @@ -22,7 +22,7 @@ - Spring-WS only supports the contract-first development style. This section explains why. + Spring-WS only supports the contract-first development style, and this section explains why.
@@ -32,7 +32,7 @@ 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 + converting all Java properties and fields to sub-elements or attributes. However, things are not as 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 @@ -42,7 +42,7 @@ 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 + that subclass. In XSD, you can extend a data type by restricting it: that is, constraining the valid values for the elements and attributes. For instance, consider the following example: @@ -96,8 +96,8 @@ public Map getFlights() { ]]> 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 + either a java.util.Date or java.util.Calendar. However, + both of these classes actually describe times, rather than dates. So, we will actually end up sending data that represents the fourth of April 2007 at midnight (2007-04-04T00:00:00), which is not the same as 2007-04-04. @@ -151,7 +151,7 @@ public class Passenger { ]]> 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 + to validate this structure. Another issue is that the standard way to use these references in SOAP (RPC/encoded) has been deprecated in favor of document/literal (see WS-I Basic Profile). @@ -199,7 +199,7 @@ public class Passenger { When Java is automatically transformed into XML, there is no way to be sure as to what is sent across the wire. An object might reference another object, which refers to another, etc. In the end, half of the objects on the heap in your virtual machine might be converted into XML, - which will result in a slow service. + which will result in slow response times. When using contract-first, you explicitly describe what XML is sent where, thus making sure that it is @@ -209,7 +209,7 @@ public class Passenger {
Reusability - Defining your schema in a separate file allows you to reuse that file in different scenario's. If you + Defining your schema in a separate file allows you to reuse that file in different scenarios. If you define an AirportCode in a file called airline.xsd, like so: ]]> - You can reuse this definition in other schema's, or even WSDL files, using an + You can reuse this definition in other schemas, or even WSDL files, using an import statement.
@@ -227,7 +227,7 @@ public class Passenger { Versioning Even though a contract must remain constant for as long as possible, they do need - to be changed sometimes. In Java, this typically result in a new Java interface, such as + to be changed sometimes. In Java, this typically results in a new Java interface, such as AirlineService2, and a (new) implementation of that interface. Of course, the old service must be kept around, because there might be clients who have not migrated yet. @@ -235,7 +235,7 @@ public class Passenger { If using contract-first, we can have a looser coupling between contract and implementation. Such a looser coupling allows us to implement both versions of the contract in one class. We could, for - instance, use an XSLT to convert any "old-style" messages to the "new-style" messages. + instance, use an XSLT stylesheet to convert any "old-style" messages to the "new-style" messages.