From 37e18649396db74cd4454301e7e851baff7f4e59 Mon Sep 17 00:00:00 2001 From: Arjen Poutsma Date: Mon, 20 Dec 2010 10:40:27 +0000 Subject: [PATCH] Documentation --- src/docbkx/common.xml | 12 ++- src/docbkx/server.xml | 217 ++++++++++++++++++++++++++++++++-------- src/docbkx/tutorial.xml | 73 +++++++------- 3 files changed, 218 insertions(+), 84 deletions(-) diff --git a/src/docbkx/common.xml b/src/docbkx/common.xml index 83e054c2..3abee3ba 100644 --- a/src/docbkx/common.xml +++ b/src/docbkx/common.xml @@ -76,12 +76,14 @@ The SoapMessage is a subclass of WebServiceMessage. It contains SOAP-specific methods, such as getting - SOAP Headers, SOAP Faults, etc. Generally, your code should not be dependent on - SoapMessage, because the content of the SOAP Body can be obtained via + SOAP Headers, SOAP Faults, etc. + Generally, your code should not be dependent on SoapMessage, because + the content of the SOAP Body (the payload of the message) can be obtained via getPayloadSource() and getPayloadResult() in the - WebServiceMessage. Only when it is necessary to perform SOAP-specific - actions, such as adding a header, get an attachment, etc., should you need to cast - WebServiceMessage to SoapMessage. + WebServiceMessage. + Only when it is necessary to perform SOAP-specific actions, such as adding a header, getting an + attachment, etc., should you need to cast WebServiceMessage to + SoapMessage.
diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index daa03262..dbbcc626 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -10,15 +10,12 @@ MessageDispatcher that dispatches incoming messages to endpoints, with configurable endpoint mappings, response generation, and endpoint interception. - The simplest endpoint is a PayloadEndpoint, which just offers the - 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 - 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. + Endpoints are typically annotated with the @Endpoint annotation, and have + one or more handling methods. + These methods handle incoming XML request messages by inspecting parts of the message (typically the + payload), and create some sort of response. + You annotate the method with another annotation, typically @PayloadRoot, + to indicate what sort of messages it can handle. Spring-WS's XML handling is extremely flexible. An endpoint can choose from @@ -62,8 +59,8 @@ 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. + If an endpoint is found, the invocation chain associated with the endpoint (pre-processors, + post-processors, and endpoints) will be executed in order to create a response. @@ -185,7 +182,7 @@ - Another cool feature of the MessageDispatcherServlet (or more correctly the + Another nice feature of the MessageDispatcherServlet (or more correctly the WsdlDefinitionHandlerAdapter) is that it is able to transform the value of the 'location' of all the WSDL that it exposes to reflect the URL of the incoming request. @@ -257,9 +254,6 @@ - - This bean wrap the messages.xsd (which imports types.xsd), and inlines them as a one. - /WEB-INF/xsds/Orders.xsd @@ -281,7 +275,7 @@ Refer to the class-level Javadoc of these classes to see how you can extend this mechanism, if necessary. - + Even though it can be quite handy to create the WSDL at runtime from your XSDs, there are a couple of drawbacks to this approach. First off, though we try to keep the WSDL generation @@ -296,7 +290,7 @@ SimpleWsdl11Definition. This is the only way to be really sure that the WSDL does not change over time. - +
@@ -591,36 +585,123 @@ 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 endpoints in Spring Web Services is the - org.springframework.ws.server.endpoint.PayloadEndpoint interface, the source - code of which is listed below. - + You create an endpoint by annotating a class with the @Endpoint annotation. + In the class, you define one or more methods that handle the incoming XML request, by using a wide + variety of parameter types (such as DOM elements, JAXB2 objects, etc). + You indicate the sort of messages a method can handle by using another annotation (typically + @PayloadRoot). + + + Consider the following sample endpoint: + + + + + + + + + + + + /** - * Invokes an operation. - */ - - As you can see, the PayloadEndpoint interface defines a single method that - is invoked with the XML payload of a request (typically the contents of the SOAP Body, see - ). The returned Source, if any, is stored in the - response XML message. While the PayloadEndpoint interface is quite abstract, - Spring-WS offers a lot of endpoint implementations out of the box that already contain a lot of the - functionality you might need. The PayloadEndpoint interface just defines the - most basic responsibility required of every endpoint; namely handling a request and returning a response. + + + + The class is annotated with @Endpoint, marking it as a + Spring-WS endpoint. + + + + + The constructor is marked with @Autowired, so that the + OrderService business service is injected into this endpoint. + + + + + The order method takes a Element + as a parameter, annotated with @RequestPayload. + This means that the payload of the message is passed on this method as a DOM element. + The method has a void return type, indicating that no response message + is sent. + + + For more information about endpoint methods, refer to + . + + + + + The getOrder method takes a OrderRequest + as a parameter, annotated with @RequestPayload as well. + This parameter is a JAXB2-supported object (it is annotated with + @XmlRootElement). + This means that the payload of the message is passed on to this method as a unmarshalled + object. + The method is also annotated with @ResponseBody, + indicating that the return value (the Order) is used as the payload + of the response message. + + + For more information about endpoint methods, refer to + . + + + + + The two handling methods of this endpoint are marked with + @PayloadRoot, indicating what sort of request messages + can be handled by the method: the getOrder method + will be invoked for requests with a orderRequest local name and a + http://samples namespace URI; the order method + for requests with a order local name. + + + For more information about @PayloadRoot, refer to + . + + + + - Alternatively, there is the MessageEndpoint, which operates on a - whole MessageContext rather than just - the payload. Typically, your code should not be dependent on messages, because the payload should - contain the information of interest. Only when it is necessary to perform actions on the message 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 an - endpoint interceptor. + In the next couple of sections, a more elaborate description of the @Endpoint + programming model is given. @@ -631,10 +712,58 @@ Spring Reference documentation. - Note that all abstract base classes provided in Spring-WS (like AbstractDomPayloadEndpoint etc) are - thread safe. + Note that all abstract base classes provided in Spring-WS are thread safe, unless otherwise indicated + in the class-level Javadoc. +
+ <interfacename>@Endpoint</interfacename> handling methods + + In order for an endpoint to actually handle incoming XML messages, it needs to have one or more handling + methods. + Handling methods can take wide range of parameters and return types, but typically they have one + parameter that will contain the message payload, and they return the payload of the response message + (if any). + You will learn which parameter and return types are supported in this section. + + + To indicate what sort of messages a method can handle, the method is typically annotated with either the + @PayloadRoot or @SoapAction annotation. + You will learn more about these annotations in . + + + Here is an example of a handling method: + @PayloadRoot(localPart = "order", namespace = "http://samples") +public void order(@RequestPayload Element orderElement) { + Order order = createOrder(orderElement); + orderService.createOrder(order); +} + The order method takes a Element + as a parameter, annotated with @RequestPayload. + This means that the payload of the message is passed on this method as a DOM element. + The method has a void return type, indicating that no response message + is sent. + +
+ Handling method parameters + + The handling method typically has one or more parameters that refer to various parts of the + incoming XML message. + Most commonly, the handling method will have a single parameter that will map to the payload of + the message, but it is also possible to map to other parts of the message, such as a SOAP header. + This section will describe the parameters you can use in your handling method signatures. + + + One + +
+
+ Handling method return types + + + +
+
<classname>AbstractDomPayloadEndpoint</classname> and other DOM endpoints diff --git a/src/docbkx/tutorial.xml b/src/docbkx/tutorial.xml index e3fe89cf..9aa1b3b3 100644 --- a/src/docbkx/tutorial.xml +++ b/src/docbkx/tutorial.xml @@ -13,7 +13,7 @@ and this tutorial will help 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 . + focuses on implementing this contract using Spring-WS . The most important thing when doing contract-first Web service development is @@ -678,7 +678,7 @@ public class HolidayEndpoint { org.springframework.ws spring-ws-core - 2.0.0 + 2.0.0-RC2 jdom @@ -694,14 +694,21 @@ public class HolidayEndpoint { Here is how we would configure these classes in our spring-ws-servlet.xml Spring XML configuration file, by using component scanning. + We also instruct Spring-WS to use annotation-driven endpoints, with the + <sws:annotation-driven> element. - + http://www.springframework.org/schema/web-services http://www.springframework.org/schema/web-services/web-services-2.0.xsd + http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> + + ]]>
@@ -720,6 +727,8 @@ public class HolidayEndpoint { http://mycompany.com/hr/schemas and the HolidayRequest local name, it will be routed to the handleHolidayRequest method. + By using the <sws:annotation-driven> element in our configuration, we + enable the detection of the @PayloadRoot annotations. It is possible (and quite common) to have multiple, related handling methods in an endpoint, each of them handling different XML messages. @@ -739,43 +748,29 @@ public class HolidayEndpoint { - - - - - - - + + + + - - - - - - - - - -]]> + + +]]> - The bean id determines the URL where the WSDL can be retrieved. In this case, the bean id is - holiday, which means that the WSDL can be retrieved as - holiday.wsdl in the servlet context. The full URL will typically be - http://localhost:8080/holidayService/holiday.wsdl. - - - - - The schema property refers to the human resource schema we defined in - , wrapped in a SimpleXsdSchema. We simply - placed the schema in the WEB-INF directory of the application. + The id determines the URL where the WSDL can be retrieved. + In this case, the id is holiday, which means that the WSDL can be retrieved + as holiday.wsdl in the servlet context. + The full URL will typically be http://localhost:8080/holidayService/holiday.wsdl. - Next, we define the WSDL port type to be HumanResource. + Next, we set the WSDL port type to be HumanResource. @@ -798,8 +793,16 @@ public class HolidayEndpoint { - Finally, we define the target namespace for the WSDL definition itself. Setting these - is not required. If not set, we give the WSDL the same namespace as the schema. + We define the target namespace for the WSDL definition itself. + Setting this attribute is not required. + If not set, the WSDL will have the same namespace as the XSD schema. + + + + + The xsd element refers to the human resource schema we defined in + . + We simply placed the schema in the WEB-INF directory of the application.