View Javadoc

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  	 * [email protected] false}.
74  	 */
75  	public void setExpandEntityReferences(boolean expandEntityRef) {
76  		documentBuilderFactory.setExpandEntityReferences(expandEntityRef);
77  	}
78  
79  
80      /**
81       * Set if the request [email protected] Source} should always be transformed into a new [email protected] DOMResult}.
82       * <p/>
83       * Default is [email protected] 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 [email protected] DOMSource}, and returns the [email protected]
133      * DOMSource#getNode() node} of that. In all other cases, or when [email protected] #setAlwaysTransform(boolean)
134      * alwaysTransform} is [email protected] true}, the source is transformed into a [email protected] DOMResult}, which is more expensive. If
135      * the passed source is [email protected] null}, [email protected] null} is returned.
136      *
137      * @param source          the source to return the root element of; can be [email protected] 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 }