From 8a3a9e21d18f3e93631c79699da185d2e6f4a9f5 Mon Sep 17 00:00:00 2001 From: Arjen Poutsma Date: Fri, 16 Feb 2007 23:51:33 +0000 Subject: [PATCH] Finished client-side docs. --- doc/src/docbkx/client.xml | 132 +++++++++++++++++++++++++++++++++----- doc/src/docbkx/index.xml | 2 +- 2 files changed, 116 insertions(+), 18 deletions(-) diff --git a/doc/src/docbkx/client.xml b/doc/src/docbkx/client.xml index 27dd91ce..c399fb86 100644 --- a/doc/src/docbkx/client.xml +++ b/doc/src/docbkx/client.xml @@ -31,32 +31,130 @@ 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. + + + 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. + +
- Transports + Sending and receiving a <interfacename>WebServiceMessage</interfacename> - The WebServiceTemplate requires a reference to a - MessageSender. The message sender is responsible for sending the XML message - across a transport layer. + 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. + + Helo World"; + private WebServiceTemplate webServiceTemplate = new WebServiceTemplate(); + + public void setMessageFactory(WebServiceMessageFactory messageFactory) { + webServiceTemplate.setMessageFactory(messageFactory); + } + + public void setMessageSender(WebServiceMessageSender messageSender) { + webServiceTemplate.setMessageSender(messageSender); + } + + public void simpleSendAndReceive() throws IOException { + StreamSource source = new StreamSource(new StringReader(MESSAGE)); + StreamResult result = new StreamResult(System.out); + webServiceTemplate.sendAndReceive(source, result); + } + +}]]> + + Here is the corresponding configuration: + + + + + + + + + + + + + +]]> - 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. + 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 factory and 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 + pre-built bean properties for configuration.
- Message factories + Marshalling, sending, receiving, and unmarshalling - 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. + 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 . + 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.
- +
+ <interface>WebServiceMessageCallback</interface> + + To accommodate the setting of a 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. + + +
- + \ No newline at end of file diff --git a/doc/src/docbkx/index.xml b/doc/src/docbkx/index.xml index 6d1511aa..f31e432c 100644 --- a/doc/src/docbkx/index.xml +++ b/doc/src/docbkx/index.xml @@ -37,7 +37,7 @@ Document-driven Web services with Spring-WS This chapter will contain the reference for server-side Spring-WS usage. - +