diff --git a/src/docbkx/client.xml b/src/docbkx/client.xml index 02ee6b2b..88afc677 100644 --- a/src/docbkx/client.xml +++ b/src/docbkx/client.xml @@ -7,106 +7,63 @@ 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 use of marshallers and unmarshallers. - The package - org.springframework.ws.client.core - provides the core functionality for using + 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 + 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 - 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, + 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,
Using the client-side API
- - <classname>WebServiceTemplate</classname> - + <classname>WebServiceTemplate</classname> - The - WebServiceTemplate - is the core class for client-side Web service access in - Spring-WS. It contains methods for sending - Source - objects, and receiving response - messages as either - Source - or - Result - . Additionally, it can + The WebServiceTemplate is the core class for client-side Web service access in + Spring-WS. It contains methods for sending Source objects, and receiving response + messages as either Source or Result. Additionally, it can marshal objects to XML before sending them across a transport, and unmarshal the response XML into an object again.
Transports - The - WebServiceTemplate - requires a reference to a - MessageSender - . The message sender is responsible for sending the XML message - across a transport layer. + The WebServiceTemplate requires a reference to a + MessageSender. The message sender is responsible for sending the XML + message across a transport layer. - There are two implementations of the - MessageSender - interface for sending messages - via HTTP. The simplest implementation is the - HttpUrlConnectionMessageSender - , - which uses the facilities provided by Java SE itself. The alternative is the - CommonsHttpMessageSender - , which uses the Jakarta Commons HttpClient. Use the - latter if you need more advanced and easy-to-use functionality. Both HTTP message senders require an - URL to be set using the - url - property. + There are two implementations of the MessageSender interface for sending + messages via HTTP. The simplest implementation is the + HttpUrlConnectionMessageSender, which uses the facilities provided by Java + SE itself. The alternative is the CommonsHttpMessageSender, which uses the + Jakarta Commons HttpClient. Use the latter if you need more advanced and easy-to-use functionality. + Both HTTP message senders require an URL to be set using the url property.
Message factories - In addition to a message sender, the - WebServiceTemplate - requires a Web service - message factory. As explained in - - , there are two message factories - for SOAP: - SaajSoapMessageFactory - and - AxiomSoapMessageFactory - . If no message factory is specified, Spring-WS will - use the - SaajSoapMessageFactory - by default. + In addition to a message sender, the WebServiceTemplate requires a Web + service message factory. As explained in , there are two message + factories for SOAP: SaajSoapMessageFactory and + AxiomSoapMessageFactory. If no message factory is specified, Spring-WS will + use the SaajSoapMessageFactory by default.
- Sending and receiving a - <interfacename>WebServiceMessage</interfacename> + <title>Sending and receiving a<interfacename>WebServiceMessage</interfacename> - The - WebServiceTemplate - contains many convenience methods to send and receive - web service messages. There are methods that take and return - Source - and those that return a - Result - . Additionally, there are methods which + The WebServiceTemplate contains many convenience methods to send and receive + web service messages. There are methods that take and return Source + and those that return a Result. Additionally, there are methods which marshal and unmarshal objects to XML. Here is an example that sends a simple XML message to a Web service. @@ -157,51 +114,29 @@ public class WebServiceClient { ]]> This example uses the template to send a hello world message to the web service located at - http://localhost:8080/WebService - , and writes the result to the console. - The - WebServiceTemplate - is injected with the message sender. - A zero argument constructor and - messageFactory - / - messageSender + http://localhost:8080/WebService, and writes the result to the console. The + WebServiceTemplate is injected with the message sender. A zero argument + constructor and messageFactory/messageSender bean properties are provided and can be used for constructing the instance (using a BeanFactory or plain Java code). Alternatively, consider deriving from - Spring-WS's - WebServiceGatewaySupport - convenience base class, which provides + Spring-WS's WebServiceGatewaySupport convenience base class, which provides pre-built bean properties for configuration.
Marshalling, sending, receiving, and unmarshalling - In order to facilitate the sending of plain Java objects, the - WebServiceTemplate + 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. - 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 - . - For more information about marshalling and unmarshaller, refer to - - . + 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. + For more information about marshalling and unmarshaller, refer to . By using the marshallers, you and your application code can focus on the business object that is being sent or received and not be concerned with the details of how it is represented as XML. In order to use the marshalling functionality, you have to set a marshaller and unmarshaller with the - marshaller - / - unmarshaller - properties of the - WebServiceTemplate - . + marshaller/unmarshaller properties of the + WebServiceTemplate.
@@ -210,12 +145,12 @@ public class WebServiceClient { To accommodate the setting of a SOAP headers, and other settings on the message, the - WebServiceMessageCallback - interface gives you access to the message + 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. -