1 /*
2 * Copyright 2005 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.ws.server.endpoint;
18
19 import javax.xml.parsers.DocumentBuilder;
20 import javax.xml.parsers.DocumentBuilderFactory;
21 import javax.xml.parsers.ParserConfigurationException;
22 import javax.xml.transform.Source;
23 import javax.xml.transform.TransformerException;
24 import javax.xml.transform.dom.DOMResult;
25 import javax.xml.transform.dom.DOMSource;
26
27 import org.w3c.dom.Document;
28 import org.w3c.dom.Element;
29 import org.w3c.dom.Node;
30
31 import org.springframework.xml.transform.TransformerObjectSupport;
32
33 /**
34 * Abstract base class for endpoints that handle the message payload as DOM elements.
35 * <p/>
36 * Offers the message payload as a DOM <code>Element</code>, and allows subclasses to create a response by returning an
37 * <code>Element</code>.
38 * <p/>
39 * An <code>AbstractDomPayloadEndpoint</code> only accept <em>one</em> payload element. Multiple payload elements are
40 * not in accordance with WS-I.
41 *
42 * @author Arjen Poutsma
43 * @author Alef Arendsen
44 * @see #invokeInternal(org.w3c.dom.Element,org.w3c.dom.Document)
45 * @since 1.0.0
46 */
47 public abstract class AbstractDomPayloadEndpoint extends TransformerObjectSupport implements PayloadEndpoint {
48
49 private DocumentBuilderFactory documentBuilderFactory;
50
51 private boolean validating = false;
52
53 private boolean namespaceAware = true;
54
55 private boolean alwaysTransform = false;
56
57 /** Set whether or not the XML parser should be XML namespace aware. Default is <code>true</code>. */
58 public void setNamespaceAware(boolean namespaceAware) {
59 this.namespaceAware = namespaceAware;
60 }
61
62 /** Set if the XML parser should validate the document. Default is <code>false</code>. */
63 public void setValidating(boolean validating) {
64 this.validating = validating;
65 }
66
67 /**
68 * Set if the request {@link Source} should always be transformed into a new {@link DOMResult}.
69 * <p/>
70 * Default is {@code false}, which is faster.
71 */
72 public void setAlwaysTransform(boolean alwaysTransform) {
73 this.alwaysTransform = alwaysTransform;
74 }
75
76 public final Source invoke(Source request) throws Exception {
77 if (documentBuilderFactory == null) {
78 documentBuilderFactory = createDocumentBuilderFactory();
79 }
80 DocumentBuilder documentBuilder = createDocumentBuilder(documentBuilderFactory);
81 Element requestElement = getDocumentElement(request, documentBuilder);
82 Document responseDocument = documentBuilder.newDocument();
83 Element responseElement = invokeInternal(requestElement, responseDocument);
84 return responseElement != null ? new DOMSource(responseElement) : null;
85 }
86
87 /**
88 * Create a <code>DocumentBuilder</code> that this endpoint will use for parsing XML documents. Can be overridden in
89 * subclasses, adding further initialization of the builder.
90 *
91 * @param factory the <code>DocumentBuilderFactory</code> that the DocumentBuilder should be created with
92 * @return the <code>DocumentBuilder</code>
93 * @throws ParserConfigurationException if thrown by JAXP methods
94 */
95 protected DocumentBuilder createDocumentBuilder(DocumentBuilderFactory factory)
96 throws ParserConfigurationException {
97 return factory.newDocumentBuilder();
98 }
99
100 /**
101 * Create a <code>DocumentBuilderFactory</code> that this endpoint will use for constructing XML documents. Can be
102 * overridden in subclasses, adding further initialization of the factory. The resulting
103 * <code>DocumentBuilderFactory</code> is cached, so this method will only be called once.
104 *
105 * @return the DocumentBuilderFactory
106 * @throws ParserConfigurationException if thrown by JAXP methods
107 */
108 protected DocumentBuilderFactory createDocumentBuilderFactory() throws ParserConfigurationException {
109 DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
110 factory.setValidating(validating);
111 factory.setNamespaceAware(namespaceAware);
112 return factory;
113 }
114
115 /**
116 * Returns the payload element of the given source.
117 * <p/>
118 * Default implementation checks whether the source is a {@link DOMSource}, and returns the {@linkplain
119 * DOMSource#getNode() node} of that. In all other cases, or when {@linkplain #setAlwaysTransform(boolean)
120 * alwaysTransform} is {@code true}, the source is transformed into a {@link DOMResult}, which is more expensive. If
121 * the passed source is {@code null}, {@code null} is returned.
122 *
123 * @param source the source to return the root element of; can be {@code null}
124 * @param documentBuilder the document builder to be used for transformations
125 * @return the document element
126 * @throws TransformerException in case of errors
127 */
128 protected Element getDocumentElement(Source source, DocumentBuilder documentBuilder) throws TransformerException {
129 if (source == null) {
130 return null;
131 }
132 if (!alwaysTransform && source instanceof DOMSource) {
133 Node node = ((DOMSource) source).getNode();
134 if (node.getNodeType() == Node.ELEMENT_NODE) {
135 return (Element) node;
136 }
137 else if (node.getNodeType() == Node.DOCUMENT_NODE) {
138 return ((Document) node).getDocumentElement();
139 }
140 }
141 // we have no other option than to transform
142 Document requestDocument = documentBuilder.newDocument();
143 DOMResult domResult = new DOMResult(requestDocument);
144 transform(source, domResult);
145 return requestDocument.getDocumentElement();
146 }
147
148 /**
149 * Template method that subclasses must implement to process the request.
150 * <p/>
151 * <p>Offers the request payload as a DOM <code>Element</code>, and allows subclasses to return a response
152 * <code>Element</code>.
153 * <p/>
154 * <p>The given DOM <code>Document</code> is to be used for constructing <code>Node</code>s, by using the various
155 * <code>create</code> methods.
156 *
157 * @param requestElement the contents of the SOAP message as DOM elements
158 * @param responseDocument a DOM document to be used for constructing <code>Node</code>s
159 * @return the response element. Can be <code>null</code> to specify no response.
160 */
161 protected abstract Element invokeInternal(Element requestElement, Document responseDocument) throws Exception;
162
163 }