1 /*
2 * Copyright 2002-2013 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 * @deprecated as of Spring Web Services 2.0, in favor of annotated endpoints
47 */
48 @Deprecated
49 public abstract class AbstractDomPayloadEndpoint extends TransformerObjectSupport implements PayloadEndpoint {
50
51 private DocumentBuilderFactory documentBuilderFactory;
52
53 private boolean validating = false;
54
55 private boolean namespaceAware = true;
56
57 private boolean expandEntityReferences = false;
58
59 private boolean alwaysTransform = false;
60
61 /** Set whether or not the XML parser should be XML namespace aware. Default is <code>true</code>. */
62 public void setNamespaceAware(boolean namespaceAware) {
63 this.namespaceAware = namespaceAware;
64 }
65
66 /** Set if the XML parser should validate the document. Default is <code>false</code>. */
67 public void setValidating(boolean validating) {
68 this.validating = validating;
69 }
70
71 /**
72 * Set if the XML parser should expand entity reference nodes. Default is
73 * {@code false}.
74 */
75 public void setExpandEntityReferences(boolean expandEntityRef) {
76 documentBuilderFactory.setExpandEntityReferences(expandEntityRef);
77 }
78
79
80 /**
81 * Set if the request {@link Source} should always be transformed into a new {@link DOMResult}.
82 * <p/>
83 * Default is {@code false}, which is faster.
84 */
85 public void setAlwaysTransform(boolean alwaysTransform) {
86 this.alwaysTransform = alwaysTransform;
87 }
88
89 public final Source invoke(Source request) throws Exception {
90 if (documentBuilderFactory == null) {
91 documentBuilderFactory = createDocumentBuilderFactory();
92 }
93 DocumentBuilder documentBuilder = createDocumentBuilder(documentBuilderFactory);
94 Element requestElement = getDocumentElement(request, documentBuilder);
95 Document responseDocument = documentBuilder.newDocument();
96 Element responseElement = invokeInternal(requestElement, responseDocument);
97 return responseElement != null ? new DOMSource(responseElement) : null;
98 }
99
100 /**
101 * Create a <code>DocumentBuilder</code> that this endpoint will use for parsing XML documents. Can be overridden in
102 * subclasses, adding further initialization of the builder.
103 *
104 * @param factory the <code>DocumentBuilderFactory</code> that the DocumentBuilder should be created with
105 * @return the <code>DocumentBuilder</code>
106 * @throws ParserConfigurationException if thrown by JAXP methods
107 */
108 protected DocumentBuilder createDocumentBuilder(DocumentBuilderFactory factory)
109 throws ParserConfigurationException {
110 return factory.newDocumentBuilder();
111 }
112
113 /**
114 * Create a <code>DocumentBuilderFactory</code> that this endpoint will use for constructing XML documents. Can be
115 * overridden in subclasses, adding further initialization of the factory. The resulting
116 * <code>DocumentBuilderFactory</code> is cached, so this method will only be called once.
117 *
118 * @return the DocumentBuilderFactory
119 * @throws ParserConfigurationException if thrown by JAXP methods
120 */
121 protected DocumentBuilderFactory createDocumentBuilderFactory() throws ParserConfigurationException {
122 DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
123 factory.setValidating(validating);
124 factory.setNamespaceAware(namespaceAware);
125 factory.setExpandEntityReferences(expandEntityReferences);
126 return factory;
127 }
128
129 /**
130 * Returns the payload element of the given source.
131 * <p/>
132 * Default implementation checks whether the source is a {@link DOMSource}, and returns the {@linkplain
133 * DOMSource#getNode() node} of that. In all other cases, or when {@linkplain #setAlwaysTransform(boolean)
134 * alwaysTransform} is {@code true}, the source is transformed into a {@link DOMResult}, which is more expensive. If
135 * the passed source is {@code null}, {@code null} is returned.
136 *
137 * @param source the source to return the root element of; can be {@code null}
138 * @param documentBuilder the document builder to be used for transformations
139 * @return the document element
140 * @throws TransformerException in case of errors
141 */
142 protected Element getDocumentElement(Source source, DocumentBuilder documentBuilder) throws TransformerException {
143 if (source == null) {
144 return null;
145 }
146 if (!alwaysTransform && source instanceof DOMSource) {
147 Node node = ((DOMSource) source).getNode();
148 if (node.getNodeType() == Node.ELEMENT_NODE) {
149 return (Element) node;
150 }
151 else if (node.getNodeType() == Node.DOCUMENT_NODE) {
152 return ((Document) node).getDocumentElement();
153 }
154 }
155 // we have no other option than to transform
156 Document requestDocument = documentBuilder.newDocument();
157 DOMResult domResult = new DOMResult(requestDocument);
158 transform(source, domResult);
159 return requestDocument.getDocumentElement();
160 }
161
162 /**
163 * Template method that subclasses must implement to process the request.
164 * <p/>
165 * <p>Offers the request payload as a DOM <code>Element</code>, and allows subclasses to return a response
166 * <code>Element</code>.
167 * <p/>
168 * <p>The given DOM <code>Document</code> is to be used for constructing <code>Node</code>s, by using the various
169 * <code>create</code> methods.
170 *
171 * @param requestElement the contents of the SOAP message as DOM elements
172 * @param responseDocument a DOM document to be used for constructing <code>Node</code>s
173 * @return the response element. Can be <code>null</code> to specify no response.
174 */
175 protected abstract Element invokeInternal(Element requestElement, Document responseDocument) throws Exception;
176
177 }